FileDocCategorySizeDatePackage
UUID.javaAPI DocJava SE 5 API16510Fri Aug 26 14:57:24 BST 2005java.util

UUID

public final class UUID extends Object implements Comparable, Serializable
A class that represents an immutable universally unique identifier (UUID). A UUID represents a 128-bit value.

There exist different variants of these global identifiers. The methods of this class are for manipulating the Leach-Salz variant, although the constructors allow the creation of any variant of UUID (described below).

The layout of a variant 2 (Leach-Salz) UUID is as follows: The most significant long consists of the following unsigned fields:

0xFFFFFFFF00000000 time_low
0x00000000FFFF0000 time_mid
0x000000000000F000 version
0x0000000000000FFF time_hi
The least significant long consists of the following unsigned fields:
0xC000000000000000 variant
0x3FFF000000000000 clock_seq
0x0000FFFFFFFFFFFF node

The variant field contains a value which identifies the layout of the UUID. The bit layout described above is valid only for a UUID with a variant value of 2, which indicates the Leach-Salz variant.

The version field holds a value that describes the type of this UUID. There are four different basic types of UUIDs: time-based, DCE security, name-based, and randomly generated UUIDs. These types have a version value of 1, 2, 3 and 4, respectively.

For more information including algorithms used to create UUIDs, see the Internet-Draft UUIDs and GUIDs or the standards body definition at ISO/IEC 11578:1996.

version
1.14, 07/12/04
since
1.5

Fields Summary
private static final long
serialVersionUID
Explicit serialVersionUID for interoperability.
private final long
mostSigBits
private final long
leastSigBits
private transient int
version
private transient int
variant
private volatile transient long
timestamp
private transient int
sequence
private transient long
node
private transient int
hashCode
private static volatile SecureRandom
numberGenerator
Constructors Summary
private UUID(byte[] data)


    // Constructors and Factories

    /*
     * Private constructor which uses a byte array to construct the new UUID.
     */
       
        long msb = 0;
        long lsb = 0;
        assert data.length == 16;
        for (int i=0; i<8; i++)
            msb = (msb << 8) | (data[i] & 0xff);
        for (int i=8; i<16; i++)
            lsb = (lsb << 8) | (data[i] & 0xff);
        this.mostSigBits = msb;
        this.leastSigBits = lsb;
    
public UUID(long mostSigBits, long leastSigBits)
Constructs a new UUID using the specified data. mostSigBits is used for the most significant 64 bits of the UUID and leastSigBits becomes the least significant 64 bits of the UUID.

param
mostSigBits
param
leastSigBits

        this.mostSigBits = mostSigBits;
        this.leastSigBits = leastSigBits;
    
Methods Summary
public intclockSequence()
The clock sequence value associated with this UUID.

The 14 bit clock sequence value is constructed from the clock sequence field of this UUID. The clock sequence field is used to guarantee temporal uniqueness in a time-based UUID.

The clockSequence value is only meaningful in a time-based UUID, which has version type 1. If this UUID is not a time-based UUID then this method throws UnsupportedOperationException.

return
the clock sequence of this UUID.
throws
UnsupportedOperationException if this UUID is not a version 1 UUID.

        if (version() != 1) {
            throw new UnsupportedOperationException("Not a time-based UUID");
        }
        if (sequence < 0) {
            sequence = (int)((leastSigBits & 0x3FFF000000000000L) >>> 48);
        }
        return sequence;
    
public intcompareTo(java.util.UUID val)
Compares this UUID with the specified UUID.

The first of two UUIDs follows the second if the most significant field in which the UUIDs differ is greater for the first UUID.

param
val UUID to which this UUID is to be compared.
return
-1, 0 or 1 as this UUID is less than, equal to, or greater than val.

        // The ordering is intentionally set up so that the UUIDs
        // can simply be numerically compared as two numbers
        return (this.mostSigBits < val.mostSigBits ? -1 : 
                (this.mostSigBits > val.mostSigBits ? 1 :
                 (this.leastSigBits < val.leastSigBits ? -1 :
                  (this.leastSigBits > val.leastSigBits ? 1 :
                   0))));
    
