- Notifications
You must be signed in to change notification settings - Fork9
K-Sortable Globally Unique IDs for Java
License
ksuid/ksuid
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
This is a Java port ofSegment's K-Sortable Globally Unique IDs.
KSUID is for K-Sortable Unique IDentifier. It's a way to generate globally unique IDs similar to RFC 4122 UUIDs,but contain a time component so they can be "roughly" sorted by time of creation.The remainder of the KSUID is randomly generated bytes.
In summary:
- Roughly sortable by creation time;
- Can be stored as a string of 27 chars;
- Can be stored as an array of 20 bytes;
- String format is encoded tobase-62 (0-9A-Za-z);
- String format is URL safe and has no hyphens.
For the story of how KSUIDs came about, seeA brief history of the UUID.
To use this as a command-line program on Unix-like systems, run
wget https://repo1.maven.org/maven2/com/github/ksuid/ksuid/1.1.3/ksuid-1.1.3-cli.jarsudo mv ksuid-1.1.3-cli.jar /usr/local/bin/ksuidsudo chmod +x /usr/local/bin/ksuidksuid# prints 1HCpXwx2EK9oYluWbacgeCnFcLfAdd the library to maven pom.xml (or the equivalent in your build system):
<dependency> <groupId>com.github.ksuid</groupId> <artifactId>ksuid</artifactId> <version>1.1.3</version></dependency>
Then simply generate a ksuid string like this:
Stringksuid =Ksuid.newKsuid().toString();System.out.println(ksuid);// prints 1HCpXwx2EK9oYluWbacgeCnFcLf
For more complex use cases, create aKsuidGenerator with aSecureRandom and get a newKsuid for use.
Note thatKsuidGenerator is threadsafe andKsuid is immutable (and therefore threadsafe).
// Construct a new KsuidGenerator object. Since it is threadsafe you only need one.privatestaticfinalKsuidGeneratorKSUID_GENERATOR =newKsuidGenerator(newSecureRandom());// Get a new Ksuid object.finalKsuidksuid =ksuidGenerator.newKsuid();// The toString() method is the string representation of KSUID.System.out.println("ksuid:\n" +ksuid +"\n");// The log string format shows some details on one line, suitable for logging.System.out.println("ksuid.toLogString():\n" +ksuid.toLogString() +"\n");// The inspect string format shows details.System.out.println("ksuid.toInspectString():\n" +ksuid.toInspectString());
The output from the code block above is
ksuid:1HCpXwx2EK9oYluWbacgeCnFcLfksuid.toLogString():Ksuid[timestamp = 150215977, string = 1HCpXwx2EK9oYluWbacgeCnFcLf payload = [124, 76, 43, -110, 116, -6, \ -91, 45, 0, -125, -127, 109, 28, 24, 28, -17], ksuidBytes = [8, -12, 29, 41, 124, 76, 43, -110, 116, \ -6, -91, 45, 0, -125, -127, 109, 28, 24, 28, -17]]ksuid.toInspectString():REPRESENTATION: String: 1HCpXwx2EK9oYluWbacgeCnFcLf Raw: 08F41D297C4C2B9274FAA52D0083816D1C181CEFCOMPONENTS: Time: 2019-02-14 23:32:57 -0800 PST Timestamp: 150215977 Payload: 7C4C2B9274FAA52D0083816D1C181CEFA very rough performance profile for generating KSUIDs was run on a MacBook Pro with a 3.1 GHz Intel Core i7 and 16 GB 2133 MHz LPDDR3 RAM.
publicstaticvoidmain(finalString[]args) {finalKsuidGeneratorgenerator =newKsuidGenerator(newSecureRandom());IntStream.range(0,100).forEach(i ->generator.newKsuid());// prime the randomIntStream.iterate(1000,operand ->operand *10) .limit(5) .forEach(count -> {finallongstart =System.nanoTime();IntStream.range(0,count).forEach(i ->generator.newKsuid());finallongduration =TimeUnit.MILLISECONDS.convert(System.nanoTime() -start,TimeUnit.NANOSECONDS);System.out.println(String.format("%,d in %,d ms. rate = %,d/ms",count,duration,count /duration)); });}
The output from the code block above is
1,000 in 14 ms. rate = 71/ms10,000 in 32 ms. rate = 312/ms100,000 in 95 ms. rate = 1,052/ms1,000,000 in 881 ms. rate = 1,135/ms10,000,000 in 6,665 ms. rate = 1,500/msThis library is Open Source software released under theMIT license.
About
K-Sortable Globally Unique IDs for Java