Module com.github.f4b6a3.uuid
Package com.github.f4b6a3.uuid

Class UuidCreator

  • public final class UuidCreator
extends Object
    Facade for everything.

    All UUID types can be generated from this entry point.

    • Method Detail

      • toBytes

        public static byte[] toBytes​(UUID uuid)
        Returns an array of bytes from a UUID.
        Parameters:
        uuid - a UUID
        Returns:
        an array of bytes
        Throws:
        InvalidUuidException - if the argument is invalid

      • fromBytes

        public static UUID fromBytes​(byte[] uuid)
        Returns a UUID from a byte array.

        It also checks if the input byte array is valid.

        Parameters:
        uuid - a byte array
        Returns:
        a UUID
        Throws:
        InvalidUuidException - if the argument is invalid

      • toString

        public static String toString​(UUID uuid)
        Returns a string from a UUID.

        It can be much faster than UUID.toString() in JDK 8.

        Parameters:
        uuid - a UUID
        Returns:
        a UUID string
        Throws:
        InvalidUuidException - if the argument is invalid

      • fromString

        public static UUID fromString​(String uuid)
        Returns a UUID from a string.

        It accepts strings:

        • With URN prefix: "urn:uuid:";
        • With curly braces: '{' and '}';
        • With upper or lower case;
        • With or without hyphens.

        It can be much faster than UUID.fromString(String) in JDK 8.

        It also can be twice as fast as UUID.fromString(String) in JDK 11.

        Parameters:
        uuid - a UUID string
        Returns:
        a UUID
        Throws:
        InvalidUuidException - if the argument is invalid

      • getNil

        public static UUID getNil()
        Returns a Nil UUID.

        Nil UUID is a special UUID that has all 128 bits set to ZERO.

        The canonical string of Nil UUID is 00000000-0000-0000-0000-000000000000.

        Returns:
        a Nil UUID

      • getMax

        public static UUID getMax()
        Returns a Max UUID.

        Max UUID is a special UUID that has all 128 bits set to ONE.

        The canonical string of Max UUID is FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF.

        Returns:
        a Max UUID
        Since:
        5.0.0
        See Also:
        New UUID Formats

      • getRandomBased

        public static UUID getRandomBased()
        Returns a random-based unique identifier (UUIDv4).
        Returns:
        a UUIDv4
        See Also:
        RandomBasedFactory

      • getRandomBasedFast

        public static UUID getRandomBasedFast()
        Returns a fast random-based unique identifier (UUIDv4).

        It employs SplittableRandom which works very well, although not cryptographically strong.

        Security-sensitive applications that require a cryptographically secure pseudo-random generator should use getRandomBased().

        Returns:
        a UUIDv4
        Since:
        5.2.0
        See Also:
        RandomBasedFactory, SplittableRandom

      • getTimeBased

        public static UUID getTimeBased()
        Returns a time-based unique identifier (UUIDv1).

        The default node identifier is a random number that is generated once at initialization.

        A custom node identifier can be provided by the system property 'uuidcreator.node' or the environment variable 'UUIDCREATOR_NODE'.

        Returns:
        a UUIDv1
        See Also:
        TimeBasedFactory

      • getTimeBasedWithMac

        public static UUID getTimeBasedWithMac()
        Returns a time-based unique identifier (UUIDv1).

        The node identifier is a MAC address that is obtained once at initialization.

        Returns:
        a UUIDv1
        See Also:
        TimeBasedFactory

      • getTimeBasedWithHash

        public static UUID getTimeBasedWithHash()
        Returns a time-based unique identifier (UUIDv1).

        The node identifier is a hash that is calculated once at initialization.

        The hash input is a string containing host name, MAC and IP.

        Returns:
        a UUIDv1
        See Also:
        TimeBasedFactory, MachineId

      • getTimeBasedWithRandom

        public static UUID getTimeBasedWithRandom()
        Returns a time-based unique identifier (UUIDv1).

        The node identifier is a random number that is generated with each method invocation.

        Returns:
        a UUIDv1
        See Also:
        TimeBasedFactory

      • getTimeBased

        public static UUID getTimeBased​(Instant instant,
                                Integer clockseq,
                                Long nodeid)
        Returns a time-based unique identifier (UUIDv1).

        Instant accuracy is be limited to 1 millisecond on Linux with JDK 8. On Windows, its accuracy may be limited to 15.625ms (64hz).

        The clock sequence is a number between 0 and 16383 (2^14 - 1). If the value passed as an argument is out of range, the result of MOD 2^14 will be used.

        The node identifier is a number between 0 and 281474976710655 (2^48 - 1). If the value passed as an argument is out of range, the result of MOD 2^48 will be used.

        Null arguments are ignored. If all arguments are null, this method works just like method getTimeBased().

        Parameters:
        instant - an alternate instant
        clockseq - an alternate clock sequence between 0 and 2^14-1
        nodeid - an alternate node identifier between 0 and 2^48-1
        Returns:
        a UUIDv1
        See Also:
        TimeBasedFactory

      • getTimeOrdered

        public static UUID getTimeOrdered()
        Returns a time-ordered unique identifier (UUIDv6).

        The default node identifier is a random number that is generated once at initialization.

        A custom node identifier can be provided by the system property 'uuidcreator.node' or the environment variable 'UUIDCREATOR_NODE'.

        Returns:
        a UUIDv6
        See Also:
        TimeOrderedFactory, New UUID Formats

      • getTimeOrderedWithMac

        public static UUID getTimeOrderedWithMac()
        Returns a time-ordered unique identifier (UUIDv6).

        The node identifier is a MAC address that is obtained once at initialization.

        Returns:
        a UUIDv6
        See Also:
        TimeOrderedFactory, New UUID Formats

      • getTimeOrderedWithHash

        public static UUID getTimeOrderedWithHash()
        Returns a time-ordered unique identifier (UUIDv6).

        The node identifier is a hash that is calculated once at initialization.

        The hash input is a string containing host name, MAC and IP.

        Returns:
        a UUIDv6
        See Also:
        TimeOrderedFactory, MachineId, New UUID Formats

      • getTimeOrderedWithRandom

        public static UUID getTimeOrderedWithRandom()
        Returns a time-ordered unique identifier (UUIDv6).

        The node identifier is a random number that is generated with each method invocation.

        Returns:
        a UUIDv6
        See Also:
        TimeOrderedFactory, New UUID Formats

      • getTimeOrdered

        public static UUID getTimeOrdered​(Instant instant,
                                  Integer clockseq,
                                  Long nodeid)
        Returns a time-ordered unique identifier (UUIDv6).

        Instant accuracy is be limited to 1 millisecond on Linux with JDK 8. On Windows, its accuracy may be limited to 15.625ms (64hz).

        The clock sequence is a number between 0 and 16383 (2^14 - 1). If the value passed as an argument is out of range, the result of MOD 2^14 will be used.

        The node identifier is a number between 0 and 281474976710655 (2^48 - 1). If the value passed as an argument is out of range, the result of MOD 2^48 will be used.

        Null arguments are ignored. If all arguments are null, this method works just like method getTimeOrdered().

        Parameters:
        instant - an alternate instant
        clockseq - an alternate clock sequence between 0 and 2^14-1
        nodeid - an alternate node identifier between 0 and 2^48-1
        Returns:
        a UUIDv6
        See Also:
        TimeOrderedFactory, New UUID Formats

      • getTimeOrderedEpoch

        public static UUID getTimeOrderedEpoch()
        Returns a time-ordered unique identifier that uses Unix Epoch (UUIDv7).

        The identifier has 3 parts: time, counter and random.

        The counter bits are incremented by 1 when the time repeats.

        The random bits are generated with each method invocation.

        Returns:
        a UUIDv7
        Since:
        5.0.0
        See Also:
        TimeOrderedEpochFactory, New UUID Formats

      • getTimeOrderedEpochPlus1

        public static UUID getTimeOrderedEpochPlus1()
        Returns a time-ordered unique identifier that uses Unix Epoch (UUIDv7).

        The identifier has 2 parts: time and monotonic random.

        The monotonic random bits are incremented by 1 when the time repeats.

        Returns:
        a UUIDv7
        Since:
        5.0.0
        See Also:
        TimeOrderedEpochFactory, New UUID Formats

      • getTimeOrderedEpochPlusN

        public static UUID getTimeOrderedEpochPlusN()
        Returns a time-ordered unique identifier that uses Unix Epoch (UUIDv7).

        The identifier has 2 parts: time and monotonic random.

        The monotonic random bits are incremented by a random number between 1 and 2^32 when the time repeats.

        Returns:
        a UUIDv7
        Since:
        5.0.0
        See Also:
        TimeOrderedEpochFactory, New UUID Formats

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(String name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).

        The name string is encoded into a sequence of bytes using UTF-8.

        Parameters:
        name - a string
        Returns:
        a UUIDv3
        See Also:
        NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(byte[] name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).
        Parameters:
        name - a byte array
        Returns:
        a UUIDv3
        See Also:
        NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(UUID name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).
        Parameters:
        name - a UUID
        Returns:
        a UUIDv3
        See Also:
        NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(UUID namespace,
                                   String name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).

        The name string is encoded into a sequence of bytes using UTF-8.

        Parameters:
        namespace - a custom name space UUID
        name - a string
        Returns:
        a UUIDv3
        See Also:
        UuidNamespace, NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(UUID namespace,
                                   byte[] name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).
        Parameters:
        namespace - a custom name space UUID
        name - a byte array
        Returns:
        a UUIDv3
        See Also:
        UuidNamespace, NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(UUID namespace,
                                   UUID name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).
        Parameters:
        namespace - a custom name space UUID
        name - a UUID
        Returns:
        a UUIDv3
        See Also:
        UuidNamespace, NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(String namespace,
                                   String name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).

        The name string is encoded into a sequence of bytes using UTF-8.

        Parameters:
        namespace - a custom name space UUID in string format
        name - a string
        Returns:
        a UUIDv3
        Throws:
        InvalidUuidException - if namespace is invalid
        See Also:
        UuidNamespace, NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(String namespace,
                                   byte[] name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).
        Parameters:
        namespace - a custom name space UUID in string format
        name - a byte array
        Returns:
        a UUIDv3
        Throws:
        InvalidUuidException - if namespace is invalid
        See Also:
        UuidNamespace, NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(String namespace,
                                   UUID name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).
        Parameters:
        namespace - a custom name space UUID in string format
        name - a UUID
        Returns:
        a UUIDv3
        Throws:
        InvalidUuidException - if namespace is invalid
        See Also:
        UuidNamespace, NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(UuidNamespace namespace,
                                   String name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).

        The name string is encoded into a sequence of bytes using UTF-8.

        Name spaces predefined by RFC-4122 (Appendix C):

        • NAMESPACE_DNS: Name string is a fully-qualified domain name;
        • NAMESPACE_URL: Name string is a URL;
        • NAMESPACE_OID: Name string is an ISO OID;
        • NAMESPACE_X500: Name string is an X.500 DN (in DER or text format).
        Parameters:
        namespace - a predefined name space enumeration
        name - a string
        Returns:
        a UUIDv3
        See Also:
        UuidNamespace, NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(UuidNamespace namespace,
                                   byte[] name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).

        Name spaces predefined by RFC-4122 (Appendix C):

        • NAMESPACE_DNS: Name string is a fully-qualified domain name;
        • NAMESPACE_URL: Name string is a URL;
        • NAMESPACE_OID: Name string is an ISO OID;
        • NAMESPACE_X500: Name string is an X.500 DN (in DER or text format).
        Parameters:
        namespace - a predefined name space enumeration
        name - a byte array
        Returns:
        a UUIDv3
        See Also:
        UuidNamespace, NameBasedMd5Factory

      • getNameBasedMd5

        public static UUID getNameBasedMd5​(UuidNamespace namespace,
                                   UUID name)
        Returns a name-based unique identifier that uses MD5 hashing (UUIDv3).

        Name spaces predefined by RFC-4122 (Appendix C):

        • NAMESPACE_DNS: Name string is a fully-qualified domain name;
        • NAMESPACE_URL: Name string is a URL;
        • NAMESPACE_OID: Name string is an ISO OID;
        • NAMESPACE_X500: Name string is an X.500 DN (in DER or text format).
        Parameters:
        namespace - a predefined name space enumeration
        name - a UUID
        Returns:
        a UUIDv3
        See Also:
        UuidNamespace, NameBasedMd5Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(String name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).

        The name string is encoded into a sequence of bytes using UTF-8.

        Parameters:
        name - a string
        Returns:
        a UUIDv5
        See Also:
        NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(byte[] name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).
        Parameters:
        name - a byte array
        Returns:
        a UUIDv5
        See Also:
        NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(UUID name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).
        Parameters:
        name - a UUID
        Returns:
        a UUIDv5
        See Also:
        NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(UUID namespace,
                                    String name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).

        The name string is encoded into a sequence of bytes using UTF-8.

        Parameters:
        namespace - a custom name space UUID
        name - a string
        Returns:
        a UUIDv5
        See Also:
        UuidNamespace, NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(UUID namespace,
                                    byte[] name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).
        Parameters:
        namespace - a custom name space UUID
        name - a byte array
        Returns:
        a UUIDv5
        See Also:
        UuidNamespace, NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(UUID namespace,
                                    UUID name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).
        Parameters:
        namespace - a custom name space UUID
        name - a UUID
        Returns:
        a UUIDv5
        See Also:
        UuidNamespace, NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(String namespace,
                                    String name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).

        The name string is encoded into a sequence of bytes using UTF-8.

        Parameters:
        namespace - a custom name space UUID in string format
        name - a string
        Returns:
        a UUIDv5
        Throws:
        InvalidUuidException - if namespace is invalid
        See Also:
        UuidNamespace, NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(String namespace,
                                    byte[] name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).
        Parameters:
        namespace - a custom name space UUID in string format
        name - a byte array
        Returns:
        a UUIDv5
        Throws:
        InvalidUuidException - if namespace is invalid
        See Also:
        UuidNamespace, NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(String namespace,
                                    UUID name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).
        Parameters:
        namespace - a custom name space UUID in string format
        name - a UUID
        Returns:
        a UUIDv5
        Throws:
        InvalidUuidException - if namespace is invalid
        See Also:
        UuidNamespace, NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(UuidNamespace namespace,
                                    String name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).

        The name string is encoded into a sequence of bytes using UTF-8.

        Name spaces predefined by RFC-4122 (Appendix C):

        • NAMESPACE_DNS: Name string is a fully-qualified domain name;
        • NAMESPACE_URL: Name string is a URL;
        • NAMESPACE_OID: Name string is an ISO OID;
        • NAMESPACE_X500: Name string is an X.500 DN (in DER or text format).
        Parameters:
        namespace - a predefined name space enumeration
        name - a string
        Returns:
        a UUIDv5
        See Also:
        UuidNamespace, NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(UuidNamespace namespace,
                                    byte[] name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).

        Name spaces predefined by RFC-4122 (Appendix C):

        • NAMESPACE_DNS: Name string is a fully-qualified domain name;
        • NAMESPACE_URL: Name string is a URL;
        • NAMESPACE_OID: Name string is an ISO OID;
        • NAMESPACE_X500: Name string is an X.500 DN (in DER or text format).
        Parameters:
        namespace - a predefined name space enumeration
        name - a byte array
        Returns:
        a UUIDv5
        See Also:
        UuidNamespace, NameBasedSha1Factory

      • getNameBasedSha1

        public static UUID getNameBasedSha1​(UuidNamespace namespace,
                                    UUID name)
        Returns a name-based unique identifier that uses SHA-1 hashing (UUIDv5).

        Name spaces predefined by RFC-4122 (Appendix C):

        • NAMESPACE_DNS: Name string is a fully-qualified domain name;
        • NAMESPACE_URL: Name string is a URL;
        • NAMESPACE_OID: Name string is an ISO OID;
        • NAMESPACE_X500: Name string is an X.500 DN (in DER or text format).
        Parameters:
        namespace - a predefined name space enumeration
        name - a UUID
        Returns:
        a UUIDv5
        See Also:
        UuidNamespace, NameBasedSha1Factory

      • getDceSecurity

        public static UUID getDceSecurity​(byte localDomain,
                                  int localIdentifier)
        Returns a DCE Security unique identifier (UUIDv2).
        Parameters:
        localDomain - a custom local domain byte
        localIdentifier - a local identifier
        Returns:
        a UUIDv2
        See Also:
        UuidLocalDomain, DceSecurityFactory

      • getDceSecurityWithMac

        public static UUID getDceSecurityWithMac​(byte localDomain,
                                         int localIdentifier)
        Returns a DCE Security unique identifier (UUIDv2).
        Parameters:
        localDomain - a custom local domain byte
        localIdentifier - a local identifier
        Returns:
        a UUIDv2
        See Also:
        UuidLocalDomain, DceSecurityFactory

      • getDceSecurityWithHash

        public static UUID getDceSecurityWithHash​(byte localDomain,
                                          int localIdentifier)
        Returns a DCE Security unique identifier (UUIDv2).
        Parameters:
        localDomain - a custom local domain byte
        localIdentifier - a local identifier
        Returns:
        a UUIDv2
        See Also:
        UuidLocalDomain, DceSecurityFactory

      • getDceSecurityWithRandom

        public static UUID getDceSecurityWithRandom​(byte localDomain,
                                            int localIdentifier)
        Returns a DCE Security unique identifier (UUIDv2).
        Parameters:
        localDomain - a custom local domain byte
        localIdentifier - a local identifier
        Returns:
        a UUIDv2
        See Also:
        UuidLocalDomain, DceSecurityFactory

      • getDceSecurity

        public static UUID getDceSecurity​(UuidLocalDomain localDomain,
                                  int localIdentifier)
        Returns a DCE Security unique identifier (UUIDv2).

        Local domains predefined by DCE 1.1 Authentication and Security Services (Chapter 11):

        • LOCAL_DOMAIN_PERSON: 0 (interpreted as POSIX UID domain);
        • LOCAL_DOMAIN_GROUP: 1 (interpreted as POSIX GID domain);
        • LOCAL_DOMAIN_ORG: 2.
        Parameters:
        localDomain - a predefined local domain enumeration
        localIdentifier - a local identifier
        Returns:
        a UUIDv2
        See Also:
        UuidLocalDomain, DceSecurityFactory

      • getDceSecurityWithMac

        public static UUID getDceSecurityWithMac​(UuidLocalDomain localDomain,
                                         int localIdentifier)
        Returns a DCE Security unique identifier (UUIDv2).

        Local domains predefined by DCE 1.1 Authentication and Security Services (Chapter 11):

        • LOCAL_DOMAIN_PERSON: 0 (interpreted as POSIX UID domain);
        • LOCAL_DOMAIN_GROUP: 1 (interpreted as POSIX GID domain);
        • LOCAL_DOMAIN_ORG: 2.
        Parameters:
        localDomain - a predefined local domain enumeration
        localIdentifier - a local identifier
        Returns:
        a UUIDv2
        See Also:
        UuidLocalDomain, DceSecurityFactory

      • getDceSecurityWithHash

        public static UUID getDceSecurityWithHash​(UuidLocalDomain localDomain,
                                          int localIdentifier)
        Returns a DCE Security unique identifier (UUIDv2).

        Local domains predefined by DCE 1.1 Authentication and Security Services (Chapter 11):

        • LOCAL_DOMAIN_PERSON: 0 (interpreted as POSIX UID domain);
        • LOCAL_DOMAIN_GROUP: 1 (interpreted as POSIX GID domain);
        • LOCAL_DOMAIN_ORG: 2.
        Parameters:
        localDomain - a predefined local domain enumeration
        localIdentifier - a local identifier
        Returns:
        a UUIDv2
        See Also:
        UuidLocalDomain, DceSecurityFactory

      • getDceSecurityWithRandom

        public static UUID getDceSecurityWithRandom​(UuidLocalDomain localDomain,
                                            int localIdentifier)
        Returns a DCE Security unique identifier (UUIDv2).

        Local domains predefined by DCE 1.1 Authentication and Security Services (Chapter 11):

        • LOCAL_DOMAIN_PERSON: 0 (interpreted as POSIX UID domain);
        • LOCAL_DOMAIN_GROUP: 1 (interpreted as POSIX GID domain);
        • LOCAL_DOMAIN_ORG: 2.
        Parameters:
        localDomain - a predefined local domain enumeration
        localIdentifier - a local identifier
        Returns:
        a UUIDv2
        See Also:
        UuidLocalDomain, DceSecurityFactory

      • getShortPrefixComb

        public static UUID getShortPrefixComb()
        Returns n Short Prefix COMB GUID.

        The creation minute is a 2 bytes PREFIX is at the MOST significant bits.

        The prefix wraps around every ~45 days (2^16/60/24 = ~45).

        Returns:
        a GUID
        See Also:
        ShortPrefixCombFactory, Sequential UUID Generators

      • getShortSuffixComb

        public static UUID getShortSuffixComb()
        Returns a Short Suffix COMB GUID.

        The creation minute is a 2 bytes SUFFIX is at the LEAST significant bits.

        The suffix wraps around every ~45 days (2^16/60/24 = ~45).

        Returns:
        a GUID
        See Also:
        ShortSuffixCombFactory, Sequential UUID Generators