org.tquadrat.foundation.util.UniqueIdUtils

@ClassVersion(sourceVersion="$Id: UniqueIdUtils.java 1111 2024-03-04 21:54:29Z tquadrat $") @API(status=STABLE, since="0.0.5") @UtilityClass public final class UniqueIdUtils extends Object

This static class provides some utility methods that are helpful when working with unique ids.

All methods in this class are final, no instance of this class is allowed.

First it extends the capabilities of the class UUID that is a part of the Java Runtime library; it implements Universal Unique ids as defined through RFC 4122. It extends the capabilities of the Java Runtime class UUID.

RFC 4122 UUID

The methods nameUUIDFromBytes(byte[],HashType), nameUUIDFromString(CharSequence,HashType), nameUUIDFromString(UUID, CharSequence,HashType), randomUUID(), sequenceUUID(long,long), timebasedUUID(), timebasedUUID(long), timebasedUUIDFromNodeName(CharSequence), and uuidFromString(CharSequence) do all create a UUID instance, but randomUUID() will delegate to the method with the same name of the class UUID itself, while uuidFromString(CharSequence) delegates to UUID.fromString(String). nameUUIDFromBytes(byte[],HashType) delegates to UUID.nameUUIDFromBytes(byte[]) for hashType equal to UniqueIdUtils.HashType.HASH_MD5.

Currently, this class supports only the generation of UUIDs with the types 1 (not supported by UUID), 3, 4, and 5, although the method uuidFromString(CharSequence) is also capable of converting UUID Strings representing the type 2 into valid UUID instances.

The type 0 as generated by sequenceUUID(long,long) is not defined by RFC 4122.

The sample Implementation for a UUID Generator

The source code for this sample implementation in C was taken from RFC 4122.

The appendix C of RFC 4122 also lists the name space IDs for some potentially interesting name spaces, as initialized C structures and in the string representation defined by the RFC.

   /* Name string is a fully-qualified domain name */
   uuid_t NameSpace_DNS = { /* 6ba7b810-9dad-11d1-80b4-00c04fd430c8 */
       0x6ba7b810,
       0x9dad,
       0x11d1,
       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
   };

   /* Name string is a URL */
   uuid_t NameSpace_URL = { /* 6ba7b811-9dad-11d1-80b4-00c04fd430c8 */
       0x6ba7b811,
       0x9dad,
       0x11d1,
       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
   };

   /* Name string is an ISO OID */
   uuid_t NameSpace_OID = { /* 6ba7b812-9dad-11d1-80b4-00c04fd430c8 */
       0x6ba7b812,
       0x9dad,
       0x11d1,
       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
   };

   /* Name string is an X.500 DN (in DER or a text output format) */
   uuid_t NameSpace_X500 = { /* 6ba7b814-9dad-11d1-80b4-00c04fd430c8 */
       0x6ba7b814,
       0x9dad,
       0x11d1,
       0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8
   };

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: UniqueIdUtils.java 1111 2024-03-04 21:54:29Z tquadrat $

Since:

0.0.5

See Also:

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.util.UniqueIdUtils"

⁠

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static enum

UniqueIdUtils.HashType

Two different hash types are used for name-based UUIDs.
Field Summary

Fields

Modifier and Type

Field

Description

private static final BigInteger

BIT_MASK

The bit mask used for the conversion from and to a number.

private static long

m_ClockSeq

The clock sequence.

private static final AutoLock

m_ClockSeqGuard

The guard for the clock sequence.

private static final long

m_DummyNodeId

The dummy node id that is used to generate UUIDs, if required.

private static long

m_LastClockSeqRequest

The last time when a clock sequence was requested.

private static final Map<String,UUID>

m_Namespaces

The UUIDs for the predefined name spaces, according to RFC 4122.

private static final long

m_NodeId

The node id that is used to generate UUIDs.

private static final boolean

m_UsePseudoNodeId

This flag controls if m_NodeId is forced to be a random value.

It will be controlled by the system property ""org.tquadrat.foundation.util.UniqueIdUtils.UsePseudoNodeId"".

Using a pseudo node id would generate anonymous UUIDs.

private static final AtomicInteger

m_UUID7Counter

The counter for version 7 UUIDs.

private static final char[][]

m_UUIDXMLDigits

The digits that are used for an XML safe UUID.

private static final BigInteger

ONE_HUNDRED

Divisor for the calculation of the timestamp.

static final String

PROPERTY_USE_PSEUDO_NODE_ID

The name for the internal system property for the flag controlling that only pseudo node ids should be used to generate UUID instances of type 1: "org.tquadrat.foundation.util.UniqueIdUtils.UsePseudoNodeId".

static final UUID

UUID_MAX

The max UUID.

static final UUID

UUID_NIL

The nil UUID.

static final int

UUID_Size

