Package io.hypersistence.tsid

Class TSID

java.lang.Object
io.hypersistence.tsid.TSID
All Implemented Interfaces:
Serializable, Comparable<TSID>
public final class TSID extends Object implements Serializable, Comparable<TSID>
A value object that represents a Time-Sorted Unique Identifier (TSID).

TSID is a 64-bit value that has 2 components:

  • Time component (42 bits): a number of milliseconds since 1970-01-01 (Unix epoch).
  • Random component (22 bits): a sequence of random bits generated by a secure random generator.

The Random component has 2 sub-parts:

  • Node (0 to 20 bits): a number used to identify the machine or node.
  • Counter (2 to 22 bits): a randomly generated number that is incremented whenever the time component is repeated.

The random component layout depend on the node bits. If the node bits are 10, the counter bits are limited to 12. In this example, the maximum node value is 2^10-1 = 1023 and the maximum counter value is 2^12-1 = 4093. So the maximum TSIDs that can be generated per millisecond per node is 4096.

Instances of this class are immutable.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    TSID.Factory
    A factory that actually generates Time-Sorted Unique Identifiers (TSID).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    TSID_BYTES
    Number of bytes of a TSID.
    static final int
    TSID_CHARS
    Number of characters of a TSID.
    static final long
    TSID_EPOCH
    Number of milliseconds of 2020-01-01T00:00:00.000Z.

  • Constructor Summary

    Constructors
    Constructor
    Description
    TSID(long number)
    Creates a new TSID.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(TSID that)
    Compares two TSIDs as unsigned 64-bit integers.
    static TSID
    decode(String string, int base)
    Converts a base-n encoded string to a TSID.
    String
    encode(int base)
    Converts the TSID to a base-n encoded string.
    boolean
    equals(Object other)
    Checks if some other TSID is equal to this one.
    static TSID
    fast()
    Returns a fast new TSID.
    String
    format(String format)
    Converts the TSID to a string using a custom format.
    static TSID
    from(byte[] bytes)
    Converts a byte array into a TSID.
    static TSID
    from(long number)
    Converts a number into a TSID.
    static TSID
    from(String string)
    Converts a canonical string into a TSID.
    Instant
    getInstant()
    Returns the instant of creation.
    Instant
    getInstant(Instant customEpoch)
    Returns the instant of creation.
    long
    getUnixMilliseconds()
    Returns the time of creation in milliseconds since 1970-01-01.
    long
    getUnixMilliseconds(long customEpoch)
    Returns the time of creation in milliseconds since 1970-01-01.
    int
    hashCode()
    Returns a hash code value for the TSID.
    static boolean
    isValid(String string)
    Checks if the input string is valid.
    byte[]
    toBytes()
    Converts the TSID into a byte array.
    long
    toLong()
    Converts the TSID into a number.
    String
    toLowerCase()
    Converts the TSID into a canonical string in lower case.
    String
    toString()
    Converts the TSID into a canonical string in upper case.
    static TSID
    unformat(String formatted, String format)
    Converts a string using a custom format to a TSID.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • TSID_BYTES

      public static final int TSID_BYTES
      Number of bytes of a TSID.
      See Also:

    • TSID_CHARS

      public static final int TSID_CHARS
      Number of characters of a TSID.
      See Also:

    • TSID_EPOCH

      public static final long TSID_EPOCH
      Number of milliseconds of 2020-01-01T00:00:00.000Z.

  • Constructor Details

    • TSID

      public TSID(long number)
      Creates a new TSID.

      This constructor wraps the input value in an immutable object.

      Parameters:
      number - a number

  • Method Details

    • from

      public static TSID from(long number)
      Converts a number into a TSID.

      This method wraps the input value in an immutable object.

      Parameters:
      number - a number
      Returns:
      a TSID

    • from

      public static TSID from(byte[] bytes)
      Converts a byte array into a TSID.
      Parameters:
      bytes - a byte array
      Returns:
      a TSID
      Throws:
      IllegalArgumentException - if bytes are null or its length is not 8

    • from

      public static TSID from(String string)
      Converts a canonical string into a TSID.

      The input string must be 13 characters long and must contain only characters from Crockford's base 32 alphabet.

      The first character of the input string must be between 0 and F.

      Parameters:
      string - a canonical string
      Returns:
      a TSID
      Throws:
      IllegalArgumentException - if the input string is invalid
      See Also:

    • toLong

      public long toLong()
      Converts the TSID into a number.

      This method simply unwraps the internal value.

      Returns:
      an number.

    • toBytes

      public byte[] toBytes()
      Converts the TSID into a byte array.
      Returns:
      an byte array.

    • fast

      public static TSID fast()
      Returns a fast new TSID.

      This static method is a quick alternative to TSID.Factory.getTsid().

      It employs AtomicInteger to generate up to 2^22 (4,194,304) TSIDs per millisecond. It can be useful, for example, for logging.

      Security-sensitive applications that require a cryptographically secure pseudo-random generator should use TSID.Factory.getTsid().

      System property "tsidcreator.node" and environment variable "TSID_NODE" are ignored by this method. Therefore, there will be collisions if more than one process is generating TSIDs using this method. In that case, TSID.Factory.getTsid() should be used in conjunction with that property or variable.

      Returns:
      a TSID
      Since:
      5.1.0

    • toString

      public String toString()
      Converts the TSID into a canonical string in upper case.

      The output string is 13 characters long and contains only characters from Crockford's base 32 alphabet.

      For lower case string, use the shorthand Tsid.toLowerCase() instead of Tsid.toString().toLowerCase().

      Overrides:
      toString in class Object
      Returns:
      a TSID string
      See Also:

    • toLowerCase

      public String toLowerCase()
      Converts the TSID into a canonical string in lower case.

      The output string is 13 characters long and contains only characters from Crockford's base 32 alphabet.

      It is faster shorthand for Tsid.toString().toLowerCase().

      Returns:
      a string
      See Also:

    • getInstant

      public Instant getInstant()
      Returns the instant of creation.

      The instant of creation is extracted from the time component.

      Returns:
      Instant

    • getInstant

      public Instant getInstant(Instant customEpoch)
      Returns the instant of creation.

      The instant of creation is extracted from the time component.

      Parameters:
      customEpoch - the custom epoch instant
      Returns:
      Instant

    • getUnixMilliseconds

      public long getUnixMilliseconds()
      Returns the time of creation in milliseconds since 1970-01-01.

      The time of creation is extracted from the time component.

      Returns:
      the number of milliseconds since 1970-01-01

    • getUnixMilliseconds

      public long getUnixMilliseconds(long customEpoch)
      Returns the time of creation in milliseconds since 1970-01-01.

      The time of creation is extracted from the time component.

      Parameters:
      customEpoch - the custom epoch in milliseconds since 1970-01-01
      Returns:
      the number of milliseconds since 1970-01-01

    • isValid

      public static boolean isValid(String string)
      Checks if the input string is valid.

      The input string must be 13 characters long and must contain only characters from Crockford's base 32 alphabet.

      The first character of the input string must be between 0 and F.

      Parameters:
      string - a string
      Returns:
      true if valid

    • hashCode

      public int hashCode()
      Returns a hash code value for the TSID.
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object other)
      Checks if some other TSID is equal to this one.
      Overrides:
      equals in class Object

    • compareTo

      public int compareTo(TSID that)
      Compares two TSIDs as unsigned 64-bit integers.

      The first of two TSIDs is greater than the second if the most significant byte in which they differ is greater for the first TSID.

      Specified by:
      compareTo in interface Comparable<TSID>
      Parameters:
      that - a TSID to be compared with
      Returns:
      -1, 0 or 1 as this is less than, equal to, or greater than that

    • encode

      public String encode(int base)
      Converts the TSID to a base-n encoded string.

      Example:

      • TSID: 0AXS751X00W7C
      • Base: 62
      • Output: 0T5jFDIkmmy

      The output string is left padded with zeros.

      Parameters:
      base - a radix between 2 and 62
      Returns:
      a base-n encoded string
      Since:
      5.2.0

    • decode

      public static TSID decode(String string, int base)
      Converts a base-n encoded string to a TSID.

      Example:

      • String: 05772439BB9F9074
      • Base: 16
      • Output: 0AXS476XSZ43M

      The input string is left padded with zeros.

      Parameters:
      string - a base-n encoded string
      base - a radix between 2 and 62
      Returns:
      a TSID
      Since:
      5.2.0

    • format

      public String format(String format)
      Converts the TSID to a string using a custom format.

      The custom format uses a placeholder that will be substituted by the TSID string. Only the first occurrence of a placeholder will replaced.

      Placeholders:

      • %S: canonical string in upper case
      • %s: canonical string in lower case
      • %X: hexadecimal in upper case
      • %x: hexadecimal in lower case
      • %d: base-10
      • %z: base-62

      Examples:

      • An key that starts with a letter:
        • TSID: 0AWE5HZP3SKTK
        • Format: K%S
        • Output: K0AWE5HZP3SKTK
      • A file name in hexadecimal with a prefix and an extension:
        • TSID: 0AXFXR5W7VBX0
        • Format: DOC-%X.PDF
        • Output: DOC-0575FDC1786137D6.PDF

      The opposite operation can be done by unformat(String, String).

      Parameters:
      format - a custom format
      Returns:
      a string using a custom format
      Since:
      5.2.0

    • unformat

      public static TSID unformat(String formatted, String format)
      Converts a string using a custom format to a TSID.

      This method does the opposite operation of format(String).

      Examples:

      • An key that starts with a letter:
        • String: K0AWE5HZP3SKTK
        • Format: K%S
        • Output: 0AWE5HZP3SKTK
      • A file name in hexadecimal with a prefix and an extension:
        • String: DOC-0575FDC1786137D6.PDF
        • Format: DOC-%X.PDF
        • Output: 0AXFXR5W7VBX0
      Parameters:
      formatted - a string using a custom format
      format - a custom format
      Returns:
      a TSID
      Since:
      5.2.0