private static java.lang.Stringdigits(long val, int digits)
Returns val represented by the specified number of hex digits.

	long hi = 1L << (digits * 4);
	return Long.toHexString(hi | (val & (hi - 1))).substring(1);
    
public booleanequals(java.lang.Object obj)
Compares this object to the specified object. The result is true if and only if the argument is not null, is a UUID object, has the same variant, and contains the same value, bit for bit, as this UUID.

param
obj the object to compare with.
return
true if the objects are the same; false otherwise.

	if (!(obj instanceof UUID))
	    return false;
        if (((UUID)obj).variant() != this.variant())
            return false;
        UUID id = (UUID)obj;
	return (mostSigBits == id.mostSigBits &&
                leastSigBits == id.leastSigBits);
    
public static java.util.UUIDfromString(java.lang.String name)
Creates a UUID from the string standard representation as described in the {@link #toString} method.

param
name a string that specifies a UUID.
return
a UUID with the specified value.
throws
IllegalArgumentException if name does not conform to the string representation as described in {@link #toString}.

        String[] components = name.split("-");
        if (components.length != 5)
            throw new IllegalArgumentException("Invalid UUID string: "+name);
        for (int i=0; i<5; i++)
            components[i] = "0x"+components[i];

        long mostSigBits = Long.decode(components[0]).longValue();
        mostSigBits <<= 16;
        mostSigBits |= Long.decode(components[1]).longValue();
        mostSigBits <<= 16;
        mostSigBits |= Long.decode(components[2]).longValue();

        long leastSigBits = Long.decode(components[3]).longValue();
        leastSigBits <<= 48;
        leastSigBits |= Long.decode(components[4]).longValue();

        return new UUID(mostSigBits, leastSigBits);
    
public longgetLeastSignificantBits()
Returns the least significant 64 bits of this UUID's 128 bit value.

return
the least significant 64 bits of this UUID's 128 bit value.

        return leastSigBits;
    
public longgetMostSignificantBits()
Returns the most significant 64 bits of this UUID's 128 bit value.

return
the most significant 64 bits of this UUID's 128 bit value.

        return mostSigBits;
    
public inthashCode()
Returns a hash code for this UUID.

return
a hash code value for this UUID.

        if (hashCode == -1) {
            hashCode = (int)((mostSigBits >> 32) ^
                             mostSigBits ^
                             (leastSigBits >> 32) ^
                             leastSigBits);
        }
        return hashCode;
    
public static java.util.UUIDnameUUIDFromBytes(byte[] name)
Static factory to retrieve a type 3 (name based) UUID based on the specified byte array.

param
name a byte array to be used to construct a UUID.
return
a UUID generated from the specified array.

        MessageDigest md;
        try {
            md = MessageDigest.getInstance("MD5");
        } catch (NoSuchAlgorithmException nsae) {
            throw new InternalError("MD5 not supported");
        }
        byte[] md5Bytes = md.digest(name);
        md5Bytes[6]  &= 0x0f;  /* clear version        */
        md5Bytes[6]  |= 0x30;  /* set to version 3     */
        md5Bytes[8]  &= 0x3f;  /* clear variant        */
        md5Bytes[8]  |= 0x80;  /* set to IETF variant  */
        return new UUID(md5Bytes);
    
public longnode()
The node value associated with this UUID.

The 48 bit node value is constructed from the node field of this UUID. This field is intended to hold the IEEE 802 address of the machine that generated this UUID to guarantee spatial uniqueness.

The node value is only meaningful in a time-based UUID, which has version type 1. If this UUID is not a time-based UUID then this method throws UnsupportedOperationException.

return
the node value of this UUID.
throws
UnsupportedOperationException if this UUID is not a version 1 UUID.

        if (version() != 1) {
            throw new UnsupportedOperationException("Not a time-based UUID");
        }
        if (node < 0) {
            node = leastSigBits & 0x0000FFFFFFFFFFFFL;
        }
        return node;
    
public static java.util.UUIDrandomUUID()
Static factory to retrieve a type 4 (pseudo randomly generated) UUID. The UUID is generated using a cryptographically strong pseudo random number generator.

return
a randomly generated UUID.

        SecureRandom ng = numberGenerator;
        if (ng == null) {
            numberGenerator = ng = new SecureRandom();
        }

        byte[] randomBytes = new byte[16];
        ng.nextBytes(randomBytes);
        randomBytes[6]  &= 0x0f;  /* clear version        */
        randomBytes[6]  |= 0x40;  /* set to version 4     */
        randomBytes[8]  &= 0x3f;  /* clear variant        */
        randomBytes[8]  |= 0x80;  /* set to IETF variant  */
        UUID result = new UUID(randomBytes);
        return new UUID(randomBytes);
    
private voidreadObject(java.io.ObjectInputStream in)
Reconstitute the UUID instance from a stream (that is, deserialize it). This is necessary to set the transient fields to their correct uninitialized value so they will be recomputed on demand.


        in.defaultReadObject();

        // Set "cached computation" fields to their initial values
        version = -1;
        variant = -1;
        timestamp = -1;
        sequence = -1;
        node = -1;
        hashCode = -1;
    
public longtimestamp()
The timestamp value associated with this UUID.

The 60 bit timestamp value is constructed from the time_low, time_mid, and time_hi fields of this UUID. The resulting timestamp is measured in 100-nanosecond units since midnight, October 15, 1582 UTC.

The timestamp value is only meaningful in a time-based UUID, which has version type 1. If this UUID is not a time-based UUID then this method throws UnsupportedOperationException.

throws
UnsupportedOperationException if this UUID is not a version 1 UUID.

        if (version() != 1) {
            throw new UnsupportedOperationException("Not a time-based UUID");
        }
        long result = timestamp;
        if (result < 0) {
            result = (mostSigBits & 0x0000000000000FFFL) << 48;
            result |= ((mostSigBits >> 16) & 0xFFFFL) << 32;
            result |= mostSigBits >>> 32;
            timestamp = result;
        }
        return result;
    
public java.lang.StringtoString()
Returns a String object representing this UUID.

The UUID string representation is as described by this BNF :

UUID =  "-"  "-"
 "-"
 "-"

time_low = 4*
time_mid = 2*
time_high_and_version = 2*
variant_and_sequence = 2*
node = 6*
hexOctet = 
hexDigit =
"0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
| "a" | "b" | "c" | "d" | "e" | "f"
| "A" | "B" | "C" | "D" | "E" | "F"

return
a string representation of this UUID.

	return (digits(mostSigBits >> 32, 8) + "-" +
		digits(mostSigBits >> 16, 4) + "-" +
		digits(mostSigBits, 4) + "-" +
		digits(leastSigBits >> 48, 4) + "-" +
		digits(leastSigBits, 12));
    
public intvariant()
The variant number associated with this UUID. The variant number describes the layout of the UUID. The variant number has the following meaning:

  • 0 Reserved for NCS backward compatibility
  • 2 The Leach-Salz variant (used by this class)
  • 6 Reserved, Microsoft Corporation backward compatibility
  • 7 Reserved for future definition

return
the variant number of this UUID.

        if (variant < 0) {
            // This field is composed of a varying number of bits
            if ((leastSigBits >>> 63) == 0) {
                variant = 0;
            } else if ((leastSigBits >>> 62) == 2) {
                variant = 2;
            } else {
                variant = (int)(leastSigBits >>> 61);
            }
        }
        return variant;
    
public intversion()
The version number associated with this UUID. The version number describes how this UUID was generated. The version number has the following meaning:

  • 1 Time-based UUID
  • 2 DCE security UUID
  • 3 Name-based UUID
  • 4 Randomly generated UUID

return
the version number of this UUID.

        if (version < 0) {
            // Version is bits masked by 0x000000000000F000 in MS long
            version = (int)((mostSigBits >> 12) & 0x0f);
        }
        return version;