Package com.github.f4b6a3.ulid.creator

Class UlidBasedGuidCreator

  • public class UlidBasedGuidCreator
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 Detail

      • randomMsb

        protected long randomMsb

      • randomLsb

        protected long randomLsb

      • randomLsbMax

        protected long randomLsbMax

      • randomMsbMax

        protected long randomMsbMax

      • HALF_RANDOM_COMPONENT

        protected static final long HALF_RANDOM_COMPONENT
        See Also:
        Constant Field Values

      • previousTimestamp

        protected long previousTimestamp

      • random

        protected Random random

    • Constructor Detail

      • UlidBasedGuidCreator

        public UlidBasedGuidCreator()

    • Method Detail

      • create

        public UUID create()
        Return a GUID based on the ULID specification. A ULID 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. The random part is generated by a secure random number generator: SecureRandom. ### 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 GUID value
        Throws:
        UlidCreatorException - an overrun exception if too many requests are made within the same millisecond.

      • createString

        public String createString()
        Returns a ULID string. The returning string is encoded to Crockford's base32.
        Returns:
        a ULID string

      • 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, although it's extremely unlikely to occur.
        Throws:
        UlidCreatorException - if an overrun happens.

      • withRandomGenerator

        public <T extends UlidBasedGuidCreator> 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:
        UlidBasedGuidCreator

      • withFastRandomGenerator

        public <T extends UlidBasedGuidCreator> 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:
        UlidBasedGuidCreator

      • truncate

        protected long truncate​(long value)
        Truncate long to half random component.
        Parameters:
        value - a value to be truncated.
        Returns:
        truncated value

      • extractRandomLsb

        protected long extractRandomLsb​(UUID uuid)
        For unit tests

      • extractRandomMsb

        protected long extractRandomMsb​(UUID uuid)
        For unit tests