andrew
/
ulid-creator
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ulid-creator/README.md

182 lines
5.9 KiB
Markdown
Raw Normal View History

Rearranging the code
2020-02-22 16:07:16 +00:00
Updated README.md
2020-02-24 07:53:01 +00:00
# ULID Creator
Rearranging the code
2020-02-22 16:07:16 +00:00
Preparing v1.1.0
2020-04-18 05:43:18 +00:00
A Java library for generating ULIDs.
Rearranging the code
2020-02-22 16:07:16 +00:00
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
* Generated in lexicographical order;
* Can be stored as a UUID/GUID;
* Can be stored as a string of 26 chars;
* String format is encoded to [Crockford's base32](https://www.crockford.com/base32.html);
* String format is URL safe, case insensitive and accepts hyphens.
Rearranging the code
2020-02-22 16:07:16 +00:00
How to Use
------------------------------------------------------
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
Create a ULID:
Rearranging the code
2020-02-22 16:07:16 +00:00
```java
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
UUID ulid = UlidCreator.getUlid(); // 01706d6c-6aad-c795-370c-98d0be881bba
Rearranging the code
2020-02-22 16:07:16 +00:00
```
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
Create a ULID string:
Rearranging the code
2020-02-22 16:07:16 +00:00
```java
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
String ulid = UlidCreator.getUlidString(); // 01E1PPRTMSQ34W7JR5YSND6B8Z
Rearranging the code
2020-02-22 16:07:16 +00:00
```
### Maven dependency
Updated README.md
2020-02-23 17:08:30 +00:00
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>
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
<version>2.1.0</version>
Updated README.md
2020-02-23 17:08:30 +00:00
</dependency>
```
Updated pom.xml
2020-04-19 23:18:24 +00:00
See more options in [maven.org](https://search.maven.org/artifact/com.github.f4b6a3/ulid-creator).
Rearranging the code
2020-02-22 16:07:16 +00:00
Implementation
------------------------------------------------------
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
### ULID
Rearranging the code
2020-02-22 16:07:16 +00:00
Updated README.md
2020-02-24 07:53:01 +00:00
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.
Rearranging the code
2020-02-22 16:07:16 +00:00
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.
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
The default random number generator is `java.security.SecureRandom`.
Rearranging the code
2020-02-22 16:07:16 +00:00
```java
// GUID based on ULID spec
Preparing v1.1.0
2020-04-18 05:43:18 +00:00
UUID ulid = UlidCreator.getUlid();
Rearranging the code
2020-02-22 16:07:16 +00:00
```
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
Sequence of GUIDs based on ULID spec:
Rearranging the code
2020-02-22 16:07:16 +00:00
```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
```
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
### ULID string
Rearranging the code
2020-02-22 16:07:16 +00:00
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
The ULID string is a sequence of 26 chars. See the [ULID specification](https://github.com/ulid/spec) for more information.
Version 2.0.0 Rename UlidBasedGuidCreator to UlidSpecCreator Add method UlidCreator.fromString() Add RandomStrategy for UlidSpecCreator Add DefaultRandomStrategy using thread local SecureRandom Add OtherRandomStrategy for any instance of Random Add tests cases Optimize UlidConverter.fromString() Optimize UlidConverter.toString() Optimize UlidValidator.isValid() Optimize UlidSpecCreator Update README.md Update tests cases
2020-07-04 15:25:37 +00:00
See the section on GUIDs to know how the 128 bits are generated in this library.
```java
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
// String based on ULID spec
Version 2.0.0 Rename UlidBasedGuidCreator to UlidSpecCreator Add method UlidCreator.fromString() Add RandomStrategy for UlidSpecCreator Add DefaultRandomStrategy using thread local SecureRandom Add OtherRandomStrategy for any instance of Random Add tests cases Optimize UlidConverter.fromString() Optimize UlidConverter.toString() Optimize UlidValidator.isValid() Optimize UlidSpecCreator Update README.md Update tests cases
2020-07-04 15:25:37 +00:00
String ulid = UlidCreator.getUlidString();
```
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
Sequence of Strings based on ULID spec:
Version 2.0.0 Rename UlidBasedGuidCreator to UlidSpecCreator Add method UlidCreator.fromString() Add RandomStrategy for UlidSpecCreator Add DefaultRandomStrategy using thread local SecureRandom Add OtherRandomStrategy for any instance of Random Add tests cases Optimize UlidConverter.fromString() Optimize UlidConverter.toString() Optimize UlidValidator.isValid() Optimize UlidSpecCreator Update README.md Update tests cases
2020-07-04 15:25:37 +00:00
```text
01E1PPRTMSQ34W7JR5YSND6B8T
01E1PPRTMSQ34W7JR5YSND6B8V
01E1PPRTMSQ34W7JR5YSND6B8W
01E1PPRTMSQ34W7JR5YSND6B8X
01E1PPRTMSQ34W7JR5YSND6B8Y
01E1PPRTMSQ34W7JR5YSND6B8Z
01E1PPRTMSQ34W7JR5YSND6B90
01E1PPRTMSQ34W7JR5YSND6B91
01E1PPRTMTYMX8G17TWSJJZMEE < millisecond changed
01E1PPRTMTYMX8G17TWSJJZMEF
01E1PPRTMTYMX8G17TWSJJZMEG
01E1PPRTMTYMX8G17TWSJJZMEH
01E1PPRTMTYMX8G17TWSJJZMEJ
01E1PPRTMTYMX8G17TWSJJZMEK
01E1PPRTMTYMX8G17TWSJJZMEM
01E1PPRTMTYMX8G17TWSJJZMEN
^ look ^ look
|---------|--------------|
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
millisecs randomness
Version 2.0.0 Rename UlidBasedGuidCreator to UlidSpecCreator Add method UlidCreator.fromString() Add RandomStrategy for UlidSpecCreator Add DefaultRandomStrategy using thread local SecureRandom Add OtherRandomStrategy for any instance of Random Add tests cases Optimize UlidConverter.fromString() Optimize UlidConverter.toString() Optimize UlidValidator.isValid() Optimize UlidSpecCreator Update README.md Update tests cases
2020-07-04 15:25:37 +00:00
```
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
### How use the `UlidSpecCreator` directly
Version 2.0.0 Rename UlidBasedGuidCreator to UlidSpecCreator Add method UlidCreator.fromString() Add RandomStrategy for UlidSpecCreator Add DefaultRandomStrategy using thread local SecureRandom Add OtherRandomStrategy for any instance of Random Add tests cases Optimize UlidConverter.fromString() Optimize UlidConverter.toString() Optimize UlidValidator.isValid() Optimize UlidSpecCreator Update README.md Update tests cases
2020-07-04 15:25:37 +00:00
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
These are some examples of using the `UlidSpecCreator` to create ULID strings:
Rearranging the code
2020-02-22 16:07:16 +00:00
```java
Small optimizations Optimized methods: - UlidUtil.fromUuidToUlid() - UlidUtil.fromUlidToUuid() Added tests cases: - UlidUtilTest.testFromUuidToBytes() - UlidUtilTest.testFromBytesToUuid() - UlidUtilTest.testToAndFromBytes() Created classes: - Benchmarks.java (need to uncomment)
2020-02-25 18:40:35 +00:00
// with your custom timestamp strategy
Preparing v1.1.0
2020-04-18 05:43:18 +00:00
TimestampStrategy customStrategy = new CustomTimestampStrategy();
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
UlidSpecCreator creator = UlidCreator.getUlidSpecCreator()
.withTimestampStrategy(customStrategy);
String ulid = creator.createString();
Update README.md
2020-07-05 03:49:48 +00:00
```
Update README.md
2020-07-05 03:50:30 +00:00
```java
Version 2.0.0 Rename UlidBasedGuidCreator to UlidSpecCreator Add method UlidCreator.fromString() Add RandomStrategy for UlidSpecCreator Add DefaultRandomStrategy using thread local SecureRandom Add OtherRandomStrategy for any instance of Random Add tests cases Optimize UlidConverter.fromString() Optimize UlidConverter.toString() Optimize UlidValidator.isValid() Optimize UlidSpecCreator Update README.md Update tests cases
2020-07-04 15:25:37 +00:00
// with your custom random strategy that wraps any random generator
RandomStrategy customStrategy = new CustomRandomStrategy();
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
UlidSpecCreator creator = UlidCreator.getUlidSpecCreator()
.withRandomStrategy(customStrategy);
String ulid = creator.createString();
Update README.md
2020-07-05 03:49:48 +00:00
```
Update README.md
2020-07-05 03:50:30 +00:00
```java
Preparing v1.1.0
2020-04-18 05:43:18 +00:00
// with `java.util.Random` number generator
Random random = new Random();
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
UlidSpecCreator creator = UlidCreator.getUlidSpecCreator()
.withRandomGenerator(random);
String ulid = creator.createString();
Rearranging the code
2020-02-22 16:07:16 +00:00
```
Version 2.0.0 Rename UlidBasedGuidCreator to UlidSpecCreator Add method UlidCreator.fromString() Add RandomStrategy for UlidSpecCreator Add DefaultRandomStrategy using thread local SecureRandom Add OtherRandomStrategy for any instance of Random Add tests cases Optimize UlidConverter.fromString() Optimize UlidConverter.toString() Optimize UlidValidator.isValid() Optimize UlidSpecCreator Update README.md Update tests cases
2020-07-04 15:25:37 +00:00
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
---------------------------------------------------------------------------
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
Total time: 00:04:01
Version 2.0.0 Rename UlidBasedGuidCreator to UlidSpecCreator Add method UlidCreator.fromString() Add RandomStrategy for UlidSpecCreator Add DefaultRandomStrategy using thread local SecureRandom Add OtherRandomStrategy for any instance of Random Add tests cases Optimize UlidConverter.fromString() Optimize UlidConverter.toString() Optimize UlidValidator.isValid() Optimize UlidSpecCreator Update README.md Update tests cases
2020-07-04 15:25:37 +00:00
---------------------------------------------------------------------------
```
```
----------------------------------------------------------------------
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
----------------------------------------------------------------------
[#3] Remove overrun exception Remove UlidCreatorException // extremely unlikely to occur overrun Add UlidCreator.toString() // from UUID to crockford base 32 Change DefaultRandomStrategy // no need for thread local SecureRandom Update test cases Update README.md Update javadoc Test coverage: 94.2%
2020-10-18 00:50:37 +00:00
Total time: 00:04:01
Version 2.0.0 Rename UlidBasedGuidCreator to UlidSpecCreator Add method UlidCreator.fromString() Add RandomStrategy for UlidSpecCreator Add DefaultRandomStrategy using thread local SecureRandom Add OtherRandomStrategy for any instance of Random Add tests cases Optimize UlidConverter.fromString() Optimize UlidConverter.toString() Optimize UlidValidator.isValid() Optimize UlidSpecCreator Update README.md Update tests cases
2020-07-04 15:25:37 +00:00
----------------------------------------------------------------------
```
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)