tyrex.services
public final class UUID extends Object
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 $
Nested Class Summary | |
---|---|
static class | UUID.InvalidIDException
An exception indicating the identifier is invalid and
cannot be converted into an array of bytes. |
Field Summary | |
---|---|
static int | MAXIMUM_LENGTH
The maximum length of an identifier in textual form.
|
static int | MAXIMUM_PREFIX
The maximum length of an identifier prefix. |
static String | PREFIX
Default prefix that can be used by identifiers.
|
static String | PROPERTY_CLOCK_SEQUENCE
UUID state file property that determined the clock sequence.
|
static String | PROPERTY_NODE_IDENTIFIER
UUID state file property that determined the node identifier.
|
static int | RESOLUTION_BYTES
The identifier resolution in bytes. |
static String | UUID_STATE_FILE
Name of the UUID state file. |
Method Summary | |
---|---|
static String | create()
Creates and returns a new identifier.
|
static String | create(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 String | fromBytes(String prefix, byte[] bytes)
Converts a byte array into a prefixed identifier.
|
static String | fromBytes(byte[] bytes)
Converts a byte array into an identifier.
|
static boolean | isLocal(byte[] uuid)
Returns true if the UUID was created on this machine.
|
static void | main(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 String | trim(String identifier)
Truncates an identifier so that it does not extend beyond
MAXIMUM_LENGTH characters in length.
|
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. create
. Identifiers created using create(String)
may use this prefix to
denote an identifier. The value of this variable is
ID:
.Returns: An identifier
This method is equivalent to prefix + create()
.
Parameters: prefix The prefix to use
Returns: A prefixed identifier
Returns: An identifier
Returns: A time-based UUID
Returns: A time-based UUID
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
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
Parameters: uuid The UUID as a byte array
Returns: True if created on this machine
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
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
Parameters: identifier An identifier
Returns: An identifier trimmed to MAXIMUM_LENGTH characters