org.apache.commons.id.uuid
Class UUID

java.lang.Object
  org.apache.commons.id.uuid.UUID

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable, Constants

public class UUID
extends java.lang.Object
implements Constants, java.io.Serializable, java.lang.Comparable

UUID represents a Universally Unique Identifier per RFC 4122. See the RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace for more information.

Version:

$Revision: 480488 $ $Date: 2006-11-29 08:57:26 +0000 (Wed, 29 Nov 2006) $

Author:

Commons-Id Team

See Also:

Serialized Form

Field Summary

Fields inherited from interface org.apache.commons.id.uuid.Constants

CLOCK_SEQ_HI_AND_RESERVED_BYTE_8, FORMAT_POSITION1, FORMAT_POSITION2, FORMAT_POSITION3, FORMAT_POSITION4, MD5_ENCODING, SHA1_ENCODING, TIME_HI_AND_VERSION_BYTE_6, TIME_HI_BYTE_LEN, TIME_HI_START_POS, TIME_HI_TS_POS, TIME_LOW_BYTE_LEN, TIME_LOW_START_POS, TIME_LOW_TS_POS, TIME_MID_BYTE_LEN, TIME_MID_START_POS, TIME_MID_TS_POS, TOKEN_LENGTHS, TOKENS_IN_UUID, URN_PREFIX, UUID_BIT_LENGTH, UUID_BYTE_LENGTH, UUID_FORMATTED_LENGTH, UUID_UNFORMATTED_LENGTH, VARIANT_FUTURE, VARIANT_IETF_DRAFT, VARIANT_MS, VARIANT_NCS_COMPAT, VERSION_FIVE, VERSION_FOUR, VERSION_ONE, VERSION_THREE, VERSION_TWO, WRONG_VAR_VER_MSG

Constructor Summary

UUID()
Constructs a nil UUID

UUID(byte[] byteArray)
Constructs a UUID from a 16 byte array.

UUID(java.io.DataInput input)
Constructs a UUID from a DataInput.

UUID(long mostSignificant, long leastSignificant)
Constructs a UUID from two long values in most significant byte, and least significant bytes order.

UUID(java.lang.String uuidString)
Constructs a UUID from a UUID formatted String.

UUID(UUID copyFrom)
Copy constructor.

Method Summary

int	clockSequence() Returns the clock sequence value in the UUID.
int	compareTo(java.lang.Object compareTo) Compares two UUID's for equality.
boolean	equals(java.lang.Object obj) Compares two UUID for equality.
static UUID	fromString(java.lang.String uuidString) Parses a string for a UUID.
byte[]	getRawBytes() Returns a copy of the byte values contained in this UUID.
int	hashCode() Returns a hash code value for the object.
static UUID	nameUUIDFromString(java.lang.String name, UUID namespace) Returns a new version three UUID given a name and the namespace's UUID.
static UUID	nameUUIDFromString(java.lang.String name, UUID namespace, java.lang.String encoding) Returns a new version three (MD5) or five (SHA-1) UUID, using the specified encoding given a name and the namespace's UUID.
long	node() Returns the node identifier found in this UUID.
static UUID	randomUUID() Returns a new version 4 UUID, based upon Random bits.
long	timestamp() Returns the timestamp value of the UUID as 100-nano second intervals since the Gregorian change offset (00:00:00.00, 15 October 1582 ).
static UUID	timeUUID() Returns a new version 1 UUID, based upon node identifier and time stamp.
java.lang.String	toString() Returns a string representation of the UUID.
java.lang.String	toUrn() Returns a urn representation of the UUID.
int	variant() Returns the variant field of the UUID.
int	version() Returns the version of the UUID.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

UUID

public UUID()

Constructs a nil UUID

UUID

public UUID(UUID copyFrom)

Copy constructor.

Parameters:

copyFrom - the UUID to copy to create this UUID.

UUID

public UUID(byte[] byteArray)
     throws java.lang.IllegalArgumentException

Constructs a UUID from a 16 byte array.

Parameters:

byteArray - the 16 byte array to construct this UUID from.

Throws:

java.lang.IllegalArgumentException - argument must be 16 bytes

UUID

public UUID(java.io.DataInput input)
     throws java.io.IOException

Constructs a UUID from a DataInput. Note if 16 bytes are not available this method will block.

Parameters:

input - the datainput with 16 bytes to read in from.

Throws:

java.io.IOException - exception if there is an IO problem also argument must contain 16 bytes.

UUID

public UUID(long mostSignificant,
            long leastSignificant)

Constructs a UUID from two long values in most significant byte, and least significant bytes order.

Parameters:

mostSignificant - - the most significant 8 bytes of the uuid to be constructed.

leastSignificant - - the least significant 8 bytes of the uuid to be constructed.

UUID

