ulid-creator/README.md

# ulid-creator

A Java library for generating and handling ULIDs - _Universally Unique Lexicographically Sortable Identifiers_.

How to Use
------------------------------------------------------

Create a ULID:

```java
String ulid = UlidCreator.getUlid();
```

Create a fast ULID:

```java
String ulid = UlidCreator.getFastUlid();
```

Create a ULID as GUID object:

```java
UUID ulid = UlidCreator.getGuid();
```

Create a fast ULID as GUID object:

```java
UUID ulid = UlidCreator.getFastGuid();
```

Create a ULID as byte sequence:

```java
byte[] ulid = UlidCreator.getBytes();
```

Create a fast ULID as byte sequence:

```java
byte[] ulid = UlidCreator.getFastBytes();
```

### 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>1.0.0</version>
</dependency>
```
See more options in [maven.org](https://search.maven.org/artifact/com.github.f4b6a3/ulid-creator) and [mvnrepository.com](https://mvnrepository.com/artifact/com.github.f4b6a3/ulid-creator).

Implementation
------------------------------------------------------

### ULID

The ULID is a unique and sortable 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.getUlid();
```

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
```

### GUID

The GUIDs in this library are based on the ULID specification <sup>[9]</sup>. 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`.

```java
// GUID based on ULID spec
UUID guid = UlidCreator.getGuid();
```

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
```

#### How use the `GuidCreator` directly

These are some examples of using the `GuidCreator` to create ULIDs:

```java

// with the default random generator (java.security.SecureRandom)
String ulid = UlidCreator.getGuidCreator().createUlid();
    
// with java random generator (java.util.Random)
String ulid = UlidCreator.getGuidCreator()
    .withRandomGenerator(new Random())
    .createUlid();

// with fast random generator (Xorshift128Plus)
String ulid = UlidCreator.getGuidCreator()
    .withFastRandomGenerator()
    .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();
```

If you use the `GuidCreator` directly, you need do handle the `UlidCreatorException`, in the case that too many ULIDs are requested within the same millisecond.