178 lines
5.5 KiB
Markdown
178 lines
5.5 KiB
Markdown
|
|
# ULID Creator
|
|
|
|
A Java library for generating ULIDs.
|
|
|
|
How to Use
|
|
------------------------------------------------------
|
|
|
|
Create a ULID as GUID:
|
|
|
|
```java
|
|
UUID ulid = UlidCreator.getUlid();
|
|
```
|
|
|
|
Create a ULID as string:
|
|
|
|
```java
|
|
String ulid = UlidCreator.getUlidString();
|
|
```
|
|
|
|
|
|
### Maven dependency
|
|
|
|
Add these lines to your `pom.xml`.
|
|
|
|
```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](https://search.maven.org/artifact/com.github.f4b6a3/ulid-creator).
|
|
|
|
Implementation
|
|
------------------------------------------------------
|
|
|
|
### ULID as GUID
|
|
|
|
The GUIDs in this library are based on the [ULID specification](https://github.com/ulid/spec). 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`.
|
|
|
|
```java
|
|
// GUID based on ULID spec
|
|
UUID ulid = UlidCreator.getUlid();
|
|
```
|
|
|
|
Examples of GUIDs based on ULID spec:
|
|
|
|
```text
|
|
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](https://github.com/ulid/spec) for more information.
|
|
|
|
See the section on GUIDs to know how the 128 bits are generated in this library.
|
|
|
|
```java
|
|
// ULIDs
|
|
String ulid = UlidCreator.getUlidString();
|
|
```
|
|
|
|
Examples of ULIDs:
|
|
|
|
```text
|
|
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:
|
|
|
|
```java
|
|
|
|
// 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](https://github.com/fabiolimace/uuid-creator-benchmark)
|
|
|
|
Links for generators
|
|
-------------------------------------------
|
|
* [UUID Creator](https://github.com/f4b6a3/uuid-creator)
|
|
* [ULID Creator](https://github.com/f4b6a3/ulid-creator)
|
|
* [TSID Creator](https://github.com/f4b6a3/tsid-creator)
|