The character count for a UUID: 36.
Constructor Summary

Constructors

Modifier

Constructor

Description

private

UniqueIdUtils()

No instance of this class is allowed!
Method Summary

Modifier and Type

Method

Description

static final UUID

fromXMLId(CharSequence input)

Converts an XML safe id that was created through toXMLId(UUID) back to a UUID.

private static final long

getClockSequence(long currentTime)

Returns the clock sequence.

static final UUID

getNamespaceUUID(String key)

Returns the UUID for the namespace with the given name.

static final String[]

listNamespaces()

Returns the names of the known UUID namespaces.

static final UUID

nameUUIDFromBytes(byte[] name, UniqueIdUtils.HashType hashType)

Static factory to retrieve a type 3 (name based, MD5 hashed) or a type 5 (name based, SHA hashed) UUID based on the specified byte array.

This method will always return the same output if the input is the same.

The provided name should be prepended with the UUID for a designated name space, although this is neither enforced nor checked by this method.

static final UUID

nameUUIDFromString(CharSequence name, UniqueIdUtils.HashType hashType)

Creates a name-based (version type 3 or type 5, depending on the provided hash type) UUID from the given String.

This method will always return the same output if the input is the same.

The provided name should be prepended with the UUID for a designated name space, although this is neither enforced nor checked by this method.

static final UUID

nameUUIDFromString(UUID namespace, CharSequence name, UniqueIdUtils.HashType hashType)

Creates a name-based (version type 3 or type 5, depending on the provided hash type) UUID from the given String, using the provided namespace UUID as the prefix.

This method will always return the same output if the input is the same.

static final UUID

randomUUID()

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

static final UUID

sequenceUUID(long mostSignificant, long leastSignificant)

Creates a sequence UUID from the given values; this UUID will have the type 0 (that is not officially defined).

static final UUID

timebasedUUID()

Creates a time-based (version type 1) UUID using the internal node id.

static final UUID

timebasedUUID(long nodeId)

Creates a time-based (version type 1) UUID, using the given node id.

static final UUID

timebasedUUIDFromDummyNode()

Creates a time-based (version type 1) UUID from a dummy node id.

static final UUID

timebasedUUIDFromNodeName(CharSequence nodeName)

Creates a time-based (version type 1) UUID from the given node name.

The provided node name will be hashed (using MD5), the bytes from the result will be converted into BigInteger.

static final String

toXMLId(UUID input)

Converts a UUID to a String that can be used as an XML id.

static final UUID

uuidFromNumber(BigInteger value)

Creates a UUID from the given number (more precise, the given BigInteger).

static final UUID

uuidFromString(CharSequence uuid)

Creates a UUID from the string standard representation.

static final BigInteger

uuidToNumber(UUID uuid)

Returns a number (more precise, an instance of BigInteger) that represents the given UUID.

static final UUID

version7UUID()

Creates a time-based (version type 7) UUID.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details
- BIT_MASK
  
  private static final BigInteger BIT_MASK
  
  The bit mask used for the conversion from and to a number.
- ONE_HUNDRED
  
  private static final BigInteger ONE_HUNDRED
  
  Divisor for the calculation of the timestamp.
- PROPERTY_USE_PSEUDO_NODE_ID
  
  @API(status=STABLE, since="0.0.5") public static final String PROPERTY_USE_PSEUDO_NODE_ID
  
  The name for the internal system property for the flag controlling that only pseudo node ids should be used to generate UUID instances of type 1: "org.tquadrat.foundation.util.UniqueIdUtils.UsePseudoNodeId".
  
  A value of true means that only pseudo ids will be used throughout the current run of the program, while false (the default) means that a MAC address is used for the calculation of a node id, if available.
  
  This system property is not necessarily configured.
  See Also:
  
  SystemUtils.PROPERTY_NODE_ID
  
  Constant Field Values
- UUID_Size
  
  @API(status=STABLE, since="0.0.5") public static final int UUID_Size
  
  The character count for a UUID: 36.
  See Also:
  
  Constant Field Values
- m_ClockSeq
  
  private static volatile long m_ClockSeq
  
  The clock sequence.
- m_LastClockSeqRequest
  
  private static volatile long m_LastClockSeqRequest
  
  The last time when a clock sequence was requested.
- m_UUID7Counter
  
  private static final AtomicInteger m_UUID7Counter
  
  The counter for version 7 UUIDs.
- m_UUIDXMLDigits
  
  @API(status=INTERNAL, since="0.3.0") private static final char[][] m_UUIDXMLDigits
  
  The digits that are used for an XML safe UUID. The first array holds the original digits, the second array those for the XML id.
- m_ClockSeqGuard
  
  private static final AutoLock m_ClockSeqGuard
  
  The guard for the clock sequence.
