ULID Creator

A Java library for generating ULIDs.

How to Use

Create a ULID as GUID:

UUID ulid = UlidCreator.getUlid();

Create a ULID as string:

String ulid = UlidCreator.getUlidString();

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>2.0.1</version>
</dependency>

See more options in maven.org.

Implementation

ULID as GUID

The GUIDs in this library are based on the ULID specification. 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 a thread safe java.security.SecureRandom, but it's possible to use any RNG that extends java.util.Random.

// GUID based on ULID spec
UUID ulid = UlidCreator.getUlid();

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

ULID as string

The ULID is a 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.getUlidString();

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

How use the UlidSpecCreator directly

These are some examples of using the UlidSpecCreator to create ULIDs strings:

// with your custom timestamp strategy
TimestampStrategy customStrategy = new CustomTimestampStrategy();
String ulid = UlidCreator.getUlidSpecCreator()
	.withTimestampStrategy(customStrategy)
	.createString();

// with your custom random strategy that wraps any random generator
RandomStrategy customStrategy = new CustomRandomStrategy();
String ulid = UlidCreator.getUlidSpecCreator()
	.withRandomStrategy(customStrategy)
	.createString();

// with `java.util.Random` number generator
Random random = new Random();
String ulid = UlidCreator.getUlidSpecCreator()
    .withRandomGenerator(random)
    .createString();

Benchmark

This section shows benchmarks comparing UlidCreator to java.util.UUID.

---------------------------------------------------------------------------
THROUGHPUT                         Mode  Cnt      Score     Error   Units
---------------------------------------------------------------------------
Throughput.Java_RandomBased        thrpt    5   2234,199 ±   2,844  ops/ms
Throughput.UlidCreator_Ulid        thrpt    5  19155,742 ±  22,195  ops/ms
Throughput.UlidCreator_UlidString  thrpt    5   4946,479 ±  22,800  ops/ms
---------------------------------------------------------------------------
Total time: 00:06:41
---------------------------------------------------------------------------

----------------------------------------------------------------------
AVERAGE TIME                        Mode  Cnt    Score   Error  Units
----------------------------------------------------------------------
AverageTime.Java_RandomBased        avgt    5  449,641 ± 0,994  ns/op
AverageTime.UlidCreator_Ulid        avgt    5   52,199 ± 0,185  ns/op
AverageTime.UlidCreator_UlidString  avgt    5  202,014 ± 2,111  ns/op
----------------------------------------------------------------------
Total time: 00:06:41
----------------------------------------------------------------------

System: CPU i5-3330, 8G RAM, Ubuntu 20.04.

See: uuid-creator-benchmark

Links for generators

• UUID Creator
• ULID Creator
• TSID Creator