Implementation of TSID based on Snowflake ID.

TSID (stands for Time-Sorted ID) is a special type of ID that looks like UUID but is actually sortable and incremental. This ensures the usage of indexing in the database while preserving the uniqueness of UUID (or mostly the look of it).

TSID is basically a signed 64-bit integer (long in Java). The implementation is heavily inspired by the following sources:

• Vlad Mihalcea's posts on TSID and why using it at all.
• Snowflake ID from X (formerly Twitter).

The current implementation of TSID consists of three parts:

• The first 42 bits represent the timestamp of the creation of the TSID. Specifically, it comprises a 1-bit signed value and a 41-bit timestamp. The timestamp is calculated by getting the current UTC in milliseconds since Unix epoch and subtracting the custom epoch value (if defined).
• The next 10 bits represent the node ID for the current machine/node/worker. This allocation is particularly useful in systems where multiple instances of applications are deployed, and each utilizes the TsidFactory for generating the Tsid.
• Finally, the last 12 bits represent an incremental sequence number for multiple TSIDs generated within the same millisecond (timestamp), if such occurrences arise. The starting sequence for each timestamp is securely randomized to minimize the predictability of the TSID.

The generation of Tsid per node is guaranteed to be thread-safe.

To generate an instance of Tsid, we use TsidFactory:

import com.vincentdao.tsid.Tsid;
import com.vincentdao.tsid.TsidFactory;

public static void main(String[] args) {
    // Quickly generate a new one (NOT THREAD-SAFE!)
    Tsid quickGeneratedTsid = TsidFactory.instance().quickGenerate();

    // Generate new Tsid (thread-safe)
    Tsid tsid = TsidFactory.instance().generate();

    // Reset the factory
    TsidFactory.reset();

    // Configure the factory using its Builder
    TsidFactory.builder()
            .withNode()
            .customizedAs(69L)
            .withEpoch()
            .customizedAs(1000000L)
            .build();

    // Now, the new Tsid will have its node set to 69 and timestamp calculated from epoch 1000000
    Tsid configuredTsid = TsidFactory.instance().generate();
}

If we already have a Tsid value (long or String), we can use Tsid static methods:

import com.vincentdao.tsid.Tsid;

public static void main(String[] args) {
    // The value must be 64-bit integer!
    Tsid fromLongTsid = Tsid.fromLong(1541815603606036480L);

    // String must be in Crockford's encoding
    Tsid fromStringTsid = Tsid.fromString("2NJT27V22YG00");
}

There are currently two configurations for the factory:

• Node ID: Indicates the current machine/node/worker. As TSIDs can be generated by multiple instances in the system, it is crucial to clearly define each node with its ID to ensure safe generation (i.e., no collision). The default value is the current thread's ID where the call to obtain the factory instance occurs.
• Custom epoch: Specifies the epoch for calculating the timestamp. The default is the Unix epoch.

These values can be defined at 3 places: system's environment, system's properties (for current running Java app), and on code-level using TsidFactory.Builder.

Configuring for the properties is used through -D argument:

java -D

Here are the name of these variables:

• Node:
  • TSID_NODE for env
  • tsid.node for property
• Epoch:
  • TSID_EPOCH for env
  • tsid.epoch for property

The String representation of TSID is based on Crockford's Base32:

import com.vincentdao.tsid.Tsid;
import com.vincentdao.tsid.TsidFactory;

public static void main(String[] args) {
  // Example for Tsid with value "1541815603606036480"
  Tsid id = TsidFactory.instance().generate();

  System.out.println(id.asLong());                  // 1541815603606036480
  System.out.println(id.asString());                // "2NJT27V22YG00"
  System.out.println(id);                           // "2NJT27V22YG00"
  System.out.println(id.asLowercaseString());       // "2njt27v22yg00"
}