- m_DummyNodeId
  
  private static final long m_DummyNodeId
  
  The dummy node id that is used to generate UUIDs, if required. This is always a random value.
- m_Namespaces
  
  private static final Map<String,UUID> m_Namespaces
  
  The UUIDs for the predefined name spaces, according to RFC 4122.
- m_NodeId
  
  private static final long m_NodeId
  
  The node id that is used to generate UUIDs. This is either the MAC address of one of the NICs in the current system, or a random value.
- m_UsePseudoNodeId
  
  private static final boolean m_UsePseudoNodeId
  
  This flag controls if m_NodeId is forced to be a random value.
  
  It will be controlled by the system property ""org.tquadrat.foundation.util.UniqueIdUtils.UsePseudoNodeId"".
  
  Using a pseudo node id would generate anonymous UUIDs.
- UUID_MAX
  
  @API(status=STABLE, since="0.0.5") public static final UUID UUID_MAX
  
  The max UUID.
- UUID_NIL
  
  @API(status=STABLE, since="0.0.5") public static final UUID UUID_NIL
  
  The nil UUID.
Constructor Details
- UniqueIdUtils
  
  private UniqueIdUtils()
  
  No instance of this class is allowed!
Method Details
- fromXMLId
  
  @API(status=STABLE, since="0.3.0") public static final UUID fromXMLId(CharSequence input)
  
  Converts an XML safe id that was created through toXMLId(UUID) back to a UUID.
  
  Parameters:
  
  input - The XML safe id.
  
  Returns:
  
  The UUID.
  
  Throws:
  
  IllegalArgumentException - The given XML safe id cannot be converted to a UUID.
- getClockSequence
  
  private static final long getClockSequence(long currentTime)
  
  Returns the clock sequence. It will be initialised with a random number on each time the program starts, and it remains unchanged until the system detects a clock shift; in that case, it will be increased by one.
  
  An overflow for the clock sequence is possible, but does not harm.
  
  Parameters:
  
  currentTime - The current time.
  
  Returns:
  
  The clock sequence.
- getNamespaceUUID
  
  @API(status=STABLE, since="0.0.5") public static final UUID getNamespaceUUID(String key)
  
  Returns the UUID for the namespace with the given name.
  
  Parameters:
  
  key - The name of the namespace.
  
  Returns:
  
  The UUID for the namespace, or null if that namespace does not exist.
- listNamespaces
  
  @API(status=STABLE, since="0.0.5") public static final String[] listNamespaces()
  
  Returns the names of the known UUID namespaces.
  
  Returns:
  
  The names of the namespaces.
- nameUUIDFromBytes
  
  @API(status=STABLE, since="0.0.5") public static final UUID nameUUIDFromBytes(byte[] name, UniqueIdUtils.HashType hashType)
  
  Static factory to retrieve a type 3 (name based, MD5 hashed) or a type 5 (name based, SHA hashed) UUID based on the specified byte array.
  
  This method will always return the same output if the input is the same.
  
  The provided name should be prepended with the UUID for a designated name space, although this is neither enforced nor checked by this method.
  Parameters:
  
  name - A byte array to be used to construct a UUID.
  
  hashType - The hash type to use.
  
  Returns:
  
  The UUID generated from the specified array.
  
  See Also:
  
  UUID.nameUUIDFromBytes(byte[])
- nameUUIDFromString
  
  @API(status=STABLE, since="0.0.5") public static final UUID nameUUIDFromString(CharSequence name, UniqueIdUtils.HashType hashType)
  
  Creates a name-based (version type 3 or type 5, depending on the provided hash type) UUID from the given String.
  
  This method will always return the same output if the input is the same.
  
  The provided name should be prepended with the UUID for a designated name space, although this is neither enforced nor checked by this method.
  Parameters:
  
  name - The name base for the UUID.
  
  hashType - The hash type to use.
  
  Returns:
  
  The UUID.
  
  See Also:
  
  UUID.nameUUIDFromBytes(byte[])
- nameUUIDFromString
  
  @API(status=STABLE, since="0.0.5") public static final UUID nameUUIDFromString(UUID namespace, CharSequence name, UniqueIdUtils.HashType hashType)
  
  Creates a name-based (version type 3 or type 5, depending on the provided hash type) UUID from the given String, using the provided namespace UUID as the prefix.
  
  This method will always return the same output if the input is the same.
  Parameters:
  
  namespace - The UUID for the namespace.
  
  name - The name base for the UUID.
  
  hashType - The hash type to use.
  
  Returns:
  
  The UUID.
  
  See Also:
  
  UUID.nameUUIDFromBytes(byte[])
- randomUUID
  
  @API(status=STABLE, since="0.0.5") public static final 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.
  
  This is a wrapper for the method with the same name from UUID.
  Returns:
  
  A randomly generated UUID.
  
  See Also:
  
  UUID.randomUUID()