public UUID(java.lang.String uuidString)
     throws UUIDFormatException

Constructs a UUID from a UUID formatted String.

Parameters:

uuidString - the String representing a UUID to construct this UUID

Throws:

UUIDFormatException - String must be a properly formatted UUID string

Method Detail

fromString

public static UUID fromString(java.lang.String uuidString)
                       throws UUIDFormatException

Parses a string for a UUID.

Parameters:

uuidString - the UUID formatted String to parse.

Returns:

Returns a UUID or null if the formatted string could not be parsed.

Throws:

UUIDFormatException - the String must be a properly formatted UUID String.

toString

public java.lang.String toString()

Returns a string representation of the UUID.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the UUID formatted according to the specification.

toUrn

public java.lang.String toUrn()

Returns a urn representation of the UUID. This is same as the toString() value prefixed with urn:uuid:

Returns:

Returns the urn string representation of the UUID

equals

public boolean equals(java.lang.Object obj)

Compares two UUID for equality.

Overrides:

equals in class java.lang.Object

See Also:

Object.equals(Object)

hashCode

public int hashCode()

Returns a hash code value for the object.

Overrides:

hashCode in class java.lang.Object

See Also:

Object.hashCode()

compareTo

public int compareTo(java.lang.Object compareTo)
              throws java.lang.ClassCastException

Compares two UUID's for equality.

Specified by:

compareTo in interface java.lang.Comparable

Throws:

java.lang.ClassCastException

See Also:

Comparable.compareTo(Object)

clockSequence

public int clockSequence()
                  throws java.lang.UnsupportedOperationException

Returns the clock sequence value in the UUID. The clock sequence is a random assigned to a particular clock instance that generated the time in the timestamp of a time based UUID.

Returns:

the clock sequence value in the UUID.

Throws:

java.lang.UnsupportedOperationException - thrown if this is not a IETF variant or not a time-based UUID.

version

public int version()

Returns the version of the UUID.

• VERSION_ONE - The time-based version
• VERSION_TWO - DCE Security version, with embedded POSIX UIDs.
• VERSION_THREE - Name based UUID with MD5 hashing.
• VERSION_FOUR - Random based UUID.
• VERSION_FIVE - Name based UUID with SHA-1 hashing.

Returns:

the version of the UUID.

variant

public int variant()

Returns the variant field of the UUID.

Returns:

Returns the variant field of the UUID.

See Also:

Constants.VARIANT_NCS_COMPAT, Constants.VARIANT_IETF_DRAFT, Constants.VARIANT_MS, Constants.VARIANT_FUTURE

node

public long node()
          throws java.lang.UnsupportedOperationException

Returns the node identifier found in this UUID. The specification was written such that this value holds the IEEE 802 MAC address. The specification permits this value to be calculated from other sources other than the MAC.

Returns:

the node identifier found in this UUID.

Throws:

java.lang.UnsupportedOperationException - thrown if this is not a IETF variant or not a time-based UUID.

timestamp

public long timestamp()
               throws java.lang.UnsupportedOperationException

Returns the timestamp value of the UUID as 100-nano second intervals since the Gregorian change offset (00:00:00.00, 15 October 1582 ).

Returns:

the timestamp value of the UUID as 100-nano second intervals since the Gregorian change offset.

Throws:

java.lang.UnsupportedOperationException - thrown if this is not a IETF variant or not a time-based UUID.

getRawBytes

public byte[] getRawBytes()

Returns a copy of the byte values contained in this UUID.

Returns:

a copy of the byte values contained in this UUID.

randomUUID

public static UUID randomUUID()

Returns a new version 4 UUID, based upon Random bits.

Returns:

a new version 4 UUID, based upon Random bits.

timeUUID

public static UUID timeUUID()

Returns a new version 1 UUID, based upon node identifier and time stamp.

Returns:

a new version 1 UUID, based upon node identifier and time stamp.

nameUUIDFromString

public static UUID nameUUIDFromString(java.lang.String name,
                                      UUID namespace,
                                      java.lang.String encoding)

Returns a new version three (MD5) or five (SHA-1) UUID, using the specified encoding given a name and the namespace's UUID.

Parameters:

name - String the name to calculate the UUID for.

namespace - UUID assigned to this namespace.

encoding - The encoding to use, either #{link UUID.MD5_ENCODING} or #{link UUID.SHA1_ENCODING}

Returns:

a new version three UUID given a name and the namespace's UUID.

nameUUIDFromString

public static UUID nameUUIDFromString(java.lang.String name,
                                      UUID namespace)

Returns a new version three UUID given a name and the namespace's UUID.

Parameters:

name - String the name to calculate the UUID for.

namespace - UUID assigned to this namespace.

Returns:

a new version three UUID given a name and the namespace's UUID.