Module com.github.f4b6a3.tsid
Package com.github.f4b6a3.tsid

Class TsidCreator

  • public final class TsidCreator
extends Object
    A utility that generates Time-Sorted Unique Identifiers (TSID).

    It is highly recommended to use this class in conjunction with the "tsidcreator.node" system property or the "TSIDCREATOR_NODE" environment variable. This is a simple way to avoid collisions between identifiers produced by more than one machine or application instance.

    • Method Detail

      • getTsid

        public static Tsid getTsid()
        Returns a new TSID.

        The node ID is is set by defining the system property "tsidcreator.node" or the environment variable "TSIDCREATOR_NODE". One of them should be used to embed a machine ID in the generated TSID in order to avoid TSID collisions. If that property or variable is not defined, the node ID is chosen randomly.

        The amount of nodes can be set by defining the system property "tsidcreator.node.count" or the environment variable "TSIDCREATOR_NODE_COUNT". That property or variable is used to adjust the minimum amount of bits to accommodate the node ID. If that property or variable is not defined, the default amount of nodes is 1024, which takes 10 bits.

        The amount of bits needed to accommodate the node ID is calculated by this pseudo-code formula: node_bits = ceil(log(node_count)/log(2)).

        Random component settings:

        • Node bits: node_bits
        • Counter bits: 22-node_bits
        • Maximum node: 2^node_bits
        • Maximum counter: 2^(22-node_bits)

        The time component can be 1 ms or more ahead of the system time when necessary to maintain monotonicity and generation speed.

        Returns:
        a TSID
        Since:
        5.1.0

      • getTsid256

        public static Tsid getTsid256()
        Returns a new TSID.

        It supports up to 256 nodes.

        It can generate up to 16,384 TSIDs per millisecond per node.

        The node ID is is set by defining the system property "tsidcreator.node" or the environment variable "TSIDCREATOR_NODE". One of them should be used to embed a machine ID in the generated TSID in order to avoid TSID collisions. If that property or variable is not defined, the node ID is chosen randomly.

        Random component settings:

        • Node bits: 8
        • Counter bits: 14
        • Maximum node: 256 (2^8)
        • Maximum counter: 16,384 (2^14)

        The time component can be 1 ms or more ahead of the system time when necessary to maintain monotonicity and generation speed.

        Returns:
        a TSID

      • getTsid1024

        public static Tsid getTsid1024()
        Returns a new TSID.

        It supports up to 1,024 nodes.

        It can generate up to 4,096 TSIDs per millisecond per node.

        The node ID is is set by defining the system property "tsidcreator.node" or the environment variable "TSIDCREATOR_NODE". One of them should be used to embed a machine ID in the generated TSID in order to avoid TSID collisions. If that property or variable is not defined, the node ID is chosen randomly.

        Random component settings:

        • Node bits: 10
        • Counter bits: 12
        • Maximum node: 1,024 (2^10)
        • Maximum counter: 4,096 (2^12)

        The time component can be 1 ms or more ahead of the system time when necessary to maintain monotonicity and generation speed.

        Returns:
        a TSID

      • getTsid4096

        public static Tsid getTsid4096()
        Returns a new TSID.

        It supports up to 4,096 nodes.

        It can generate up to 1,024 TSIDs per millisecond per node.

        The node ID is is set by defining the system property "tsidcreator.node" or the environment variable "TSIDCREATOR_NODE". One of them should be used to embed a machine ID in the generated TSID in order to avoid TSID collisions. If that property or variable is not defined, the node ID is chosen randomly.

        Random component settings:

        • Node bits: 12
        • Counter bits: 10
        • Maximum node: 4,096 (2^12)
        • Maximum counter: 1,024 (2^10)

        The time component can be 1 ms or more ahead of the system time when necessary to maintain monotonicity and generation speed.

        Returns:
        a TSID number