Package io.hypersistence.tsid

Class TSID.Factory

java.lang.Object
io.hypersistence.tsid.TSID.Factory
Enclosing class:
TSID
public static final class TSID.Factory extends Object
A factory that actually generates Time-Sorted Unique Identifiers (TSID).

You can use this class to generate a Tsid or to make some customizations, for example changing the default SecureRandom random generator to a faster pseudo-random generator.

If a system property "tsidcreator.node" or environment variable "TSID_NODE" is defined, its value is utilized as node identifier. One of them should be defined to embed a machine ID in the generated TSID in order to avoid TSID collisions. Using that property or variable is highly recommended. If no property or variable is defined, a random node ID is generated at initialization.

If a system property "tsidcreator.node.count" or environment variable "TSID_NODE_COUNT" is defined, its value is utilized by the constructors of this class to adjust the amount of bits needed to embed the node ID. For example, if the number 50 is given, the node bit amount is adjusted to 6, which is the minimum number of bits to accommodate 50 nodes. If no property or variable is defined, the number of bits reserved for node ID is set to 10, which can accommodate 1024 nodes.

This class should be used as a singleton. Make sure that you create and reuse a single instance of TSID.Factory per node in your distributed system.

  • Field Details

    • INSTANCE

      public static final TSID.Factory INSTANCE

    • INSTANCE_256

      public static final TSID.Factory INSTANCE_256

    • INSTANCE_1024

      public static final TSID.Factory INSTANCE_1024

    • INSTANCE_4096

      public static final TSID.Factory INSTANCE_4096

    • THREAD_LOCAL_RANDOM_FUNCTION

      public static final IntSupplier THREAD_LOCAL_RANDOM_FUNCTION

  • Constructor Details

    • Factory

      public Factory()
      It builds a new factory.

      The node identifier provided by the "tsidcreator.node" system property or the "TSID_NODE" environment variable is embedded in the generated TSIDs in order to avoid collisions. It is highly recommended defining that property or variable. Otherwise the node identifier will be randomly chosen.

      If a system property "tsidcreator.node.count" or environment variable "TSID_NODE_COUNT" is defined, its value is used to adjust the node bits amount.

    • Factory

      public Factory(int node)
      It builds a new factory.

      The node identifier provided by parameter is embedded in the generated TSIDs in order to avoid collisions.

      If a system property "tsidcreator.node.count" or environment variable "TSID_NODE_COUNT" is defined, its value is used to adjust the node bits amount.

      Parameters:
      node - the node identifier

  • Method Details

    • newInstance256

      public static TSID.Factory newInstance256()
      Returns a new factory for up to 256 nodes and 16384 ID/ms.
      Returns:
      TSID.Factory

    • newInstance256

      public static TSID.Factory newInstance256(int node)
      Returns a new factory for up to 256 nodes and 16384 ID/ms.
      Parameters:
      node - the node identifier
      Returns:
      TSID.Factory

    • newInstance1024

      public static TSID.Factory newInstance1024()
      Returns a new factory for up to 1024 nodes and 4096 ID/ms. It is equivalent to new TsidFactory().
      Returns:
      TSID.Factory

    • newInstance1024

      public static TSID.Factory newInstance1024(int node)
      Returns a new factory for up to 1024 nodes and 4096 ID/ms. It is equivalent to new TsidFactory(int).
      Parameters:
      node - the node identifier
      Returns:
      TSID.Factory

    • newInstance4096

      public static TSID.Factory newInstance4096()
      Returns a new factory for up to 4096 nodes and 1024 ID/ms.
      Returns:
      TSID.Factory

    • newInstance4096

      public static TSID.Factory newInstance4096(int node)
      Returns a new factory for up to 4096 nodes and 1024 ID/ms.
      Parameters:
      node - the node identifier
      Returns:
      TSID.Factory

    • generate

      public TSID generate()
      Returns a TSID.
      Returns:
      a TSID.

    • builder

      public static TSID.Factory.Builder builder()
      Returns a builder object.

      It is used to build a custom TSID.Factory.

    • getTsid

      public static TSID getTsid()
      Returns a new TSID.

      The node ID is is set by defining the system property "tsid.node" or the environment variable "TSID_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 "tsid.node.count" or the environment variable "TSID_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 "tsid.node" or the environment variable "TSID_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 "tsid.node" or the environment variable "TSID_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 "tsid.node" or the environment variable "TSID_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