com.github.f4b6a3.uuid.factory.abst

Class AbstractTimeBasedUuidCreator

java.lang.Object

com.github.f4b6a3.uuid.factory.abst.AbstractUuidCreator

com.github.f4b6a3.uuid.factory.abst.AbstractTimeBasedUuidCreator

Direct Known Subclasses:

CombGuidCreator, MssqlGuidCreator, SequentialUuidCreator, TimeBasedUuidCreator

public abstract class AbstractTimeBasedUuidCreator
extends AbstractUuidCreator

Field Summary

Fields

Modifier and Type	Field and Description
protected ClockSequenceStrategy	clockSequenceStrategy
protected NodeIdentifierStrategy	nodeIdentifierStrategy
protected TimestampStrategy	timestampStrategy

Fields inherited from class com.github.f4b6a3.uuid.factory.abst.AbstractUuidCreator

NAMESPACE_DNS, NAMESPACE_OID, NAMESPACE_URL, NAMESPACE_X500, NIL_UUID, RFC4122_VARIANT_BITS, RFC4122_VERSION_BITS, VARIANT_RESERVED_FUTURE, VARIANT_RESERVED_MICROSOFT, VARIANT_RESERVED_NCS, VARIANT_RFC4122, version, VERSION_0, VERSION_1, VERSION_2, VERSION_3, VERSION_4, VERSION_5

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractTimeBasedUuidCreator(int version) This constructor requires a version number.

Method Summary

Modifier and Type	Method and Description
UUID	create() Returns a new time-based UUID. ### Timestamp The timestamp has 100-nanoseconds resolution, starting from 1582-10-15.
long	formatLeastSignificantBits(long nodeIdentifier, long clockSequence) Returns the least significant bits of the UUID. ### RFC-4122 - 4.2.2.
abstract long	formatMostSignificantBits(long timestamp) Format the MSB UUID from the current timestamp.
<T extends AbstractTimeBasedUuidCreator> T	withClockSequence(int clockSequence) Set a fixed initial clock sequence value to generate UUIDs.
<T extends AbstractTimeBasedUuidCreator> T	withClockSequenceStrategy(ClockSequenceStrategy clockSequenceStrategy) Use an alternative ClockSequenceStrategy to generate clock sequences.
<T extends AbstractTimeBasedUuidCreator> T	withHardwareAddress() Set the node identifier to be a real hardware address of the host machine.
<T extends AbstractTimeBasedUuidCreator> T	withInstant(Instant instant) Set a fixed Instant to generate UUIDs.
<T extends AbstractTimeBasedUuidCreator> T	withNodeIdentifier(long nodeIdentifier) Set a fixed node identifier to generate UUIDs.
<T extends AbstractTimeBasedUuidCreator> T	withNodeIdentifierStrategy(NodeIdentifierStrategy nodeIdentifierStrategy) Use an alternative NodeIdentifierStrategy to generate node identifiers.
<T extends AbstractTimeBasedUuidCreator> T	withTimestamp(long timestamp) Set a fixed timestamp to generate UUIDs.
<T extends AbstractTimeBasedUuidCreator> T	withTimestampStrategy(TimestampStrategy timestampStrategy) Use an alternative TimestampStrategy to generate timestamps.

Methods inherited from class com.github.f4b6a3.uuid.factory.abst.AbstractUuidCreator

getVariantBits, getVersion, getVersionBits, setVariantBits, setVersionBits, valid

Methods inherited from class java.lang.Object

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

Field Detail

timestampStrategy

protected TimestampStrategy timestampStrategy

clockSequenceStrategy

protected ClockSequenceStrategy clockSequenceStrategy

nodeIdentifierStrategy

protected NodeIdentifierStrategy nodeIdentifierStrategy

Constructor Detail

AbstractTimeBasedUuidCreator

protected AbstractTimeBasedUuidCreator(int version)

This constructor requires a version number.

Parameters:

version - the version number

Method Detail

create

public UUID create()

Returns a new time-based UUID. ### Timestamp The timestamp has 100-nanoseconds resolution, starting from 1582-10-15. It uses 60 bits from the most significant bits. The the time value rolls over around AD 5235.

   s = 10_000_000
   m = 60 * s
   h = 60 * m
   d = 24 * h
   y = 365.25 * d
   2^60 / y = ~3653
   3653 + 1582 = 5235
 

### RFC-4122 - 4.1.4. Timestamp The timestamp is a 60-bit value. For UUID version 1, this is represented by Coordinated Universal Time (UTC) as a count of 100- nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of Gregorian reform to the Christian calendar). ### RFC-4122 - 4.1.5. Clock Sequence For UUID version 1, the clock sequence is used to help avoid duplicates that could arise when the clock is set backwards in time or if the node ID changes. ### RFC-4122 - 4.1.6. Node For UUID version 1, the node field consists of an IEEE 802 MAC address, usually the host address. For systems with multiple IEEE 802 addresses, any available one can be used. The lowest addressed octet (octet number 10) contains the global/local bit and the unicast/multicast bit, and is the first octet of the address transmitted on an 802.3 LAN. For systems with no IEEE address, a randomly or pseudo-randomly generated value may be used; see Section 4.5. The multicast bit must be set in such addresses, in order that they will never conflict with addresses obtained from network cards. ### RFC-4122 - 4.2.1. Basic Algorithm (1a) Obtain a system-wide global lock (2a) From a system-wide shared stable store (e.g., a file), read the UUID generator state: the values of the timestamp, clock sequence, and node ID used to generate the last UUID. (3a) Get the current time as a 60-bit count of 100-nanosecond intervals since 00:00:00.00, 15 October 1582. (4a) Get the current node ID. (5a) If the state was unavailable (e.g., non-existent or corrupted), or the saved node ID is different than the current node ID, generate a random clock sequence value. (6a) If the state was available, but the saved timestamp is later than the current timestamp, increment the clock sequence value. (7a) Save the state (current timestamp, clock sequence, and node ID) back to the stable store. (8a) Release the global lock. (9a) Format a UUID from the current timestamp, clock sequence, and node ID values according to the steps in Section 4.2.2.

