tyrex.services

Class UUID

public final class UUID extends Object

Universally Unique Identifier (UUID) generator.

A UUID is an identifier that is unique across both space and time, with respect to the space of all UUIDs. A UUID can be used for objects with an extremely short lifetime, and to reliably identifying very persistent objects across a network. UUIDs are 128 bit values and encoded as 36 character identifiers.

This generator produces time-based UUIDs based on the varient specified in a February 4, 1998 IETF draft.

Unprefixed identifiers are generated by calling create. A method is also provided to create prefixed identifiers. Prefixed identifiers are useful for logging and associating identifiers to application objects.

To assure that identifiers can be presisted, identifiers must be kept within the limit of MAXIMUM_LENGTH characters. This includes both prefixed identifiers and identifiers created by the application. The trim method can be used to trim an identifier to the maximum allowed length. If an* identifier was generated with no prefix, or with the maximum supported prefix legnth, the identifier is guaranteed to be short enough and this method is not required.

Convenience methods are also provided for converting an identifier to and from an array of bytes. The conversion methods assume that the identifier is a prefixed or unprefixed encoding of the byte array as pairs of hexadecimal digits.

The UUID specification prescribes the following format for representing UUIDs. Four octets encode the low field of the time stamp, two octects encode the middle field of the timestamp, and two octets encode the high field of the timestamp with the version number. Two octets encode the clock sequence number and six octets encode the unique node identifier.

The timestamp is a 60 bit value holding UTC time as a count of 100 nanosecond intervals since October 15, 1582. UUIDs generated in this manner are guaranteed not to roll over until 3400 AD.

The clock sequence is used to help avoid duplicates that could arise when the clock is set backward in time or if the node ID changes. Although the system clock is guaranteed to be monotonic, the system clock is not guaranteed to be monotonic across system failures. The UUID cannot be sure that no UUIDs were generated with timestamps larger than the current timestamp.

If the clock sequence can be determined at initialization, it is incremented by one, otherwise it is set to a random number. The clock sequence MUST be originally (i.e. once in the lifetime of a system) initialized to a random number to minimize the correlation across systems. The initial value must not be correlated to the node identifier.

The node identifier must be unique for each UUID generator. This is accomplished using the IEEE 802 network card address. For systems with multiple IEEE 802 addresses, any available address can be used. For systems with no IEEE address, a 47 bit random value is used and the multicast bit is set so it will never conflict with addresses obtained from network cards.

The UUID state consists of the node identifier and clock sequence. The state need only be read once when the generator is initialized, and the clock sequence must be incremented and stored back. If the UUID state cannot be read and updated, a random number is used.

