ffffe2af51 | ||
---|---|---|
src | ||
.gitignore | ||
LICENSE | ||
README.md | ||
pom.xml |
README.md
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 ULID as GUID object:
UUID ulid = UlidCreator.getGuid();
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.2</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. 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 fixed timestamp strategy (for test cases)
String ulid = UlidCreator.getGuidCreator()
.withTimestampStrategy(new FixedTimestampStretegy())
.createUlid();
// with your custom timestamp strategy
String ulid = UlidCreator.getGuidCreator()
.withTimestampStrategy(new MyCustomTimestampStrategy())
.createUlid();
// with your custom random number generator
String ulid = UlidCreator.getGuidCreator()
.withRandomGenerator(new MyCustomRandom())
.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();
// with fast random generator (the same as above)
String ulid = UlidCreator.getGuidCreator()
.withFastRandomGenerator()
.createUlid();