UUID Creator

This is a Java library for generating Universally Unique Identifiers.

List of implemented UUID types:

• UUID Version 1: the Gregorian time-based type specified in RFC-4122;
• UUID Version 2: the DCE Security type with embedded POSIX UIDs specified in DCE 1.1;
• UUID Version 3: the name-based type specified in RFC-4122 that uses MD5 hashing;
• UUID Version 4: the randomly or pseudo-randomly generated type specified in RFC-4122;
• UUID Version 5: the name-based type specified in RFC-4122 that uses SHA1 hashing;
• UUID Version 6: the reordered Gregorian time-based type specified as a new UUID format;
• UUID Version 7: the Unix Epoch time-based type specified as a new UUID format.

This library solves some of the JDK's UUID issues:

Problem	Solution
UUID has no method to generate time-based UUIDs (UUIDv1).	Use UuidCreator.getTimeBased() or GUID.v1().
UUID has no method to generate SHA1 UUIDs (UUIDv5).	Use UuidCreator.getNameBasedSha1() or GUID.v5().
UUID has no validation method, which makes developers use UUID.fromString() or regular expression for validation.	Use UuidValidator or GUID.valid().
UUID.nameUUIDFromBytes(), which generates MD5 UUIDs (UUIDv3), does not have a namespace parameter as required by the standard.	Use UuidCreator.getNameBasedMd5() or GUID.v3().
Some methods such as UUID.timestamp() are strongly related to UUIDv1, even though it's impossible to generate UUIDv1.	Use UuidUtil.
UUID.randomUUID() can be slow due to lack of entropy in the operating system.	Use UuidCreator.getRandomBasedFast() or GUID.v4(). However, both are not cryptographically secure.
UUID.compareTo() behaves unexpectedly due to signed long comparisons, causing non-alphabetical sorting.	Use UuidComparator.
UUID.fromString() allows non-canonical strings like 0-0-0-0-0 as valid UUID strings.	Use UuidCreator.fromString() or new GUID().

There's a micro benchmark and a good amount of unit tests.

The jar file can be downloaded directly from maven.org.

Read the Wiki pages and the Javadocs.

Dependency

Maven:

<dependency>
  <groupId>com.github.f4b6a3</groupId>
  <artifactId>uuid-creator</artifactId>
  <version>5.3.7</version>
</dependency>

Gradle:

implementation 'com.github.f4b6a3:uuid-creator:5.3.3'

See more options in maven.org.

Modularity

Module and bundle names are the same as the root package name.

• JPMS module name: com.github.f4b6a3.uuid
• OSGi symbolic name: com.github.f4b6a3.uuid

Usage

All UUID types can be created from the facade UuidCreator.

The goal of this class is to make most of the library's functionality available in a single place so that you developers don't have to worry about the internals of the library. All you need is to decide which type of UUID you need for your application and call the respective generation method. If in doubt, read the documentation and check the source code.

Create a UUIDv1:

UUID uuid = UuidCreator.getTimeBased();

Create a UUIDv2:

UUID uuid = UuidCreator.getDceSecurity(UuidLocalDomain.LOCAL_DOMAIN_PERSON, 1234);

Create a UUIDv3:

UUID uuid = UuidCreator.getNameBasedMd5(UuidNamespace.NAMESPACE_URL, "https://github.com/");

Create a UUIDv4:

UUID uuid = UuidCreator.getRandomBased();

Create a UUIDv5:

UUID uuid = UuidCreator.getNameBasedSha1(UuidNamespace.NAMESPACE_URL, "https://github.com/");

Create a UUIDv6:

UUID uuid = UuidCreator.getTimeOrdered();

Create a UUIDv7:

UUID uuid = UuidCreator.getTimeOrderedEpoch();

The library can do a lot more than the examples above (much more than I should have done, but it's too late). So I sincerely hope most people are happy with this.

Alternative

GUID is an alternative implementation to the classic JDK's UUID. It also serves as a standalone generator, independent from the rest of the library. This may result in fewer classes being loaded.

This new API was also designed to be an alternative to UuidCreator with three goals in mind: clean interface, simple implementation, and high performance. It was inspired by popular libraries for Javascript and Python.

It also does not block during GUID generation due to the non-cryptographic random number generator used by its factory methods. However, it is not recommended when the security of “cryptographic quality” generators is considered necessary.

GUID guid = GUID.v1();

GUID guid = GUID.v2(GUID.LOCAL_DOMAIN_PERSON, 1234);

GUID guid = GUID.v3(GUID.NAMESPACE_DNS, "www.example.com");

GUID guid = GUID.v4();

GUID guid = GUID.v5(GUID.NAMESPACE_DNS, "www.example.com");

GUID guid = GUID.v6();

GUID guid = GUID.v7();

From GUID to UUID

You can generate JDK's UUIDs using GUID's API. For example, you can generate a JDK's UUID version 7 with this statement:

UUID uuid = GUID.v7().toUUID();

When you call toUUID() the internal value of GUID is copied to the new JDK's UUID.

Deprecation

The methods which use a UUID as a "name" parameter such as UuidCreator.getNameBasedMd5(UUID name) are deprecated. They will be removed when the new RFC is published. For more details, please read #91.

The v8() method of the alternative GUID class is also deprecated due to sudden changes in the latest RFC draft.

Other identifier generators

Check out the other ID generators from the same family:

• ULID Creator: Universally Unique Lexicographically Sortable Identifiers
• TSID Creator: Time Sortable Identifiers
• KSUID Creator: K-Sortable Unique Identifiers

License

This library is Open Source software released under the MIT license.