APIdia Launch Partner
Top Description Inners Fields Constructors Methods
java.util

public final Class UUID

extends Object
implements Serializable, Comparable<UUID>
Class Inheritance
All Implemented Interfaces
java.lang.Comparable, java.io.Serializable
Imports
java.security.*, jdk.internal.access.JavaLangAccess, .SharedSecrets, jdk.internal.util.ByteArrayLittleEndian
A class that represents an immutable Universally Unique IDentifier (UUID). A UUID represents a 128-bit value.

This class is primarily designed for manipulating Leach-Salz variant UUIDs, but it also supports the creation of UUIDs of other variants.

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.

See RFC 9562: Universally Unique Identifiers (UUIDs) for the complete specification, including the UUID format, layouts, and algorithms for creating UUIDs.

There are eight defined types of UUIDs, each identified by a version number: time-based (version 1), DCE security (version 2), name-based with MD5 (version 3), randomly generated (version 4), name-based with SHA-1 (version 5), reordered time-based (version 6), Unix epoch time-based (version 7), and custom-defined layout (version 8).

Since
1.5
External Specification
https://www.rfc-editor.org/rfc/rfc9562.html

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
UUID.Holder

Field Summary

Modifier and TypeField and Description
private static final JavaLangAccess
jla

private final long
leastSigBits

private final long
mostSigBits

private static final byte[]
NIBBLES

private static final long
serialVersionUID

Explicit serialVersionUID for interoperability.

Constructor Summary

AccessConstructor and Description
private
UUID(byte[] data)

public
UUID(long
The most significant bits of the UUID
mostSigBits, long
The least significant bits of the UUID
leastSigBits)

Constructs a new UUID using the specified data.

Method Summary

Modifier and TypeMethod and Description
public int

Returns:

The clock sequence of this UUID
clockSequence()

The clock sequence value associated with this UUID.

public int

Returns:

-1, 0 or 1 as this UUID is less than, equal to, or greater than val
compareTo(UUID
UUID to which this UUID is to be compared
val)

Implements java.lang.Comparable.compareTo.

Compares this UUID with the specified UUID.

public boolean

Returns:

true if the objects are the same; false otherwise
equals(Object
The object to be compared
obj)

Overrides java.lang.Object.equals.

Compares this object to the specified object.

public static UUID

Returns:

A UUID with the specified value
fromString(String
A string that specifies a UUID
name)

Creates a UUID from the string standard representation as described in the toString method.

private static UUID
fromString1(String name)

public long

Returns:

The least significant 64 bits of this UUID's 128 bit value
getLeastSignificantBits()

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

public long

Returns:

The most significant 64 bits of this UUID's 128 bit value
getMostSignificantBits()

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

public int

Returns:

A hash code value for this UUID
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code for this UUID.

private static long

Returns:

A long containing 8 ASCII bytes representing the hex digits
hex8(long i)

Efficiently converts 8 hexadecimal digits to their ASCII representation using SIMD-style vector operations.

public static UUID

Returns:

A UUID generated from the specified array
nameUUIDFromBytes(byte[]
A byte array to be used to construct a UUID
name)

Static factory to retrieve a type 3 (name based) UUID based on the specified byte array.

public long

Returns:

The node value of this UUID
node()

The node value associated with this UUID.

public static UUID

Returns:

a UUID constructed using the given timestamp
ofEpochMillis(long
the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded.
timestamp)

Creates a type 7 UUID (UUIDv7) UUID from the given Unix Epoch timestamp.

private static long
parse4Nibbles(String name, int pos)

public static UUID

Returns:

A randomly generated UUID
randomUUID()

Static factory to retrieve a type 4 (pseudo randomly generated) UUID.

public long

Returns:

The timestamp of this UUID.
timestamp()

The timestamp value associated with this UUID.

public String

Returns:

A string representation of this UUID
toString()

Overrides java.lang.Object.toString.

Returns a String object representing this UUID.

public int

Returns:

The variant number of this UUID
variant()

The variant number associated with this UUID.

public int

Returns:

The version number of this UUID
version()

The version number associated with this UUID.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

jlaback to summary
private static final JavaLangAccess jla
leastSigBitsback to summary
private final long leastSigBits
mostSigBitsback to summary
private final long mostSigBits
NIBBLESback to summary
private static final byte[] NIBBLES
serialVersionUIDback to summary
private static final long serialVersionUID

Explicit serialVersionUID for interoperability.

Annotations
@Serial

Constructor Detail

UUIDback to summary
private UUID(byte[] data)
UUIDback to summary
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.

Parameters
mostSigBits:long

The most significant bits of the UUID

leastSigBits:long

The least significant bits of the UUID

Method Detail

clockSequenceback to summary
public int clockSequence()

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.

Returns:int

The clock sequence of this UUID

Exceptions
UnsupportedOperationException:
If this UUID is not a version 1 UUID
compareToback to summary
public int compareTo(UUID val)

Implements java.lang.Comparable.compareTo.

Compares this UUID with the specified UUID.

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

Parameters
val:UUID

UUID to which this UUID is to be compared

Returns:int

-1, 0 or 1 as this UUID is less than, equal to, or greater than val

Annotations
@Override
equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

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.

Parameters
obj:Object

The object to be compared

Returns:boolean

