com.github.f4b6a3.ulid.guid

Class GuidCreator

java.lang.Object

com.github.f4b6a3.ulid.guid.GuidCreator

public class GuidCreator
extends Object

Factory that creates lexicographically sortable GUIDs, based on the ULID specification - Universally Unique Lexicographically Sortable Identifier. ULID specification: https://github.com/ulid/spec

Field Summary

Fields

Modifier and Type	Field and Description
protected long	firstHigh
protected long	firstLow
protected long	high
protected long	low
protected static long	MASK_UNSIGNED_SHORT
protected static String	OVERRUN_MESSAGE
protected long	previousTimestamp
protected Random	random
protected TimestampStrategy	timestampStrategy

Constructor Summary

Constructors

Constructor and Description
GuidCreator()

Method Summary

Modifier and Type	Method and Description
UUID	create() Return a GUID based on the ULID specification.
byte[]	createBytes() Return a ULID as byte sequence.
String	createUlid() Return a ULID.
protected long	getTimestamp() Return the current timestamp and resets or increments the random part.
protected void	increment() Increment the random part of the GUID.
protected void	reset() Reset the random part of the GUID.
<T extends GuidCreator> T	withFastRandomGenerator() Replaces the default random generator with a faster one.
<T extends GuidCreator> T	withRandomGenerator(Random random) Replace the default random generator, in a fluent way, to another that extends Random.
<T extends GuidCreator> T	withTimestampStrategy(TimestampStrategy timestampStrategy) Used for changing the timestamp strategy.

Methods inherited from class java.lang.Object

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

Field Detail

low

protected long low

high

protected long high

firstLow

protected long firstLow

firstHigh

protected long firstHigh

previousTimestamp

protected long previousTimestamp

random

protected Random random

MASK_UNSIGNED_SHORT

protected static final long MASK_UNSIGNED_SHORT

See Also:

Constant Field Values

OVERRUN_MESSAGE

protected static final String OVERRUN_MESSAGE

See Also:

Constant Field Values

timestampStrategy

protected TimestampStrategy timestampStrategy

Constructor Detail

GuidCreator

public GuidCreator()

Method Detail

create

public UUID create()

Return a GUID based on the ULID specification. It has two parts: 1. A part of 48 bits that represent the amount of milliseconds since Unix Epoch, 1 January 1970. 2. A part of 80 bits that has a random value generated a secure random generator. The random part is reset to a new value every time the millisecond part changes. If more than one GUID is generated within the same millisecond, the random part is incremented by one. The maximum GUIDs that can be generated per millisecond is 2^80. ### Specification of Universally Unique Lexicographically Sortable ID #### Components ##### Timestamp It is a 48 bit integer. UNIX-time in milliseconds. Won't run out of space 'til the year 10889 AD. ##### Randomness It is a 80 bits integer. Cryptographically secure source of randomness, if possible. #### Sorting The left-most character must be sorted first, and the right-most character sorted last (lexical order). The default ASCII character set must be used. Within the same millisecond, sort order is not guaranteed. #### Monotonicity When generating a ULID within the same millisecond, we can provide some guarantees regarding sort order. Namely, if the same millisecond is detected, the random component is incremented by 1 bit in the least significant bit position (with carrying). If, in the extremely unlikely event that, you manage to generate more than 2^80 ULIDs within the same millisecond, or cause the random component to overflow with less, the generation will fail.

Returns:

UUID a UUID value

Throws:

UlidCreatorException - an overrun exception if too many requests are made within the same millisecond.

createUlid

public String createUlid()

Return a ULID.

Returns:

a ULID string

createBytes

public byte[] createBytes()

Return a ULID as byte sequence.

Returns:

a byte sequence

getTimestamp

protected long getTimestamp()

Return the current timestamp and resets or increments the random part.

Returns:

timestamp

reset

protected void reset()

Reset the random part of the GUID.

increment

protected void increment()

Increment the random part of the GUID. An exception is thrown when more than 2^80 increment operations are made.

Throws:

UlidCreatorException - if an overrun happens.

withTimestampStrategy

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

Used for changing the timestamp strategy.

Parameters:

timestampStrategy - a timestamp strategy

Returns:

GuidCreator

withRandomGenerator

public <T extends GuidCreator> T withRandomGenerator(Random random)

Replace the default random generator, in a fluent way, to another that extends Random. The default random generator is SecureRandom. For other faster pseudo-random generators, see XorshiftRandom and its variations. See Random.

Parameters:

random - a random generator

Returns:

GuidCreator

withFastRandomGenerator

public <T extends GuidCreator> T withFastRandomGenerator()

Replaces the default random generator with a faster one. The host fingerprint is used to generate a seed for the random number generator. See Xorshift128PlusRandom and FingerprintUtil.getFingerprint()

Returns:

GuidCreator