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:
  
  Constant Field Values
- TSID_CHARS
  
  public static final int TSID_CHARS
  
  Number of characters of a TSID.
  See Also:
  
  Constant Field Values
- 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:
  
  Crockford's Base 32
- 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:
  
  Crockford's Base 32
- 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:
  
  Crockford's Base 32
- 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

Class TSID

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Details

TSID_BYTES

TSID_CHARS

TSID_EPOCH

Constructor Details

TSID

Method Details

from

from

from

toLong

toBytes

fast

toString

toLowerCase

getInstant

getInstant

getUnixMilliseconds

getUnixMilliseconds

isValid

hashCode

equals

compareTo

encode

decode

format

unformat