Returns:

UUID

withTimestampStrategy

public <T extends AbstractTimeBasedUuidCreator> T withTimestampStrategy(TimestampStrategy timestampStrategy)

Use an alternative TimestampStrategy to generate timestamps. The DefaultTimestampStrategy has accuracy of milliseconds. If someone needs a real 100-nanosecond an implementation of TimestampStrategy may be provided via this method.

Type Parameters:

T - type parameter

Parameters:

timestampStrategy - a timestamp strategy

Returns:

AbstractTimeBasedUuidCreator

withNodeIdentifierStrategy

public <T extends AbstractTimeBasedUuidCreator> T withNodeIdentifierStrategy(NodeIdentifierStrategy nodeIdentifierStrategy)

Use an alternative NodeIdentifierStrategy to generate node identifiers. The DefaultNodeIdentifierStrategy generates a random multicast node identifier and returns it for every call to DefaultNodeIdentifierStrategy.getNodeIdentifier().

Type Parameters:

T - type parameter

Parameters:

nodeIdentifierStrategy - a node identifier strategy

Returns:

AbstractTimeBasedUuidCreator

withClockSequenceStrategy

public <T extends AbstractTimeBasedUuidCreator> T withClockSequenceStrategy(ClockSequenceStrategy clockSequenceStrategy)

Use an alternative ClockSequenceStrategy to generate clock sequences. By default the strategy DefaultClockSequenceStrategy is used. DefaultClockSequenceStrategy

Type Parameters:

T - type parameter

Parameters:

clockSequenceStrategy - a clock sequence strategy

Returns:

AbstractTimeBasedUuidCreator

withInstant

public <T extends AbstractTimeBasedUuidCreator> T withInstant(Instant instant)

Set a fixed Instant to generate UUIDs. This method is useful for unit tests.

Type Parameters:

T - type parameter

Parameters:

instant - an Instant

Returns:

AbstractTimeBasedUuidCreator

withTimestamp

public <T extends AbstractTimeBasedUuidCreator> T withTimestamp(long timestamp)

Set a fixed timestamp to generate UUIDs. This method is useful for unit tests.

Type Parameters:

T - type parameter

Parameters:

timestamp - a timestamp

Returns:

AbstractTimeBasedUuidCreator

withNodeIdentifier

public <T extends AbstractTimeBasedUuidCreator> T withNodeIdentifier(long nodeIdentifier)

Set a fixed node identifier to generate UUIDs. Every time a factory is instantiated a random value is set to the node identifier by default. Someone may think it's useful in some special case to use a fixed node identifier other than random value.

Type Parameters:

T - type parameter

Parameters:

nodeIdentifier - a node identifier

Returns:

AbstractTimeBasedUuidCreator

withHardwareAddress

public <T extends AbstractTimeBasedUuidCreator> T withHardwareAddress()

Set the node identifier to be a real hardware address of the host machine. Every time a factory is instantiated a random value is set to the node identifier by default. Using a real hardware address today is not recommended anymore. But someone may prefer to use a real MAC address.

Type Parameters:

T - type parameter

Returns:

AbstractTimeBasedUuidCreator

withClockSequence

public <T extends AbstractTimeBasedUuidCreator> T withClockSequence(int clockSequence)

Set a fixed initial clock sequence value to generate UUIDs. The sequence has a range from 0 to 16,383 (0x3fff). Every time a factory is instantiated a random value is set to the sequence by default. This method allows someone to change this value with a desired one. It is called "initial" because during the lifetime of the factory instance, this value may be incremented or even replaced by another random value to avoid repetition of UUIDs.

Type Parameters:

T - type parameter

Parameters:

clockSequence - a clock sequence

Returns:

AbstractTimeBasedUuidCreator

formatMostSignificantBits

public abstract long formatMostSignificantBits(long timestamp)

Format the MSB UUID from the current timestamp.

Parameters:

timestamp - a timestamp

Returns:

the MSB

formatLeastSignificantBits

public long formatLeastSignificantBits(long nodeIdentifier,
                                       long clockSequence)

Returns the least significant bits of the UUID. ### RFC-4122 - 4.2.2. Generation Details Set the clock_seq_low field to the eight least significant bits (bits zero through 7) of the clock sequence in the same order of significance. Set the 6 least significant bits (bits zero through 5) of the clock_seq_hi_and_reserved field to the 6 most significant bits (bits 8 through 13) of the clock sequence in the same order of significance. Set the two most significant bits (bits 6 and 7) of the clock_seq_hi_and_reserved to zero and one, respectively. Set the node field to the 48-bit IEEE address in the same order of significance as the address.

Parameters:

nodeIdentifier - a node identifier

clockSequence - a clock sequence

Returns:

the LSB