true if the objects are the same; false otherwise

Annotations
@Override
fromStringback to summary
public static UUID fromString(String name)

Creates a UUID from the string standard representation as described in the toString method.

Parameters
name:String

A string that specifies a UUID

Returns:UUID

A UUID with the specified value

Exceptions
IllegalArgumentException:
If name does not conform to the string representation as described in toString
fromString1back to summary
private static UUID fromString1(String name)
getLeastSignificantBitsback to summary
public long getLeastSignificantBits()

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

Returns:long

The least significant 64 bits of this UUID's 128 bit value

getMostSignificantBitsback to summary
public long getMostSignificantBits()

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

Returns:long

The most significant 64 bits of this UUID's 128 bit value

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code for this UUID.

Returns:int

A hash code value for this UUID

Annotations
@Override
hex8back to summary
private static long hex8(long i)

Efficiently converts 8 hexadecimal digits to their ASCII representation using SIMD-style vector operations. This method processes multiple digits in parallel by treating a long value as eight 8-bit lanes, achieving significantly better performance compared to traditional loop-based conversion.

The conversion algorithm works as follows: 

1. Input expansion: Each 4-bit hex digit is expanded to 8 bits
2. Vector processing:
   - Add 6 to each digit: triggers carry flag for a-f digits
   - Mask with 0x10 pattern to isolate carry flags
   - Calculate ASCII adjustment: (carry << 1) + (carry >> 1) - (carry >> 4)
   - Add ASCII '0' base (0x30) and original value
3. Byte order adjustment for final output

Performance characteristics:

  • Processes 8 digits in parallel using vector operations
  • Avoids branching and loops completely
  • Uses only integer arithmetic and bit operations
  • Constant time execution regardless of input values

ASCII conversion mapping:

  • Digits 0-9 → ASCII '0'-'9' (0x30-0x39)
  • Digits a-f → ASCII 'a'-'f' (0x61-0x66)

Implementation Note

The implementation leverages CPU vector processing capabilities through long integer operations. The algorithm is based on the observation that ASCII hex digits have a specific pattern that can be computed efficiently using carry flag manipulation.

Returns:long

A long containing 8 ASCII bytes representing the hex digits

See Also
Long#reverseBytes(long)
nameUUIDFromBytesback to summary
public static UUID nameUUIDFromBytes(byte[] name)

Static factory to retrieve a type 3 (name based) UUID based on the specified byte array.

Parameters
name:byte[]

A byte array to be used to construct a UUID

Returns:UUID

A UUID generated from the specified array

nodeback to summary
public long node()

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.

Returns:long

The node value of this UUID

Exceptions
UnsupportedOperationException:
If this UUID is not a version 1 UUID
ofEpochMillisback to summary
public static UUID ofEpochMillis(long timestamp)

Creates a type 7 UUID (UUIDv7) UUID from the given Unix Epoch timestamp. The returned UUID will have the given timestamp in the first 6 bytes, followed by the version and variant bits representing UUIDv7, and the remaining bytes will contain random data from a cryptographically strong pseudo-random number generator.

API Note

UUIDv7 values are created by allocating a Unix timestamp in milliseconds in the most significant 48 bits, allocating the required version (4 bits) and variant (2-bits) and filling the remaining 74 bits with random bits. As such, this method rejects timestamp values that do not fit into 48 bits.

Monotonicity (each subsequent value being greater than the last) is a primary characteristic of UUIDv7 values. This is due to the timestamp value being part of the UUID. Callers of this method that wish to generate monotonic UUIDv7 values are expected to ensure that the given timestamp value is monotonic.

Parameters
timestamp:long

the number of milliseconds since midnight 1 Jan 1970 UTC, leap seconds excluded.

Returns:UUID

a UUID constructed using the given timestamp

Exceptions
IllegalArgumentException:
if the timestamp is negative or greater than (1L << 48) - 1
Since
26
parse4Nibblesback to summary
private static long parse4Nibbles(String name, int pos)
randomUUIDback to summary
public static UUID randomUUID()

Static factory to retrieve a type 4 (pseudo randomly generated) UUID. The UUID is generated using a cryptographically strong pseudo random number generator.

Returns:UUID

A randomly generated UUID

timestampback to summary
public long timestamp()

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.

Returns:long

The timestamp of this UUID.

Exceptions
UnsupportedOperationException:
If this UUID is not a version 1 UUID
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a String object representing this UUID.

The UUID string representation is as described by this BNF: 

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

A string representation of this UUID

Annotations
@Override
variantback to summary
public int variant()

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 IETF RFC 9562 (Leach-Salz), used by this class
  • 6 Reserved, Microsoft Corporation backward compatibility
  • 7 Reserved for future definition
Returns:int

The variant number of this UUID

versionback to summary
public int version()

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
  • 7 Unix Epoch time-based UUID
Returns:int

The version number of this UUID

java.util back to summary

private Class UUID.Holder

extends Object
Class Inheritance

Field Summary

Modifier and TypeField and Description
pack-priv static final SecureRandom
numberGenerator

Constructor Summary

AccessConstructor and Description
private
Holder()

Method Summary

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

numberGeneratorback to summary
pack-priv static final SecureRandom numberGenerator

Constructor Detail

Holderback to summary
private Holder()