Class Ksuid

java.lang.Object
icu.congee.id.generator.ksuid.Ksuid
All Implemented Interfaces:
Serializable, Comparable<Ksuid>
public final class Ksuid extends Object implements Serializable, Comparable<Ksuid>
A class that represents KSUIDs.

KSUID is a 160-bit value that has two parts:

  • Time: a sequence of 32 bits that represent the creation minute.
  • Payload: a sequence of 128 random bits generated by a secure random generator.

Instances of this class are immutable.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final long
    EPOCH_OFFSET
    Number of seconds of 2014-05-13T16:53:20Z (14e8).
    static final int
    KSUID_BYTES
    Number of bytes of a KSUID.
    static final int
    KSUID_CHARS
    Number of characters of a KSUID.
    static final int
    PAYLOAD_BYTES
    Number of bytes of the payload of a KSUID.
    static final int
    TIME_BYTES
    Number of bytes of the time of a KSUID.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Ksuid(long seconds, byte[] payload)
    Creates a new KSUID.
    Ksuid(Ksuid ksuid)
    Creates a new KSUID.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    compareTo(Ksuid that)
    Compares two KSUIDs as unsigned 160-bit integers.
    boolean
    equals(Object other)
    Checks if some other KSUID is equal to this one.
    static Ksuid
    fast()
    Returns a fast new KSUID.
    static Ksuid
    from(byte[] bytes)
    Convert a byte array into a KSUID.
    static Ksuid
    from(String string)
    Convert a canonical string into a KSUID.
    Instant
    getInstant()
    Return the instant of creation.
    static Instant
    getInstant(String string)
    Return the instant of creation.
    byte[]
    getPayload()
    Return the payload.
    static byte[]
    getPayload(String string)
    Return the payload.
    long
    getTime()
    Return the creation time.
    static long
    getTime(String string)
    Return the creation time.
    int
    hashCode()
    Returns a hash code value for the KSUID.
    Ksuid
    increment()
    Returns a new KSUID by incrementing the payload of the current KSUID.
    static boolean
    isValid(String string)
    Check if the input string is valid.
    byte[]
    toBytes()
    Convert the KSUID into a byte array.
    String
    toString()
    Convert the KSUID into a canonical string.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • KSUID_CHARS

      public static final int KSUID_CHARS
      Number of characters of a KSUID.
      See Also:

    • KSUID_BYTES

      public static final int KSUID_BYTES
      Number of bytes of a KSUID.
      See Also:

    • TIME_BYTES

      public static final int TIME_BYTES
      Number of bytes of the time of a KSUID.
      See Also:

    • PAYLOAD_BYTES

      public static final int PAYLOAD_BYTES
      Number of bytes of the payload of a KSUID.
      See Also:

    • EPOCH_OFFSET

      public static final long EPOCH_OFFSET
      Number of seconds of 2014-05-13T16:53:20Z (14e8).
      See Also:

  • Constructor Details

    • Ksuid

      public Ksuid(Ksuid ksuid)
      Creates a new KSUID.

      Useful to make copies of KSUIDs.

      Parameters:
      ksuid - a KSUID

    • Ksuid

      public Ksuid(long seconds, byte[] payload)
      Creates a new KSUID.

      Seconds parameter is the number of seconds since 1970-01-01 (Unix epoch). It is internally converted to KSUID time.

      Payload parameter must be an array of 16 bytes.

      Parameters:
      seconds - the number of seconds since 1970-01-01
      payload - an array of 16 bytes
      Throws:
      IllegalArgumentException - if payload is null or its length is not 16

  • Method Details

    • fast

      public static Ksuid fast()
      Returns a fast new KSUID.

      This static method is a quick alternative to KsuidCreator.getKsuid().

      It employs SplittableRandom which works very well, although not cryptographically strong. It can be useful, for example, for logging.

      Security-sensitive applications that require a cryptographically secure pseudo-random generator should use KsuidCreator.getKsuid().

      Returns:
      a KSUID
      Since:
      4.1.0

    • from

      public static Ksuid from(byte[] bytes)
      Convert a byte array into a KSUID.
      Parameters:
      bytes - an array of 20 bytes
      Returns:
      a KSUID
      Throws:
      IllegalArgumentException - if bytes are null or its length is not 20

    • from

      public static Ksuid from(String string)
      Convert a canonical string into a KSUID.

      The input string must be 27 characters long and must contain only characters from base-62 alphabet.

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

    • toBytes

      public byte[] toBytes()
      Convert the KSUID into a byte array.
      Returns:
      a byte array.

    • toString

      public String toString()
      Convert the KSUID into a canonical string.

      The output string is 27 characters long and contains only characters from base-62 alphabet.

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

    • getInstant

      public Instant getInstant()
      Return the instant of creation.

      The instant of creation is extracted from the creation time.

      Returns:
      the Instant of creation

    • getInstant

      public static Instant getInstant(String string)
      Return the instant of creation.

      The instant of creation is extracted from the creation time.

      Parameters:
      string - a canonical string
      Returns:
      the Instant of creation
      Throws:
      IllegalArgumentException - if the input string is invalid

    • getTime

      public long getTime()
      Return the creation time.

      The number returned is equivalent to the number of seconds since 1970-01-01 (Unix epoch).

      Returns:
      a number of seconds

    • getTime

      public static long getTime(String string)
      Return the creation time.

      The number returned is equivalent to the number of seconds since 1970-01-01 (Unix epoch).

      Parameters:
      string - a canonical string
      Returns:
      a number of seconds
      Throws:
      IllegalArgumentException - if the input string is invalid

    • getPayload

      public byte[] getPayload()
      Return the payload.

      The payload is an array of 16 bytes (128 bits).

      Returns:
      a byte array

    • getPayload

      public static byte[] getPayload(String string)
      Return the payload.

      The payload is an array of 16 bytes (128 bits).

      Parameters:
      string - a canonical string
      Returns:
      a byte array

    • isValid

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

      The input string must be 27 characters long and must contain only characters from base-62 alphabet.

      Parameters:
      string - a canonical string
      Returns:
      true if valid
      See Also:

    • hashCode

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

    • equals

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

    • compareTo

      public int compareTo(Ksuid that)
      Compares two KSUIDs as unsigned 160-bit integers.

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

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

    • increment

      public Ksuid increment()
      Returns a new KSUID by incrementing the payload of the current KSUID. When an overflow occurs in the payload 128 bits, the time is simply incremented to maintain monotonicity.
      Returns:
      a KSUID