org.apache.commons.id.uuid
Class UUID

java.lang.Object
  extended by 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.

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.


Copyright 2003-2008 The Apache Software Foundation. All Rights Reserved.