-
Notifications
You must be signed in to change notification settings - Fork 3
Home
A Java library for generating KSUIDs (K-Sortable Unique Identifier).
- Sorted by generation time;
- Can be stored as a string of 27 chars;
- Can be stored as an array of 20 bytes;
- String format is encoded to base-62 (0-9A-Za-z);
- String format is URL safe and has no hyphens.
Read the reference implementation.
Create a KSUID:
Ksuid ksuid = KsuidCreator.getKsuid();Create a KSUID String:
String string = KsuidCreator.getKsuid().toString();Add these lines to your pom.xml.
<!-- https://search.maven.org/artifact/com.github.f4b6a3/ksuid-creator -->
<dependency>
<groupId>com.github.f4b6a3</groupId>
<artifactId>ksuid-creator</artifactId>
<version>2.2.0</version>
</dependency>See more options in maven.org.
Module and bundle names are the same as the root package name.
- JPMS module name:
com.github.f4b6a3.ksuid - OSGi symbolic name:
com.github.f4b6a3.ksuid
The KSUID is a 160 bit long identifier (20 bytes). Its consists of a 32-bit timestamp and a 128-bit randomly generated payload.
// Create a KSUID
Ksuid ksuid = KsuidCreator.getKsuid();// Create a KSUID with a given instant
Ksuid ksuid = KsuidCreator.getKsuid(Instant.now());Sequence of KSUIDs:
1tVNDMPsoc59fugBaCLAn9zfbpz
1tVNDMLGoOGqXhR6wSmGCGTuvpw
1tVNDJ9mTTvJO0TqYGC3fTbL73U
1tVNDM39pmWUFhPFSoeNKNpZrsW
1tVNDIfXtt01uVAOvHPdiLunz6N
1tVNDJPRPpPu8qMFk9cmu3b4TLw
1tVNDNP3YfqCOH7wKXStcEc61UP
1tVNDIiEnf9sQAhxcCKTJejJLab
1tVNDIHTknh2fUN74Fb5Hrgo3iy
1tVNDIrcOykL0pWQELgMQ8dZmlV
1tVNDLVdzGm1dL1KeVsekwBySXI
1tVNDHpAvyP7o4xCpKBetE0mn3p
1tVNDHKi79Eaf8uymdQZIZrCG7j
1tVNDMlWdoyH1xnxFYI9UubeIqB
1tVNDHE2n8HOAnMB5bO8X4eEFTD
1tVNDNHR0sZx5d6NE5SkyVbmIzB
|----|--------------------|
time payload
Create a KSUID with subsecond precision:
// Create a KSUID with millisecond precision
Ksuid ksuid = KsuidCreator.getKsuidMs();// Create a KSUID with microsecond precision
Ksuid ksuid = KsuidCreator.getKsuidUs();// Create a KSUID with nanosecond precision
Ksuid ksuid = KsuidCreator.getKsuidNs();Create a KSUID from a canonical string (27 chars, base-62):
Ksuid ksuid = Ksuid.from("0123456789ABCDEFGHIJKLMNOPQ");Get the creation instant of a KSUID:
Instant instant = ksuid.getInstant(); // 2014-06-05T09:06:29Z// static method
Instant instant = Ksuid.getInstant("0123456789ABCDEFGHIJKLMNOPQ"); // 2014-06-05T09:06:29ZA key generator that makes substitution easy if necessary:
package com.example;
import com.github.f4b6a3.ksuid.KsuidCreator;
public class KeyGenerator {
public static String next() {
return KsuidCreator.getKsuid().toString();
}
}String key = KeyGenerator.next();A KsuidFactory with java.util.Random:
// use a `java.util.Random` instance for fast generation
KsuidFactory factory = KsuidFactory.newInstance(new Random());
// use the factory
Ksuid ksuid = factory.create();A KsuidFactory with ThreadLocalRandom inside of a Supplier<byte[]>:
// use a random supplier that returns an array of 16 bytes
KsuidFactory factory = KsuidFactory.newInstance(() -> {
final byte[] bytes = new byte[Ksuid.PAYLOAD_BYTES];
ThreadLocalRandom.current().nextBytes(bytes);
return bytes;
});
// use the factory
Ksuid ksuid = factory.create();This section shows benchmarks comparing KsuidCreator to java.util.UUID.
--------------------------------------------------------------------------------
THROUGHPUT (operations/msec) Mode Cnt Score Error Units
--------------------------------------------------------------------------------
UUID_randomUUID thrpt 5 2035,533 ± 39,739 ops/ms
UUID_randomUUID_toString thrpt 5 1177,259 ± 32,038 ops/ms
KsuidCreator_getKsuid thrpt 5 1927,256 ± 33,542 ops/ms
KsuidCreator_getKsuid_toString thrpt 5 1012,974 ± 18,003 ops/ms
--------------------------------------------------------------------------------
Total time: 00:05:21
--------------------------------------------------------------------------------
System: JVM 8, Ubuntu 20.04, CPU i5-3330, 8G RAM.
To execute the benchmark, run ./benchmark/run.sh.
Check out the other ID generators.