Package com.github.f4b6a3.uuid.creator

Class AbstractTimeBasedUuidCreator

    • Constructor Detail

      • AbstractTimeBasedUuidCreator

        protected AbstractTimeBasedUuidCreator​(UuidVersion version)

    • Method Detail

      • create

        public UUID create()
        Returns a 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
        The node identifier can be: - The host MAC address; - The hash of system data; - A user defined number; - A random number. The node identifier can be controlled by defining a system property 'uuidcreator.node' or an environment variable 'UUIDCREATOR_NODE'. Both property and variable accept one of three options: - The string "mac" for using the MAC address; - The string "hash" for using the system data hash; - The string representation of a number between 0 and 2^48-1. If no property or variable is defined, the node identifier is randomly chosen. ### 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

      • create

        public UUID create​(Instant instant,
                   Integer clockseq,
                   Long nodeid)
        Returns a time-based UUID. This method overrides some or all parts of the new UUID. For example, If you need to replace the default node identifier, you can pass another node identifier as argument. The timestamp has 100-nanos resolution, but its accuracy depends on the argument passed. In some JVMs the Instant accuracy may be limited to milliseconds, for example, in the OpenJDK-8. The node identifier range is from 0 to 281474976710655 (2^48 - 1). If the value passed by argument is out of range, the result of MOD 2^48 is used instead. The clock sequence range is from 0 to 16383 (2^14 - 1). If the value passed by argument is out of range, the result of MOD 2^14 is used instead. The null arguments are ignored. If all arguments are null, this method works exactly as the method create().
        Parameters:
        instant - an alternate instant
        clockseq - an alternate clock sequence (0 to 16,383)
        nodeid - an alternate node (0 to 2^48)
        Returns:
        UUID a UUID value
        Throws:
        UuidCreatorException - an overrun exception if more than 10 thousand UUIDs are requested within the same millisecond

      • formatMostSignificantBits

        protected long formatMostSignificantBits​(long timestamp)
        Returns the timestamp bits of the UUID version 1 in the order defined in the RFC-4122. ### RFC-4122 - 4.2.2. Generation Details Determine the values for the UTC-based timestamp and clock sequence to be used in the UUID, as described in Section 4.2.1. For the purposes of this algorithm, consider the timestamp to be a 60-bit unsigned integer and the clock sequence to be a 14-bit unsigned integer. Sequentially number the bits in a field, starting with zero for the least significant bit. "Set the time_low field equal to the least significant 32 bits (bits zero through 31) of the timestamp in the same order of significance. Set the time_mid field equal to bits 32 through 47 from the timestamp in the same order of significance. Set the 12 least significant bits (bits zero through 11) of the time_hi_and_version field equal to bits 48 through 59 from the timestamp in the same order of significance. Set the four most significant bits (bits 12 through 15) of the time_hi_and_version field to the 4-bit version number corresponding to the UUID version being created, as shown in the table above."
        Parameters:
        timestamp - a timestamp
        Returns:
        the MSB

      • formatLeastSignificantBits

        protected 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

      • selectNodeIdentifierStrategy

        protected static NodeIdentifierStrategy selectNodeIdentifierStrategy()
        Select the node identifier strategy. This method reads the system property 'uuidcreator.node' and the environment variable 'UUIDCREATOR_NODE' to decide what node identifier strategy 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 representation of a number in octal, hexadecimal or decimal format, the generator will use the number represented. 4. Else, a random number will be used by the generator.