net.jini.id
Class Uuid

java.lang.Object
  net.jini.id.Uuid

All Implemented Interfaces:

Serializable

public class Uuid
extends Object
implements Serializable

A 128-bit value to serve as a universally unique identifier. Two Uuids are equal if they have the same 128-bit value. Uuid instances can be created using the static methods of the UuidFactory class.

The design of this class is intended to support the use of universally unique identifiers that

1. have a high likelihood of uniqueness over space and time and
2. are computationally difficult to guess.

The second goal is intended to support the treatment of data containing a Uuid as a capability. Note that not all defined Uuid values imply a generation algorithm that supports this goal.

The most significant 64 bits of the value can be decomposed into unsigned integer fields according to the following bit masks:

 0xFFFFFFFF00000000     time_low
 0x00000000FFFF0000     time_mid
 0x000000000000F000     version
 0x0000000000000FFF     time_hi
 

The least significant 64 bits of the value can be decomposed into unsigned integer fields according to the following bit masks:

 0xC000000000000000     variant
 0x3FFF000000000000     clock_seq
 0x0000FFFFFFFFFFFF     node
 

This specification defines the meaning (and implies aspects of the generation algorithm) of Uuid values if the variant field is 0x2 and the version field is either 0x1 or 0x4.

If the version field is 0x1, then

• the time_low, time_mid, and time_hi fields are the least, middle, and most significant bits (respectively) of a 60-bit timestamp of 100-nanosecond intervals since midnight, October 15, 1582 UTC,
• the clock_seq field is a 14-bit number chosen to help avoid duplicate Uuid values in the event of a changed node address or a backward system clock adjustment (such as a random number when in doubt, or the previously used number incremented by one if just a backward clock adjustment is detected), and
• the node field is an IEEE 802 address (a 48-bit value).

  As an alternative to an IEEE 802 address (such as if one is not available to the generation algorithm), the node field may also be a 48-bit number for which the most significant bit is set to 1 and the remaining bits were produced from a cryptographically strong random sequence.

If the version field is 0x4, then the time_low, time_mid, time_hi, clock_seq, and node fields are values that were produced from a cryptographically strong random sequence.

Only Uuid values with a version field of 0x4 are considered computationally difficult to guess. A Uuid value with a version field of 0x1 should not be treated as a capability.

A subclass of Uuid must not implement Externalizable; this restriction is enforced by this class's constructor and readObject methods.

Since:

2.0

Author:

Sun Microsystems, Inc.

See Also:

Serialized Form

Constructor Summary

Uuid(long bits0, long bits1)
Creates a new Uuid with the specified 128-bit value.

Method Summary

boolean	equals(Object obj) Compares the specified object with this Uuid for equality.
protected void	finalize() Delegates to the superclass's finalize method.
long	getLeastSignificantBits() Returns the least significant 64 bits of this Uuid's 128-bit value.
long	getMostSignificantBits() Returns the most significant 64 bits of this Uuid's 128-bit value.
int	hashCode() Returns the hash code value for this Uuid.
protected Object	readResolve() Returns this object.
String	toString() Returns a string representation of this Uuid.
void	write(OutputStream out) Marshals a binary representation of this Uuid to an OutputStream.
protected Object	writeReplace() Returns this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

Uuid

public Uuid(long bits0,
            long bits1)

Creates a new Uuid with the specified 128-bit value.

Parameters:

bits0 - the most significant 64 bits of the 128-bit value

bits1 - the least significant 64 bits of the 128-bit value

Throws:

SecurityException - if the class of this object implements Externalizable

Method Detail

getMostSignificantBits

public final long getMostSignificantBits()

Returns the most significant 64 bits of this Uuid's 128-bit value.

Returns:

the most significant 64 bits of the 128-bit value

getLeastSignificantBits

public final long getLeastSignificantBits()

Returns the least significant 64 bits of this Uuid's 128-bit value.

Returns:

the least significant 64 bits of the 128-bit value

hashCode

public final int hashCode()

Returns the hash code value for this Uuid.

Overrides:

hashCode in class Object

Returns:

the hash code value for this Uuid

equals

public final boolean equals(Object obj)

Compares the specified object with this Uuid for equality. This method returns true if and only if the specified object is a Uuid instance with the same 128-bit value as this one.

Overrides:

equals in class Object

Parameters:

obj - the object to compare this Uuid to

Returns:

true if the given object is equivalent to this one, and false otherwise

toString

public final String toString()

Returns a string representation of this Uuid.

The string representation is 36 characters long, with five fields of zero-filled, lowercase hexadecimal numbers separated by hyphens. The fields of the string representation are derived from the components of the 128-bit value in the following order:

• time_low (8 hexadecimal digits)
• time_mid (4 hexadecimal digits)
• version and time_hi treated as a single field (4 hexadecimal digits)
• variant and clock_seq treated as a single field (4 hexadecimal digits)
• node (12 hexadecimal digits)

As an example, a Uuid with the 128-bit value

0x0123456789ABCDEF0123456789ABCDEF

would have the following string representation:

01234567-89ab-cdef-0123-456789abcdef

Overrides:

toString in class Object

Returns:

a string representation of this Uuid

write

public final void write(OutputStream out)
                 throws IOException

Marshals a binary representation of this Uuid to an OutputStream.

Specifically, this method writes the 128-bit value to the stream as 16 bytes in network (big-endian) byte order.

Parameters:

out - the OutputStream to write this Uuid to

Throws:

IOException - if an I/O exception occurs while performing this operation

NullPointerException - if out is null

finalize

protected final void finalize()
                       throws Throwable

Delegates to the superclass's finalize method. This method prevents a subclass from declaring an overriding finalize method.

Overrides:

finalize in class Object

Throws:

Throwable - if the superclass's finalize method throws a Throwable

writeReplace

protected final Object writeReplace()

Returns this object. This method prevents a subclass from declaring a writeReplace method with an alternate implementation.

Returns:

this object

readResolve

protected final Object readResolve()

Returns this object. This method prevents a subclass from declaring a readResolve method with an alternate implementation.

Returns:

this object