com.github.f4b6a3.uuid.factory

Class AbstTimeBasedFactory

java.lang.Object

com.github.f4b6a3.uuid.factory.UuidFactory

com.github.f4b6a3.uuid.factory.AbstTimeBasedFactory

Direct Known Subclasses:

DceSecurityFactory, TimeBasedFactory, TimeOrderedFactory

public abstract class AbstTimeBasedFactory
extends UuidFactory

Abstract factory for creating time-based unique identifiers (UUIDv1, UUIDv2 and UUIDv6).

The time stamp has 100-nanoseconds resolution, starting from 1582-10-15, which is a date known as Gregorian Epoch. The the time stamp rolls over around AD 5235 (1582 + 2^60 / 365.25 / 24 / 60 / 60 / 10000000).

The node identifier can be:

• A MAC address;
• A hash of host name, MAC and IP;
• A random number that always changes;
• A specific number chosen by someone.

The node identifier used by this factory can be controlled by defining a system property 'uuidcreator.node' or an environment variable 'UUIDCREATOR_NODE'. The system property has preference over the environment variable.

Options accepted by the system property and the environment variable:

• The string "mac" for using the MAC address;
• The string "hash" for using a hash of host name, MAC and IP;
• The string "random" for using a random number that always changes;
• The string representation of a specific number between 0 and 2^48-1.

If a property or variable is defined, all UUIDs generated by this factory will be based on it.

Otherwise, if no property or variable is defined, a random node identifier is generated once at instantiation. This is the default.

Example of system property definition:

 # Append to VM arguments
 -Duuidcreator.node="mac"
 

Example of environment variable definition:

 # Append to ~/.profile
 export UUIDCREATOR_NODE="mac"
 

See Also:

TimeFunction, NodeIdFunction, ClockSeqFunction, RFC 9562

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AbstTimeBasedFactory.Builder<T,B extends AbstTimeBasedFactory.Builder<T,B>> Abstract builder for creating a time-based factory.

Nested classes/interfaces inherited from class com.github.f4b6a3.uuid.factory.UuidFactory

UuidFactory.Parameters

Field Summary

Fields

Modifier and Type	Field and Description
protected ClockSeqFunction	clockseqFunction The clock sequence function.
protected ReentrantLock	lock The reentrant lock for synchronization.
protected NodeIdFunction	nodeidFunction The node function.
protected TimeFunction	timeFunction The time function.

Fields inherited from class com.github.f4b6a3.uuid.factory.UuidFactory

version, versionMask

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstTimeBasedFactory(UuidVersion version, AbstTimeBasedFactory.Builder<?,?> builder) A protected constructor that receives a builder object.

Method Summary

Modifier and Type	Method and Description
UUID	create() Returns a time-based UUID.
UUID	create(UuidFactory.Parameters parameters) Returns a time-based UUID.
protected long	formatLeastSignificantBits(long nodeIdentifier, long clockSequence) Returns the least significant bits of the UUID.
protected long	formatMostSignificantBits(long timestamp) Returns the most significant bits of the UUID.
protected static NodeIdFunction	selectNodeIdFunction() Select the node identifier function.
protected static TimeFunction	selectTimeFunction() Select the time function.

Methods inherited from class com.github.f4b6a3.uuid.factory.UuidFactory

getVersion, nameBytes, nameBytes, namespaceBytes, namespaceBytes, namespaceBytes, toUuid

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

timeFunction

protected TimeFunction timeFunction

The time function.

nodeidFunction

protected NodeIdFunction nodeidFunction

The node function.

clockseqFunction

protected ClockSeqFunction clockseqFunction

The clock sequence function.

lock

protected final ReentrantLock lock

The reentrant lock for synchronization.

Constructor Detail

AbstTimeBasedFactory

protected AbstTimeBasedFactory(UuidVersion version,
                               AbstTimeBasedFactory.Builder<?,?> builder)

A protected constructor that receives a builder object.

Parameters:

version - the version number (1, 2 or 6)

builder - a builder object

Method Detail

create

public UUID create()

Returns a time-based UUID.

Specified by:

create in class UuidFactory

Returns:

a time-based UUID

create

public UUID create(UuidFactory.Parameters parameters)

Returns a time-based UUID.

Specified by:

create in class UuidFactory

Parameters:

parameters - parameters object

Returns:

a time-based UUID

formatMostSignificantBits

protected long formatMostSignificantBits(long timestamp)

Returns the most significant bits of the UUID.

It implements the algorithm for generating UUIDv1.

Parameters:

timestamp - the number of 100-nanoseconds since 1970-01-01 (Unix epoch)

Returns:

the MSB

formatLeastSignificantBits

protected long formatLeastSignificantBits(long nodeIdentifier,
                                          long clockSequence)

Returns the least significant bits of the UUID.

Parameters:

nodeIdentifier - a node identifier

clockSequence - a clock sequence

Returns:

the LSB

selectNodeIdFunction

protected static NodeIdFunction selectNodeIdFunction()

Select the node identifier function. This method reads the system property 'uuidcreator.node' and the environment variable 'UUIDCREATOR_NODE' to decide what node identifier function must be used. 1. If it finds the string "mac", the generator will use the MAC address. 2. If it finds the string "hash", the generator will use the system data hash. 3. If it finds the string "random", the generator will use a random number that always changes. 4. If it finds the string representation of a specific number in octal, hexadecimal or decimal format, the generator will use the number represented. 5. Else, a random number will be used by the generator.

Returns:

a node function

selectTimeFunction

protected static TimeFunction selectTimeFunction()

Select the time function. If the operating system is WINDOWS, it returns a function that is more efficient for its typical time granularity (15.6ms). Otherwise, it returns the default time function.

Returns:

a time function