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

All Implemented Interfaces:

NoArgumentsUuidCreator

Direct Known Subclasses:

SequentialUuidCreator, TimeBasedUuidCreator

public abstract class AbstractTimeBasedUuidCreator
extends AbstractUuidCreator
implements NoArgumentsUuidCreator

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

version, versionBits

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractTimeBasedUuidCreator(UuidVersion 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.
protected long	formatLeastSignificantBits(long nodeIdentifier, long clockSequence) Formats the least significant bits of the UUID. ### RFC-4122 - 4.2.2.
protected abstract long	formatMostSignificantBits(long timestamp) Formats the most significant bits of the UUID.
<T extends AbstractTimeBasedUuidCreator> T	withClockSequence(int clockSequence) Set a fixed clock sequence value to generate UUIDs.
<T extends AbstractTimeBasedUuidCreator> T	withClockSequenceStrategy(ClockSequenceStrategy clockSequenceStrategy) Use an alternate ClockSequenceStrategy to generate clock sequences.
<T extends AbstractTimeBasedUuidCreator> T	withFingerprintNodeIdentifier() Set the node identifier to be a system data hash.
<T extends AbstractTimeBasedUuidCreator> T	withHardwareAddressNodeIdentifier() 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 alternate NodeIdentifierStrategy to generate node identifiers.
<T extends AbstractTimeBasedUuidCreator> T	withoutOverrunException() Used to disable the overrun exception.
<T extends AbstractTimeBasedUuidCreator> T	withRandomNodeIdentifier() Set the node identifier to be a random identifier.
<T extends AbstractTimeBasedUuidCreator> T	withRandomNodeIdentifier(Random random) Set the node identifier to be a random identifier.
<T extends AbstractTimeBasedUuidCreator> T	withTimestamp(long timestamp) Set a fixed timestamp to generate UUIDs.
<T extends AbstractTimeBasedUuidCreator> T	withTimestampStrategy(TimestampStrategy timestampStrategy) Use an alternate TimestampStrategy to generate timestamps.
<T extends AbstractTimeBasedUuidCreator> T	withUnixMilliseconds(long unixMilliseconds) Set a fixed Unix Epoch milliseconds value to generate UUIDs.

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

getVariantBits, getVersion, getVersionBits, setVariantBits, setVersionBits

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(UuidVersion 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.

Specified by:

create in interface NoArgumentsUuidCreator

Returns:

UUID a UUID value

Throws:

UuidCreatorException - an overrun exception if more than 10 thousand UUIDs are requested within the same millisecond

withTimestampStrategy

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

Use an alternate TimestampStrategy to generate timestamps. The DefaultTimestampStrategy has accuracy of milliseconds. If someone needs a real 100-nanosecond resolution, another 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 alternate NodeIdentifierStrategy to generate node identifiers.

Type Parameters:

T - type parameter

Parameters:

nodeIdentifierStrategy - a node identifier strategy

Returns:

AbstractTimeBasedUuidCreator

withClockSequenceStrategy

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

Use an alternate ClockSequenceStrategy to generate clock sequences.

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

withUnixMilliseconds

public <T extends AbstractTimeBasedUuidCreator> T withUnixMilliseconds(long unixMilliseconds)

Set a fixed Unix Epoch milliseconds value to generate UUIDs. This method is useful for unit tests.

Type Parameters:

T - type parameter

Parameters:

unixMilliseconds - a Unix Epoch milliseconds value

Returns:

AbstractTimeBasedUuidCreator

withNodeIdentifier

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

Set a fixed node identifier to generate UUIDs.

Type Parameters:

T - type parameter

Parameters:

nodeIdentifier - a node identifier

Returns:

AbstractTimeBasedUuidCreator

withHardwareAddressNodeIdentifier

public <T extends AbstractTimeBasedUuidCreator> T withHardwareAddressNodeIdentifier()

Set the node identifier to be a real hardware address of the host machine.

Type Parameters:

T - type parameter

Returns:

AbstractTimeBasedUuidCreator

withFingerprintNodeIdentifier

public <T extends AbstractTimeBasedUuidCreator> T withFingerprintNodeIdentifier()

Set the node identifier to be a system data hash. The node identifier is calculated using these system data: OS + JVM + network details + system resources. The resulting node identifier is as unique and mutable as the host machine. Read: https://en.wikipedia.org/wiki/Device_fingerprint

Type Parameters:

T - type parameter

Returns:

AbstractTimeBasedUuidCreator

withRandomNodeIdentifier

public <T extends AbstractTimeBasedUuidCreator> T withRandomNodeIdentifier()

Set the node identifier to be a random identifier. Each UUID generated will have a different random node identifier.

Type Parameters:

T - type parameter

Returns:

AbstractTimeBasedUuidCreator

withRandomNodeIdentifier

public <T extends AbstractTimeBasedUuidCreator> T withRandomNodeIdentifier(Random random)

Set the node identifier to be a random identifier. Each UUID generated will have a different random node identifier.

Type Parameters:

T - type parameter

Parameters:

random - a random number generator

Returns:

AbstractTimeBasedUuidCreator

withClockSequence

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

Set a fixed clock sequence value to generate UUIDs. The clock sequence has a range from 0 to 16,383 (0x3fff).

Type Parameters:

T - type parameter

Parameters:

clockSequence - a clock sequence

Returns:

AbstractTimeBasedUuidCreator

withoutOverrunException

public <T extends AbstractTimeBasedUuidCreator> T withoutOverrunException()

Used to disable the overrun exception. An exception thrown when more than 10 thousand requests are made within the same millisecond. This method disables the exception. This method works only with the DefaultTimestampStrategy. So don't use this method if you want the creator to use another TimestampStrategy.

Returns:

AbstractTimeBasedUuidCreator

formatMostSignificantBits

protected abstract long formatMostSignificantBits(long timestamp)

Formats the most significant bits of the UUID.

Parameters:

timestamp - a timestamp

Returns:

the MSB

formatLeastSignificantBits

protected long formatLeastSignificantBits(long nodeIdentifier,
                                          long clockSequence)

Formats 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