search

f4b6a3 / uuid-creator

UUID Creator is a Java library for generating Universally Unique Identifiers.
MIT License
430 stars 44 forks source link
guid id java rfc-4122 rfc-9562 uuid

readme

UUID Creator

This is a Java library for generating Universally Unique Identifiers.

This library is fully compliant with RFC 9562, the Internet standard which obsoletes RFC 4122.

List of implemented UUID subtypes:

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

Problem Solution
UUID can't generate Gregorian time-based UUIDs (UUIDv1). Use [UuidCreator.getTimeBased()](https://javadoc.io/static/com.github.f4b6a3/uuid-creator/5.3.7/com.github.f4b6a3.uuid/com/github/f4b6a3/uuid/UuidCreator.html#getTimeBased()).
UUID can't generate SHA-1 UUIDs (UUIDv5). Use UuidCreator.getNameBasedSha1()
UUID.nameUUIDFromBytes(), which generates MD5 UUIDs (UUIDv3), does not have a namespace parameter as required by the standard. Use UuidCreator.getNameBasedMd5()
UUID has no validation method, which makes developers use UUID.fromString() or regular expression for validation. Use UuidValidator.isValid().
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()](https://javadoc.io/static/com.github.f4b6a3/uuid-creator/5.3.7/com.github.f4b6a3.uuid/com/github/f4b6a3/uuid/UuidCreator.html#getRandomBasedFast()).
However, keep in mind that it is not cryptographically secure.
UUID.compareTo() behaves unexpectedly due to signed long comparisons, causing non-alphabetical sorting. Use UuidComparator.
UUID.fromString() allows non-standard strings like 0-0-0-0-0 as valid UUID strings. Use UuidCreator.fromString().

This project contains a micro benchmark and a good amount of unit tests, with more than 90% coverage.

For more information, read the the Javadocs and the Wiki pages.

NOTE: This software is not supported or maintained by any organization. This information may be useful when having an organization behind a project is a criterion for deciding whether software can be adopted or not.

Dependency

Maven:

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

Gradle:

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

See more options in maven.org.

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

Modularity

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

Usage

All UUID subtypes can be created from the facade UuidCreator.

The goal of the facade is to make most of the library's functionality available in a single place so that you don't have to worry about the internals of the library. All you need is to decide which UUID subtype you need for your application and call the respective generation method. If in doubt, read the documentation and check out 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();

NOTE: A UUID version is a UUID subtype. The word "version" is not used in the sense that a higher version number makes the previous one obsolete. There are 8 subtypes of UUID and each of them is assigned a number; for example, a UUIDv7 is a UUID of subtype 7. Likewise, a UUID variant is a UUID type. There are 4 types of UUID: (1) the prehistoric one, (2) the one described in RFC 9562, (3) the one belonging to Microsoft and (4) the one reserved for the future. RFC 9562 retains the terms “version” and “variant” for compatibility with previous specifications and existing implementations.

Alternative API

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.

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();

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

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

NOTE: It uses a non-cryptographic PRNG. So it doesn't block when generating random-based UUIDs. However, it is not recommended when the security provided by “cryptographic quality” generators is considered necessary.

Other identifier generators

Check out the other ID generators from the same family:

License

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

Personal Notes:

  1. The library can do much more than the examples shown in this document (much more than I should have done). I hope most people find this project useful. In other words, your like is my payment.
  2. The name of this software is UUID Creator or uuid-creator. Use "com.github.f4b6a3" or "f4b6a3" only when necessary to avoid doubt, as this is just a unique package name to follow Java convention (now I know it wasn't a good idea).