tyrex.services
Class UUID

java.lang.Object
  tyrex.services.UUID

public final class UUID

extends java.lang.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 Configuration.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 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 java.lang.String	PREFIX Default prefix that can be used by identifiers.
static java.lang.String	PROPERTY_CLOCK_SEQUENCE UUID state file property that determined the clock sequence.
static java.lang.String	PROPERTY_NODE_IDENTIFIER UUID state file property that determined the node identifier.
static int	RESOLUTION_BYTES The identifier resolution in bytes.
static java.lang.String	UUID_STATE_FILE Name of the UUID state file.

Constructor Summary

UUID()

Method Summary

static java.lang.String	create() Creates and returns a new identifier.
static java.lang.String	create(java.lang.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 java.lang.String	fromBytes(byte[] bytes) Converts a byte array into an identifier.
static java.lang.String	fromBytes(java.lang.String prefix, byte[] bytes) Converts a byte array into a prefixed identifier.
static boolean	isLocal(byte[] uuid) Returns true if the UUID was created on this machine.
static void	main(java.lang.String[] args)
static byte[]	toBytes(java.lang.String identifier) Converts an identifier into a byte array.
static byte[]	toBytes(java.lang.String prefix, java.lang.String identifier) Converts a prefixed identifier into a byte array.
static java.lang.String	trim(java.lang.String identifier) Truncates an identifier so that it does not extend beyond MAXIMUM_LENGTH characters in length.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PREFIX

public static final java.lang.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:.

See Also:

Constant Field Values

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)

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

PROPERTY_NODE_IDENTIFIER

public static final java.lang.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.

See Also:

Constant Field Values

PROPERTY_CLOCK_SEQUENCE

public static final java.lang.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.

See Also:

Constant Field Values

UUID_STATE_FILE

public static final java.lang.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.

See Also:

Constant Field Values

Constructor Detail

UUID

public UUID()

Method Detail

create

public static java.lang.String create()

Creates and returns a new identifier.

Returns:

An identifier

create

public static java.lang.String create(java.lang.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

toBytes

public static byte[] toBytes(java.lang.String prefix,
                             java.lang.String identifier)
                      throws UUID.InvalidIDException

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:

UUID.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(java.lang.String identifier)
                      throws UUID.InvalidIDException

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:

UUID.InvalidIDException - The identifier does not consist of a sequence of hexadecimal digit pairs, optionally separated by hyphens

fromBytes

public static java.lang.String fromBytes(java.lang.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

Returns:

A string representation of the identifier

fromBytes

public static java.lang.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.

Returns:

A string representation of the identifier

trim

public static java.lang.String trim(java.lang.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

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

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

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(java.lang.String[] args)