3.7 KiB

Raw Blame History

ULID Creator

A Java library for generating ULIDs.

How to Use

Create a ULID as GUID:

UUID ulid = UlidCreator.getUlid();

Create a ULID 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>1.1.1</version>
</dependency>

See more options in maven.org.

Implementation

ULID 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

Ulid-based 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 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

How use the `UlidBasedGuidCreator` directly

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

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

// with `java.util.Random` number generator
Random random = new Random();
String ulid = UlidCreator.getUlidBasedGuidCreator()
    .withRandomGenerator(random)
    .createString();
    
// with fast random generator (the same as above)
String ulid = UlidCreator.getUlidBasedGuidCreator()
    .withFastRandomGenerator()
    .createString();

3.7 KiB Raw Blame History