API Documentation

API Documentation #

UUIDs #

Static utility methods for creating, parsing, inspecting, and comparing UUID instances in accordance with RFC 9562.

The UUIDs class provides factory methods for generating all standard UUID versions defined in RFC 9562, including:

It also defines constants and utilities for working with the special values defined in the RFC:

  • nilUUID() — Nil UUID (all bits set to zero)
  • maxUUID() — Max UUID (all bits set to one)
  • NS — Standard name spaces for deterministic UUIDs

Unlike the default UUID.compareTo(UUID) implementation, which uses signed component-wise comparison and is known to produce incorrect results in some edge cases, this class offers a correct comparator via comparator() that performs canonical bytewise comparison as defined in RFC 9562 Section 6.

This class is immutable and thread-safe.

Since 1.0.0
See: UUID
See: RFC 9562

Constants #

public static final UUID NIL_UUID #

The nil UUID is a special form of UUID with all 128 bits set to zero.

See: RFC 9562 §5.9

public static final UUID MIN_UUID #

Alias for NIL_UUID.

See: RFC 9562 §5.9

public static final UUID MAX_UUID #

The Max UUID is a special form of UUID with all 128 bits set to one.

See: RFC 9562 §5.10

Interface: Namespace #

See: the section Creating Custom Namespaces for more information.

Represents a namespace identifier used for name-based UUID generation (versions 3 and 5).

Implementations of this interface provide a specific {@link UUID} that serves as the namespace for generating name-based UUIDs, as defined in RFC 9562, Section 6.5.

UUIDs.Namespace.namespace() #

Returns the UUID that identifies this namespace. Returns: the namespace UUID

Enum: UUIDs.NS #

Well-known namespace UUIDs used for name-based generation.

  • DNS — DNS names
  • URL — URL strings
  • OID — ISO OIDs
  • X500 — X.500 Distinguished Names

See: RFC 9562 §6.5

UUID Generation #

UUID timeBasedUUID() #

UUID v1UUID() #

Generates a Version 1 time-based UUID.

Returns: a Version 1 UUID
See: RFC 9562 §5.1

UUID md5UUID(NS namespace, String name) #

UUID v3UUID(NS namespace, String name) #

Generates a Version 3 name-based UUID using MD5 hashing.

Param: namespace the namespace UUID
Param: name the name string
Returns: a Version 3 UUID
See: RFC 9562 §5.3

UUID md5UUID(String name) #

UUID v3UUID(String name) #

The v3UUID(String) method, which omits a namespace, is not compliant with RFC 9562 §5.3.
RFC-compliant Version 3 UUIDs require both a namespace and a name to ensure deterministic, globally unique output.

This method is provided for compatibility with the JDK’s built-in UUID.nameUUIDFromBytes(), which also omits the namespace prefix by default. As such, the result may match JVM-generated v3 UUIDs but should not be relied on for deterministic cross-platform UUID generation.

Generates a non-standard Version 3 UUID.

Returns: a Version 3 UUID
See: RFC 9562 §5.3

UUID randomUUID() #

UUID v4UUID() #

Generates a Version 4 random UUID with 122 bits of randomness.

Returns: a Version 4 UUID
See: RFC 9562 §5.4

UUID sha1UUID(NS namespace, String name) #

UUID v5UUID(NS namespace, String name) #

Generates a Version 5 name-based UUID using SHA-1 hashing.

Param: namespace the namespace UUID
Param: name the name string
Returns: a Version 5 UUID
See: RFC 9562 §5.5

UUID sha1UUID(String name) #

UUID v5UUID(String name) #

The v5UUID(String) method, which omits a namespace, is not compliant with RFC 9562 §5.5.
Version 5 UUIDs require both a namespace and a name to ensure deterministic, globally unique output.

This method is provided only for symmetry with v3UUID(String), and should not be used in contexts where standards compliance is required.

Generates a non-standard Version 5 UUID.

Returns: a Version 5 UUID
See: RFC 9562 §5.5

UUID sortableTimeBasedUUID() #

UUID v6UUID() #

Generates a Version 6 time-ordered UUID.

Returns: a Version 6 UUID
See: RFC 9562 §5.6

UUID unixTimeBasedUUID() #

UUID v7UUID() #

Generates a Version 7 UUID with a 48-bit Unix timestamp and 74 bits of randomness.

Returns: a Version 7 UUID
See: RFC 9562 §5.7

UUID customUUID() #

UUID v8UUID() #

Generates a Version 8 custom UUID from a random base.

Returns: a Version 8 UUID
See: RFC 9562 §5.8

UUID customUUID(UUID source) #

UUID v8UUID(UUID source) #

Generates a Version 8 UUID from an existing source UUID.

Param: source the UUID to transform
Returns: a Version 8 UUID
See: RFC 9562 §5.8

Special Values #

UUID nilUUID() #

Returns the Nil UUID (00000000-0000-0000-0000-000000000000).

Returns: the Nil UUID
See: RFC 9562 §5.9

UUID maxUUID() #

Returns the Max UUID (ffffffff-ffff-ffff-ffff-ffffffffffff).

Returns: the Max UUID
See: RFC 9562 §5.10

Timestamps #

Instant realTimestamp(UUID uuid) #

Extracts the real timestamp from a time-based UUID (v1, v6, or v7).

Param: uuid a time-based UUID
Returns: the corresponding Instant
Throws: UnsupportedOperationException if the UUID version is not time-based

Instant realTimestamp(long timestamp) #

Converts a 60-bit UUID timestamp (in 100-nanosecond units) into an Instant.

Param: timestamp the UUID timestamp
Returns: the equivalent Instant

Parsing and Conversion #

UUID uuid(byte[] data) #

Converts a 16-byte array to a UUID.

Param: data a byte array of length 16
Returns: the UUID

UUID uuid(String name) #

Java’s default UUID.fromString() accepts input that does not match the expected format of a UUID.

Parses a UUID from its string representation.

Param: name the UUID string
Returns: the parsed UUID
Throws: UnsupportedOperationException If name does not conform to the string representation as described in UUID.toString()
See: JDK Bug 8216407

String toBinaryString(UUID uuid) #

Returns a grouped binary string representation of the UUID.

Param: uuid the UUID to convert
Returns: a binary string like 00000000-00000000-...

String urn(UUID uuid) #

Returns a URN (Uniform Resource Name) for the given UUID, in the form urn:uuid:<uuid>. The “uuid” URN namespace is registered in RFC 9562 and specifies that a UUID URN is constructed by prefixing the canonical UUID string (8-4-4-4-12 hexadecimal format) with urn:uuid:. For example:

urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6

Param: uuid the UUID to be formatted as a URN
Returns: a URN string compliant with RFC 9562 See: RFC 9562 §4 See: RFC 8141

String hex(UUID uuid) #

Returns the 32-character hexadecimal representation of the given UUID, with all hyphens removed.

The returned string is not the canonical UUID representation defined by RFC 9562. Systems or libraries that strictly parse only the 8–4–4–4–12 hyphenated format may reject this value as an invalid UUID.

Param: uuid the UUID to convert to a 32-hex-digit string
Returns: 32-character hex string (no dashes)

Comparison #

Java’s default UUID.compareTo() can produce unexpected results when sorting. Consider using UUIDs.comparator() instead.

Comparator<UUID> comparator() #

Returns a comparator that performs correct unsigned bytewise comparison.

Returns: a canonical comparator
See: RFC 9562 §6
See: JDK Bug 7025832