The UUID state is maintained in a fail called UUID_STATE_FILE. The file name can be overriden from the configuration property PROPERTY_UUID_STATE_FILE. The UUID state file contains two properties. The node identifier (PROPERTY_NODE_IDENTIFIER) is a 47 bit hexadecimal value. The clock sequence (PROPERTY_CLOCK_SEQUENCE is a 12 bit hexadecimal value.

The UUID generator is thread-safe and consumes a single thread.

Version: $Revision: 1.7 $ $Date: 2004/04/30 06:34:13 $

Author: Assaf Arkin

Nested Class Summary
static classUUID.InvalidIDException
An exception indicating the identifier is invalid and cannot be converted into an array of bytes.
Field Summary
static intMAXIMUM_LENGTH
The maximum length of an identifier in textual form.
static intMAXIMUM_PREFIX
The maximum length of an identifier prefix.
static StringPREFIX
Default prefix that can be used by identifiers.
static StringPROPERTY_CLOCK_SEQUENCE
UUID state file property that determined the clock sequence.
static StringPROPERTY_NODE_IDENTIFIER
UUID state file property that determined the node identifier.
static intRESOLUTION_BYTES
The identifier resolution in bytes.
static StringUUID_STATE_FILE
Name of the UUID state file.
Method Summary
static Stringcreate()
Creates and returns a new identifier.
static Stringcreate(String prefix)
Creates and returns a new prefixed identifier.
static byte[]createBinary()
Creates and returns a new identifier.
static byte[]createTimeUUIDBytes()
Returns a time-based UUID as a character array.
static char[]createTimeUUIDChars()
Returns a time-based UUID as a character array.
static StringfromBytes(String prefix, byte[] bytes)
Converts a byte array into a prefixed identifier.
static StringfromBytes(byte[] bytes)
Converts a byte array into an identifier.
static booleanisLocal(byte[] uuid)
Returns true if the UUID was created on this machine.
static voidmain(String[] args)
static byte[]toBytes(String prefix, String identifier)
Converts a prefixed identifier into a byte array.
static byte[]toBytes(String identifier)
Converts an identifier into a byte array.
static Stringtrim(String identifier)
Truncates an identifier so that it does not extend beyond MAXIMUM_LENGTH characters in length.

Field Detail

MAXIMUM_LENGTH

public static final int MAXIMUM_LENGTH
The maximum length of an identifier in textual form. Prefixed identifiers and application identifiers must be less or equal to the maximum length to allow persistence. This maximum length is 64 characters.

MAXIMUM_PREFIX

public static final int MAXIMUM_PREFIX
The maximum length of an identifier prefix. Identifiers created using create(String) with a prefix that is no longer than the maximum prefix size are guaranteed to be within the maximum length allowed and need not be trimmed.

PREFIX

public static final String PREFIX
Default prefix that can be used by identifiers. This prefix is not added to identifiers created using create. Identifiers created using create(String) may use this prefix to denote an identifier. The value of this variable is ID:.

PROPERTY_CLOCK_SEQUENCE

public static final String PROPERTY_CLOCK_SEQUENCE
UUID state file property that determined the clock sequence. The value of this property is an hexadecimal 12-bit value. The name of this property is uuid.clockSequence.

PROPERTY_NODE_IDENTIFIER

public static final String PROPERTY_NODE_IDENTIFIER
UUID state file property that determined the node identifier. The value of this property is an hexadecimal 47-bit value. The name of this property is uuid.nodeIdentifier.

RESOLUTION_BYTES

public static final int RESOLUTION_BYTES
The identifier resolution in bytes. Identifiers are 16-byte long, or 128 bits. Without a prefix, an identifier can be represented as 36 hexadecimal digits and hyphens. (4 hyphens are used in the UUID format)

UUID_STATE_FILE

public static final String UUID_STATE_FILE
Name of the UUID state file. If no file was specified in the configuration properties, this file name is used. The file name is uuid.state.

Method Detail

create

public static String create()
Creates and returns a new identifier.

Returns: An identifier

create

public static String create(String prefix)
Creates and returns a new prefixed identifier.

This method is equivalent to prefix + create().

Parameters: prefix The prefix to use

Returns: A prefixed identifier

createBinary

public static byte[] createBinary()
Creates and returns a new identifier.

Returns: An identifier

createTimeUUIDBytes

public static byte[] createTimeUUIDBytes()
Returns a time-based UUID as a character array. The UUID identifier is always 16 bytes long.

Returns: A time-based UUID

createTimeUUIDChars

public static char[] createTimeUUIDChars()
Returns a time-based UUID as a character array. The UUID identifier is always 36 characters long.

Returns: A time-based UUID

fromBytes

public static String fromBytes(String prefix, byte[] bytes)
Converts a byte array into a prefixed identifier.

The format for the identifier is prefix{nn|-}*: a prefix followed by a sequence of bytes, optionally separated by hyphens. Each byte is encoded as a pair of hexadecimal digits.

Parameters: prefix The identifier prefix byte An array of bytes

Returns: A string representation of the identifier

fromBytes

public static String fromBytes(byte[] bytes)
Converts a byte array into an identifier.

The format for the identifier is {nn|-}*: a sequence of bytes, optionally separated by hyphens. Each byte is encoded as a pair of hexadecimal digits.

Parameters: byte An array of bytes

Returns: A string representation of the identifier

isLocal

public static boolean isLocal(byte[] uuid)
Returns true if the UUID was created on this machine. Determines the source of the UUID based on the node identifier.

Parameters: uuid The UUID as a byte array

Returns: True if created on this machine

main

public static void main(String[] args)

toBytes

public static byte[] toBytes(String prefix, String identifier)
Converts a prefixed identifier into a byte array. An exception is thrown if the identifier does not match the excepted textual encoding.

The format for the identifier is prefix{nn|-}*: a prefix followed by a sequence of bytes, optionally separated by hyphens. Each byte is encoded as a pair of hexadecimal digits.

Parameters: prefix The identifier prefix identifier The prefixed identifier

Returns: The identifier as an array of bytes

Throws: InvalidIDException The identifier does not begin with the prefix, or does not consist of a sequence of hexadecimal digit pairs, optionally separated by hyphens

toBytes

public static byte[] toBytes(String identifier)
Converts an identifier into a byte array. An exception is thrown if the identifier does not match the excepted textual encoding.

The format for the identifier is {nn|-}*: a sequence of bytes, optionally separated by hyphens. Each byte is encoded as a pair of hexadecimal digits.

Parameters: identifier The identifier

Returns: The identifier as an array of bytes

Throws: InvalidIDException The identifier does not consist of a sequence of hexadecimal digit pairs, optionally separated by hyphens

trim

public static String trim(String identifier)
Truncates an identifier so that it does not extend beyond MAXIMUM_LENGTH characters in length.

Parameters: identifier An identifier

Returns: An identifier trimmed to MAXIMUM_LENGTH characters

Original code is Copyright (c) 1999-2001, Intalio, Inc. All Rights Reserved. Contributions by MetaBoss team are Copyright (c) 2003-2005, Softaris Pty. Ltd. All Rights Reserved.