com.stafney
Class UID

java.lang.Object
  |
  +--com.stafney.UID

All Implemented Interfaces:

java.lang.Comparable, java.io.Serializable

public class UID

extends java.lang.Object

implements java.io.Serializable, java.lang.Comparable

Immutable unique identifier. Uses JNI to create a universally unique identifier (UUID) or, in the absence of the JNI layer, a locally unique identifier (LUID). LUID's are guaranteed to be uniuqe only within the confines of the VM that created them. To use the JNI layer:

• A JNI library must exist for the platform being used
• The JNI library must be located where the default library search mechanism for the platform being used can find it
• The SecurityManager (if used) must have the java.lang.RuntimePermission "loadLibrary.natvuuid" permission enabled:

The current non JNI version attempts to adhere to the DCE UUID algorithm as closely as possible. It should be used with caution as it falls short in two areas:

• The JDK makes it virtually impossible to retrieve the MAC address of a NIC (so I cheat and use IP address)
• As the JDK does not support nanoseconds, duplicates can occur if:
  • The 4 least significant bytes of the longs used to generate the timestamp/sequence data can wrap if many UID's are created in rapid succession (eg. on a VERY fast machine!)
  • Multiple VM's execute the static initializers of the UID class at the same millisecond and attempt to generate their respective Nth UID at the same millisecond

As for performance, both the JNI and non-JNI versions (running on my PIII 600) create about 90000 UID's per second. Part of my test harness (for the non-JNI version) uses 2 threads each creating 150000 UID's then merges the lists and looks for duplicates. I have yet to get duplicates.

As of version 1.0 there is a JNI layer for Windows and Linux >= 7.0

NOTE: Fixed, with #getAddr(), a "feature" with 1.4 VM's that slowed multiple UID generations to a crawl.

Since:

1.0

Version:

1.1

Author:

Todd Stafney

See Also:

Serialized Form

Field Summary

static byte	GUID_BYTE_SIZE The byte size of a UID
protected static long	serialVersionUID Self manage our serialization version.

Method Summary

int	compareTo(java.lang.Object o)
boolean	equals(java.lang.Object o)
byte[]	getBytes() Get the bytes that comprise this UID
int	hashCode()
boolean	isDeferred() Determine if this UID was deferred to the OS for creation.
boolean	isUUID() Determine if this UID is locally unique or universally unique.
static UID	newInstance() Construct a new UID
java.lang.String	toString() The string representation of this UID in the form D45FD2FC-5C6E-11D1-9EC1-00C04FD7081F.
static UID	valueOf(byte[] bytes) Construct a UID from an array of bytes.
static UID	valueOf(java.lang.String guidStr) Construct a UID from a string in the form D45FD2FC-5C6E-11D1-9EC1-00C04FD7081F or {D45FD2FC-5C6E-11D1-9EC1-00C04FD7081F}.

Methods inherited from class java.lang.Object

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

Field Detail

GUID_BYTE_SIZE

public static final byte GUID_BYTE_SIZE

The byte size of a UID

See Also:

Constant Field Values

serialVersionUID

protected static final long serialVersionUID

Self manage our serialization version.

See Also:

Constant Field Values

Method Detail

valueOf

public static UID valueOf(byte[] bytes)
                   throws java.lang.NullPointerException,
                          java.lang.IllegalArgumentException

Construct a UID from an array of bytes. Note that using this method will not allow a proper determination of the UUID/LUID setting (so LUID is assumed).

Parameters:

bytes - the byte representation of a UID.

Returns:

the UID

Throws:

java.lang.NullPointerException - if the UID string is null

IllegalAgrumentException - if the UID string in incorrectly formatted

java.lang.IllegalArgumentException

Since:

1.0

valueOf

public static UID valueOf(java.lang.String guidStr)
                   throws java.lang.NullPointerException,
                          java.lang.IllegalArgumentException

Construct a UID from a string in the form D45FD2FC-5C6E-11D1-9EC1-00C04FD7081F or {D45FD2FC-5C6E-11D1-9EC1-00C04FD7081F}. Note that using this method will not allow proper determination of the UUID/LUID setting (so LUID is assumed).

Parameters:

guidStr - a string representation of a UID.

Returns:

the UID

Throws:

java.lang.NullPointerException - if the UID string is null

IllegalAgrumentException - if the UID string in incorrectly formatted

java.lang.IllegalArgumentException

Since:

1.0

newInstance

public static UID newInstance()

Construct a new UID

Since:

1.0

isUUID

public boolean isUUID()

Determine if this UID is locally unique or universally unique. Non-JNI created UIDs will (until a standard nanosecond implementation makes it into the Java SDK) always never be universally unique. Likewise, some platform implementations may limit the JNI layer to creating locally unique identifiers as well (for instance a Windows OS with out a NIC).

Returns:

true if universally unique; false if localy unique.

Since:

1.0

isDeferred

public boolean isDeferred()

Determine if this UID was deferred to the OS for creation.

Returns:

true if universally unique; false if localy unique.

Since:

1.0

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

Since:

1.0

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

Since:

1.0

compareTo

public int compareTo(java.lang.Object o)

Specified by:

compareTo in interface java.lang.Comparable

Since:

1.0

getBytes

public byte[] getBytes()

Get the bytes that comprise this UID

Returns:

bytes of the UID

Since:

1.0

toString

public java.lang.String toString()

The string representation of this UID in the form D45FD2FC-5C6E-11D1-9EC1-00C04FD7081F.

Overrides:

toString in class java.lang.Object

Returns:

the UID as a string

Since:

1.0