org.exolab.jms.common.uuid
Class UUIDGenerator

java.lang.Object
  |
  +--org.exolab.jms.common.uuid.UUIDGenerator

public final class UUIDGenerator

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 generator is thread-safe.

This class originally came from Tyrex: http://tyrex.sourceforge.net

Version:

$Revision: 1.1 $ $Date: 2004/11/26 01:50:35 $

Author:

Assaf Arkin

Inner Class Summary

static class

UUIDGenerator.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 int	RESOLUTION_BYTES /** The identifier resolution in bytes.

Constructor Summary

UUIDGenerator()

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

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)

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.

Constructor Detail

UUIDGenerator

public UUIDGenerator()

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 UUIDGenerator.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:

UUIDGenerator.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 UUIDGenerator.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:

UUIDGenerator.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

byte - An array of bytes

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.

Parameters:

bytes - An array of bytes

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)