Package icu.congee.id.generator.xid

Class Xid

java.lang.Object
icu.congee.id.generator.xid.Xid
All Implemented Interfaces:
Comparable<Xid>
public final class Xid extends Object implements Comparable<Xid>

A globally unique identifier for objects.

Consists of 12 bytes, divided as follows:

layout
0 1 2 3 4 5 6 7 8 9 10 11
time random value inc

Instances of this class are immutable.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Xid()
    Create a new object id.
    Xid(byte[] bytes)
    Constructs a new instance from the given byte array
    Xid(int timestamp, int counter)
    Creates an Xid using the given time, machine identifier, process identifier, and counter.
    Xid(String hexString)
    Constructs a new instance from a 24-byte hexadecimal string representation.
    Xid(ByteBuffer buffer)
    Constructs a new instance from the given ByteBuffer
    Xid(Date date)
    Constructs a new instance using the given date.
    Xid(Date date, int counter)
    Constructs a new instances using the given date and counter.

  • Method Summary

    Modifier and Type
    Method
    Description
    static byte[]
    bytes()
     
    int
    compareTo(Xid other)
     
    boolean
    equals(Object o)
     
    static Xid
    get()
    Gets a new object id.
    Date
    getDate()
    Gets the timestamp as a Date instance.
    static Xid
    getSmallestWithDate(Date date)
    Gets a new object id with the given date value and all other bits zeroed.
    int
    getTimestamp()
    Gets the timestamp (number of seconds since the Unix epoch).
    int
    hashCode()
     
    static void
    isTrue(String name, boolean condition)
     
    static boolean
    isValid(String hexString)
    Checks if a string could be an Xid.
    void
    putToByteBuffer(ByteBuffer buffer)
    Convert to bytes and put those bytes to the provided ByteBuffer.
    static String
    string()
     
    byte[]
    toByteArray()
    Convert to a byte array.
    String
    toHexString()
    Converts this instance into a 20-byte hexadecimal string representation.
    String
    toString()
     

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Xid

      public Xid()
      Create a new object id.

    • Xid

      public Xid(Date date)
      Constructs a new instance using the given date.
      Parameters:
      date - the date

    • Xid

      public Xid(Date date, int counter)
      Constructs a new instances using the given date and counter.
      Parameters:
      date - the date
      counter - the counter
      Throws:
      IllegalArgumentException - if the high order byte of counter is not zero

    • Xid

      public Xid(int timestamp, int counter)
      Creates an Xid using the given time, machine identifier, process identifier, and counter.
      Parameters:
      timestamp - the time in seconds
      counter - the counter
      Throws:
      IllegalArgumentException - if the high order byte of counter is not zero

    • Xid

      public Xid(String hexString)
      Constructs a new instance from a 24-byte hexadecimal string representation.
      Parameters:
      hexString - the string to convert
      Throws:
      IllegalArgumentException - if the string is not a valid hex string representation of an Xid

    • Xid

      public Xid(byte[] bytes)
      Constructs a new instance from the given byte array
      Parameters:
      bytes - the byte array
      Throws:
      IllegalArgumentException - if array is null or not of length 12

    • Xid

      public Xid(ByteBuffer buffer)
      Constructs a new instance from the given ByteBuffer
      Parameters:
      buffer - the ByteBuffer
      Throws:
      IllegalArgumentException - if the buffer is null or does not have at least 12 bytes remaining

  • Method Details

    • get

      public static Xid get()
      Gets a new object id.
      Returns:
      the new id

    • string

      public static String string()

    • bytes

      public static byte[] bytes()

    • getSmallestWithDate

      public static Xid getSmallestWithDate(Date date)
      Gets a new object id with the given date value and all other bits zeroed.

      The returned object id will compare as less than or equal to any other object id within the same second as the given date, and less than any later date.

      Parameters:
      date - the date
      Returns:
      the Xid

    • toByteArray

      public byte[] toByteArray()
      Convert to a byte array. Note that the numbers are stored in big-endian order.
      Returns:
      the byte array

    • putToByteBuffer

      public void putToByteBuffer(ByteBuffer buffer)
      Convert to bytes and put those bytes to the provided ByteBuffer. Note that the numbers are stored in big-endian order.
      Parameters:
      buffer - the ByteBuffer
      Throws:
      IllegalArgumentException - if the buffer is null or does not have at least 12 bytes remaining

    • getTimestamp

      public int getTimestamp()
      Gets the timestamp (number of seconds since the Unix epoch).
      Returns:
      the timestamp

    • getDate

      public Date getDate()
      Gets the timestamp as a Date instance.
      Returns:
      the Date

    • toHexString

      public String toHexString()
      Converts this instance into a 20-byte hexadecimal string representation.
      Returns:
      a string representation of the Xid in hexadecimal format

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • compareTo

      public int compareTo(Xid other)
      Specified by:
      compareTo in interface Comparable<Xid>

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • isValid

      public static boolean isValid(String hexString)
      Checks if a string could be an Xid.
      Parameters:
      hexString - a potential Xid as a String.
      Returns:
      whether the string could be an object id
      Throws:
      IllegalArgumentException - if hexString is null

    • isTrue

      public static void isTrue(String name, boolean condition)