ulid-creator

A Java library for generating and handling ULIDs - Universally Unique Lexicographically Sortable Identifiers.

How to Use

Create a ULID:

String ulid = UlidCreator.getUlid();

Create a fast ULID:

String ulid = UlidCreator.getFastUlid();

Create a ULID as GUID object:

UUID ulid = UlidCreator.getGuid();

Create a fast ULID as GUID object:

UUID ulid = UlidCreator.getFastGuid();

Create a ULID as byte sequence:

byte[] ulid = UlidCreator.getBytes();

Create a fast ULID as byte sequence:

byte[] ulid = UlidCreator.getFastBytes();

Maven dependency

Add these lines to your pom.xml.

<!-- https://search.maven.org/artifact/com.github.f4b6a3/ulid-creator -->
<dependency>
  <groupId>com.github.f4b6a3</groupId>
  <artifactId>ulid-creator</artifactId>
  <version>1.0.0</version>
</dependency>

See more options in maven.org and mvnrepository.com.

Implementation

ULID

The ULID is a unique and sortable 26 char sequence. See the ULID specification for more information.

See the section on GUIDs to know how the 128 bits are generated in this library.

// ULIDs
String ulid = UlidCreator.getUlid();

Examples of ULIDs:

01E1PPRTMSQ34W7JR5YSND6B8T
01E1PPRTMSQ34W7JR5YSND6B8V
01E1PPRTMSQ34W7JR5YSND6B8W
01E1PPRTMSQ34W7JR5YSND6B8X
01E1PPRTMSQ34W7JR5YSND6B8Y
01E1PPRTMSQ34W7JR5YSND6B8Z
01E1PPRTMSQ34W7JR5YSND6B90
01E1PPRTMSQ34W7JR5YSND6B91
01E1PPRTMTYMX8G17TWSJJZMEE < millisecond changed
01E1PPRTMTYMX8G17TWSJJZMEF
01E1PPRTMTYMX8G17TWSJJZMEG
01E1PPRTMTYMX8G17TWSJJZMEH
01E1PPRTMTYMX8G17TWSJJZMEJ
01E1PPRTMTYMX8G17TWSJJZMEK
01E1PPRTMTYMX8G17TWSJJZMEM
01E1PPRTMTYMX8G17TWSJJZMEN
         ^ look          ^ look
                                   
|---------|--------------|
   milli     randomness

GUID

The GUIDs in this library are based on the ULID specification ^[9]. The first 48 bits represent the count of milliseconds since Unix Epoch, 1 January 1970. The remaining 60 bits are generated by a secure random number generator.

Every time the timestamp changes the random part is reset to a new random value. If the current timestamp is equal to the previous one, the random bits are incremented by 1.

The default random number generator is SecureRandom, but it's possible to use any RNG that extends Random.

// GUID based on ULID spec
UUID guid = UlidCreator.getGuid();

Examples of GUIDs based on ULID spec:

01706d6c-6aac-80bd-7ff5-f660c2dd58ea
01706d6c-6aac-80bd-7ff5-f660c2dd58eb
01706d6c-6aac-80bd-7ff5-f660c2dd58ec
01706d6c-6aac-80bd-7ff5-f660c2dd58ed
01706d6c-6aac-80bd-7ff5-f660c2dd58ee
01706d6c-6aac-80bd-7ff5-f660c2dd58ef
01706d6c-6aac-80bd-7ff5-f660c2dd58f0
01706d6c-6aac-80bd-7ff5-f660c2dd58f1
01706d6c-6aad-c795-370c-98d0be881bb8 < millisecond changed
01706d6c-6aad-c795-370c-98d0be881bb9
01706d6c-6aad-c795-370c-98d0be881bba
01706d6c-6aad-c795-370c-98d0be881bbb
01706d6c-6aad-c795-370c-98d0be881bbc
01706d6c-6aad-c795-370c-98d0be881bbd
01706d6c-6aad-c795-370c-98d0be881bbe
01706d6c-6aad-c795-370c-98d0be881bbf
            ^ look                 ^ look
                                   
|------------|---------------------|
  millisecs        randomness

How use the GuidCreator directly

These are some examples of using the GuidCreator to create ULIDs:

// with the default random generator (java.security.SecureRandom)
String ulid = UlidCreator.getGuidCreator().createUlid();
    
// with java random generator (java.util.Random)
String ulid = UlidCreator.getGuidCreator()
    .withRandomGenerator(new Random())
    .createUlid();

// with fast random generator (Xorshift128Plus)
String ulid = UlidCreator.getGuidCreator()
    .withFastRandomGenerator()
    .createUlid();

// with fast random generator (Xorshift128Plus with salt)
int salt = (int) FingerprintUtil.getFingerprint();
Random random = new Xorshift128PlusRandom(salt);
String ulid = UlidCreator.getGuidCreator()
    .withRandomGenerator(random)
    .createUlid();

If you use the GuidCreator directly, you need do handle the UlidCreatorException, in the case that too many ULIDs are requested within the same millisecond.