org.doomdark.uuid
Class UUID

java.lang.Object
  extended by org.doomdark.uuid.UUID
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.lang.Comparable

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

UUID represents Universally Unique Identifiers (aka Global UID in Windows world). UUIDs are usually generated via UUIDGenerator (or in case of 'Null UUID', 16 zero bytes, via static method getNullUUID()), or received from external systems. By default class caches the string presentations of UUIDs so that description is only created the first time it's needed. For memory stingy applications this caching can be turned off (note though that if uuid.toString() is never called, desc is never calculated so only loss is the space allocated for the desc pointer... which can of course be commented out to save memory). Similarly, hash code is calculated when it's needed for the first time, and from thereon that value is just returned. This means that using UUIDs as keys should be reasonably efficient. UUIDs can be compared for equality, serialized, cloned and even sorted. Equality is a simple bit-wise comparison. Ordering (for sorting) is done by first ordering based on type (in the order of numeric values of types), secondarily by time stamp (only for time-based time stamps), and finally by straight numeric byte-by-byte comparison (from most to least significant bytes).

See Also:
Serialized Form

Field Summary
static byte INDEX_CLOCK_HI
           
static byte INDEX_CLOCK_LO
           
static byte INDEX_CLOCK_MID
           
static byte INDEX_CLOCK_SEQUENCE
           
static byte INDEX_TYPE
           
static byte INDEX_VARIATION
           
static java.lang.String NAMESPACE_DNS
           
static java.lang.String NAMESPACE_OID
           
static java.lang.String NAMESPACE_URL
           
static java.lang.String NAMESPACE_X500
           
static byte TYPE_DCE
           
static byte TYPE_NAME_BASED
           
static byte TYPE_NULL
           
static byte TYPE_RANDOM_BASED
           
static byte TYPE_TIME_BASED
           
 
Constructor Summary
UUID()
          Default constructor creates a NIL UUID, one that contains all zeroes Note that the clearing of array is actually unnecessary as JVMs are required to clear up the allocated arrays by default.
UUID(byte[] data)
          Constructor for cases where you already have the 16-byte binary representation of the UUID (for example if you save UUIDs binary takes less than half of space string representation takes).
UUID(byte[] data, int start)
          Constructor for cases where you already have the binary representation of the UUID (for example if you save UUIDs binary takes less than half of space string representation takes) in a byte array
UUID(java.lang.String id)
          Constructor for creating UUIDs from the canonical string representation Note that implementation is optimized for speed, not necessarily code clarity...
 
Method Summary
 byte[] asByteArray()
          Returns the UUID as a 16-byte byte array
 java.lang.Object clone()
          Default cloning behaviour (bitwise copy) is just fine...
 int compareTo(java.lang.Object o)
          Let's also make UUIDs sortable.
 boolean equals(java.lang.Object o)
          Checking equality of UUIDs is easy; just compare the 128-bit number.
static UUID getNullUUID()
          Accessor for getting the shared null UUID
 int getType()
          Returns the UUID type code
 int hashCode()
           
 boolean isNullUUID()
           
static void main(java.lang.String[] args)
           
static void setDescCaching(boolean state)
           
 byte[] toByteArray()
          'Synonym' for 'asByteArray'
 void toByteArray(byte[] dst)
           
 void toByteArray(byte[] dst, int pos)
          Fills in the 16 bytes (from index pos) of the specified byte array with the UUID contents.
 java.lang.String toString()
           
static UUID valueOf(byte[] src)
          Constructs a new UUID instance given a byte array that contains the (16 byte) binary representation.
static UUID valueOf(byte[] src, int start)
          Constructs a new UUID instance given a byte array that contains the (16 byte) binary representation.
static UUID valueOf(java.lang.String id)
          Constructs a new UUID instance given the canonical string representation of an UUID.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

INDEX_CLOCK_HI

public static final byte INDEX_CLOCK_HI
See Also:
Constant Field Values

INDEX_CLOCK_MID

public static final byte INDEX_CLOCK_MID
See Also:
Constant Field Values

INDEX_CLOCK_LO

public static final byte INDEX_CLOCK_LO
See Also:
Constant Field Values

INDEX_TYPE

public static final byte INDEX_TYPE
See Also:
Constant Field Values

INDEX_CLOCK_SEQUENCE

public static final byte INDEX_CLOCK_SEQUENCE
See Also:
Constant Field Values

INDEX_VARIATION

public static final byte INDEX_VARIATION
See Also:
Constant Field Values

TYPE_NULL

public static final byte TYPE_NULL
See Also:
Constant Field Values

TYPE_TIME_BASED

public static final byte TYPE_TIME_BASED
See Also:
Constant Field Values

TYPE_DCE

public static final byte TYPE_DCE
See Also:
Constant Field Values

TYPE_NAME_BASED

public static final byte TYPE_NAME_BASED
See Also:
Constant Field Values

TYPE_RANDOM_BASED

public static final byte TYPE_RANDOM_BASED
See Also:
Constant Field Values

NAMESPACE_DNS

public static final java.lang.String NAMESPACE_DNS
See Also:
Constant Field Values

NAMESPACE_URL