- sequenceUUID
  
  @API(status=STABLE, since="0.0.5") public static final UUID sequenceUUID(long mostSignificant, long leastSignificant)
  
  Creates a sequence UUID from the given values; this UUID will have the type 0 (that is not officially defined).
  
  UUIDs of this type are used to define globally identical keys, meaning that this method will always return the same output if the input is the same.
  
  Parameters:
  
  mostSignificant - The most significant bits for the new UUID.
  
  leastSignificant - The least significant bits for the new UUID.
  
  Returns:
  
  The new UUID of type 0.
- timebasedUUID
  
  @API(status=STABLE, since="0.0.5") public static final UUID timebasedUUID(long nodeId)
  
  Creates a time-based (version type 1) UUID, using the given node id.
  
  Parameters:
  
  nodeId - The node id; only the lower 48 bit from this value are used for the UUID.
  
  Returns:
  
  The UUID.
- timebasedUUID
  
  @API(status=STABLE, since="0.0.5") public static final UUID timebasedUUID()
  
  Creates a time-based (version type 1) UUID using the internal node id.
  Returns:
  
  The UUID.
  
  See Also:
  
  m_NodeId
  
  m_UsePseudoNodeId
- timebasedUUIDFromDummyNode
  
  @API(status=STABLE, since="0.0.7") public static final UUID timebasedUUIDFromDummyNode()
  
  Creates a time-based (version type 1) UUID from a dummy node id.
  
  Returns:
  
  The UUID.
- timebasedUUIDFromNodeName
  
  @API(status=STABLE, since="0.0.5") public static final UUID timebasedUUIDFromNodeName(CharSequence nodeName)
  
  Creates a time-based (version type 1) UUID from the given node name.
  
  The provided node name will be hashed (using MD5), the bytes from the result will be converted into BigInteger. Then timebasedUUID(long) is called with the result from BigInteger.longValue(), called on the value mentioned before.
  
  Parameters:
  
  nodeName - The node name.
  
  Returns:
  
  The UUID.
- toXMLId
  
  @API(status=STABLE, since="0.3.0") public static final String toXMLId(UUID input)
  
  Converts a UUID to a String that can be used as an XML id.
  
  Parameters:
  
  input - The UUID.
  
  Returns:
  
  The XML safe id.
- uuidFromNumber
  
  public static final UUID uuidFromNumber(BigInteger value)
  
  Creates a UUID from the given number (more precise, the given BigInteger).
  
  Parameters:
  
  value - The number.
  
  Returns:
  
  The UUID.
- uuidFromString
  
  @API(status=STABLE, since="0.0.5") public static final UUID uuidFromString(CharSequence uuid) throws IllegalArgumentException, EmptyArgumentException, NullArgumentException
  Creates a UUID from the string standard representation.
  
  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"
  Parameters:
  
  uuid - The UUID string representation.
  
  Returns:
  
  The UUID from the given String representation.
  
  Throws:
  
  NullArgumentException - The argument is null.
  
  EmptyArgumentException - The argument is the empty String.
  
  IllegalArgumentException - The argument is invalid.
  
  See Also:
  
  UUID.fromString(String)
  
  UUID.toString()
- uuidToNumber
  
  @API(status=STABLE, since="0.1.0") public static final BigInteger uuidToNumber(UUID uuid)
  
  Returns a number (more precise, an instance of BigInteger) that represents the given UUID.
  
  Parameters:
  
  uuid - The UUID to convert.
  
  Returns:
  
  The number that represents the UUID.
  
  Since:
  
  0.1.0
- version7UUID
  
  @API(status=STABLE, since="0.1.0") public static final UUID version7UUID()
  
  Creates a time-based (version type 7) UUID.
  
  Returns:
  
  The UUID.

Class UniqueIdUtils

RFC 4122 UUID

The sample Implementation for a UUID Generator

UML Diagram for "org.tquadrat.foundation.util.UniqueIdUtils"

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

BIT_MASK

ONE_HUNDRED

PROPERTY_USE_PSEUDO_NODE_ID

UUID_Size

m_ClockSeq

m_LastClockSeqRequest

m_UUID7Counter

m_UUIDXMLDigits

m_ClockSeqGuard

m_DummyNodeId

m_Namespaces

m_NodeId

m_UsePseudoNodeId

UUID_MAX

UUID_NIL

Constructor Details

UniqueIdUtils

Method Details

fromXMLId

getClockSequence

getNamespaceUUID

listNamespaces

nameUUIDFromBytes

nameUUIDFromString

nameUUIDFromString

randomUUID

sequenceUUID

timebasedUUID

timebasedUUID

timebasedUUIDFromDummyNode

timebasedUUIDFromNodeName

toXMLId

uuidFromNumber

uuidFromString

uuidToNumber

version7UUID