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

    • LOCK

      private static final ReentrantLock LOCK

    • 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

    • counter

      private int counter

    • lastTime

      private long lastTime

    • node

      private final int node

    • nodeBits

      private final int nodeBits

    • counterBits

      private final int counterBits

    • nodeMask

      private final int nodeMask

    • counterMask

      private final int counterMask

    • clock

      private final Clock clock

    • customEpoch

      private final long customEpoch

    • random

      private final TSID.Factory.IRandom random

    • randomBytes

      private final int randomBytes

    • NODE_BITS_256

      static final int NODE_BITS_256
      See Also:

    • NODE_BITS_1024

      static final int NODE_BITS_1024
      See Also:

    • NODE_BITS_4096

      static final int NODE_BITS_4096
      See Also:

  • 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

    • Factory

      private Factory(TSID.Factory.Builder builder)
      It builds a generator with the given builder.
      Parameters:
      builder - a builder instance

  • 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.

    • getTime

      private long getTime()
      Returns the current time.

      If the current time is equal to the previous time, the counter is incremented by one. Otherwise, the counter is reset to a random value.

      The maximum number of increment operations depend on the counter bits. For example, if the counter bits is 12, the maximum number of increment operations is 2^12 = 4096.

      Returns:
      the current time

    • getRandomCounter

      private int getRandomCounter()
      Returns a random counter value from 0 to 0x3fffff (2^22-1 = 4,194,303).

      The counter maximum value depends on the node identifier bits. For example, if the node identifier has 10 bits, the counter has 12 bits.

      Returns:
      a number

    • getRandomValue

      private int getRandomValue()
      Returns a random value based on the counter and the current Thread id.
      Returns:
      a number

    • 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