5.5 KiB
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.0</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.