public static final java.lang.String NAMESPACE_URL
See Also:
Constant Field Values

NAMESPACE_OID

public static final java.lang.String NAMESPACE_OID
See Also:
Constant Field Values

NAMESPACE_X500

public static final java.lang.String NAMESPACE_X500
See Also:
Constant Field Values
Constructor Detail

UUID

public UUID()
Default constructor creates a NIL UUID, one that contains all zeroes Note that the clearing of array is actually unnecessary as JVMs are required to clear up the allocated arrays by default.


UUID

public UUID(byte[] data)
Constructor for cases where you already have the 16-byte binary representation of the UUID (for example if you save UUIDs binary takes less than half of space string representation takes).

Parameters:
data - array that contains the binary representation of UUID

UUID

public UUID(byte[] data,
            int start)
Constructor for cases where you already have the binary representation of the UUID (for example if you save UUIDs binary takes less than half of space string representation takes) in a byte array

Parameters:
data - array that contains the binary representation of UUID
start - byte offset where UUID starts

UUID

public UUID(java.lang.String id)
     throws java.lang.NumberFormatException
Constructor for creating UUIDs from the canonical string representation Note that implementation is optimized for speed, not necessarily code clarity... Also, since what we get might not be 100% canonical (see below), let's not yet populate mDesc here.

Parameters:
id - String that contains the canonical representation of the UUID to build; 36-char string (see UUID specs for details). Hex-chars may be in upper-case too; UUID class will always output them in lowercase.
Throws:
java.lang.NumberFormatException
Method Detail

clone

public java.lang.Object clone()
Default cloning behaviour (bitwise copy) is just fine... Could clear out cached string presentation, but there's probably no point in doing that.

Overrides:
clone in class java.lang.Object

setDescCaching

public static void setDescCaching(boolean state)

getNullUUID

public static UUID getNullUUID()
Accessor for getting the shared null UUID

Returns:
the shared null UUID

isNullUUID

public boolean isNullUUID()

getType

public int getType()
Returns the UUID type code

Returns:
UUID type

asByteArray

public byte[] asByteArray()
Returns the UUID as a 16-byte byte array

Returns:
16-byte byte array that contains UUID bytes in the network byte order

toByteArray

public void toByteArray(byte[] dst,
                        int pos)
Fills in the 16 bytes (from index pos) of the specified byte array with the UUID contents.

Parameters:
dst - Byte array to fill
pos - Offset in the array

toByteArray

public void toByteArray(byte[] dst)

toByteArray

public byte[] toByteArray()
'Synonym' for 'asByteArray'


hashCode

public int hashCode()
Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

compareTo

public int compareTo(java.lang.Object o)
Let's also make UUIDs sortable. This will mostly/only be useful with time-based UUIDs; they will sorted by time of creation. The order will be strictly correct with UUIDs produced over one JVM's lifetime; that is, if more than one JVMs create UUIDs and/or system is rebooted the order may not be 100% accurate between UUIDs created under different JVMs. For all UUIDs, type is first compared, and UUIDs of different types are sorted together (ie. null UUID is before all other UUIDs, then time-based UUIDs etc). If types are the same, time-based UUIDs' time stamps (including additional clock counter) are compared, so UUIDs created first are ordered first. For all other types (and for time-based UUIDs with same time stamp, which should only occur when comparing a UUID with itself, or with UUIDs created on different JVMs or external systems) binary comparison is done over all 16 bytes.

Specified by:
compareTo in interface java.lang.Comparable
Parameters:
o - Object to compare this UUID to; should be a UUID
Returns:
-1 if this UUID should be ordered before the one passed, 1 if after, and 0 if they are the same
Throws:
java.lang.ClassCastException - if o is not a UUID.

equals

public boolean equals(java.lang.Object o)
Checking equality of UUIDs is easy; just compare the 128-bit number.

Overrides:
equals in class java.lang.Object

valueOf

public static UUID valueOf(java.lang.String id)
                    throws java.lang.NumberFormatException
Constructs a new UUID instance given the canonical string representation of an UUID. Note that calling this method returns the same result as would using the matching (1 string arg) constructor.

Parameters:
id - Canonical string representation used for constructing an UUID instance
Throws:
java.lang.NumberFormatException - if 'id' is invalid UUID

valueOf

public static UUID valueOf(byte[] src,
                           int start)
Constructs a new UUID instance given a byte array that contains the (16 byte) binary representation. Note that calling this method returns the same result as would using the matching constructor

Parameters:
src - Byte array that contains the UUID definition
offset - Offset in the array where the UUID starts

valueOf

public static UUID valueOf(byte[] src)
Constructs a new UUID instance given a byte array that contains the (16 byte) binary representation. Note that calling this method returns the same result as would using the matching constructor

Parameters:
src - Byte array that contains the UUID definition
offset - Offset in the array where the UUID starts

main

public static void main(java.lang.String[] args)


Copyright © 2003 MBARI.

The Monterey Bay Aquarium Research Institute (MBARI) provides this documentation and code "as is", with no warranty, express or implied, of its quality or consistency. It is provided without support and without obligation on the part of MBARI to assist in its use, correction, modification, or enhancement.