Module me.ahoo.cosid.core
Package me.ahoo.cosid.time

Record Class Layout

java.lang.Object
java.lang.Record
me.ahoo.cosid.time.Layout
Record Components:
epoch - the time origin; whole seconds for ChronoUnit.SECONDS
unit - the time unit, ChronoUnit.MILLIS or ChronoUnit.SECONDS
timeBits - the bits of the time part, 1 to 63
nodeBits - the bits of the node part, 0 to 31
seqBits - the bits of the sequence part, 1 to 62
seqResetThreshold - the highest sequence a new time unit may start from (the low-bit scattering of 4.x)
public record Layout(Instant epoch, ChronoUnit unit, int timeBits, int nodeBits, int seqBits, long seqResetThreshold) extends Record
The bit layout of time-based ids, time | node | seq from the high bits down: the one place of the bit arithmetic (03-core-model.md ยง2).

A layout wider than 63 bits, such as COSID_80, cannot pack a long: its ids are issued as IdParts and encoded through a PartsCodec.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Layout
    COSID_80
    The 80-bit CosId of 4.x: milliseconds since the Unix epoch, 44/20/16 bits; parts only (D4).
    static final Instant
    COSID_EPOCH
    The 4.x epoch, 2019-12-24T16:00:00Z (D16).
    static final int
    JS_SAFE_BITS
    The most bits a JavaScript number holds exactly.
    static final Layout
    JS_SAFE_MS
    Milliseconds, 41/3/9 bits: 53 bits, safe in JavaScript.
    static final Layout
    JS_SAFE_S
    Seconds, 31/3/19 bits: 53 bits, safe in JavaScript.
    static final int
    LONG_BITS
    The most bits a long id may take.
    static final Layout
    SNOWFLAKE_MS
    Milliseconds, 41/10/12 bits from COSID_EPOCH: the 4.x default (D16).
    static final Layout
    SNOWFLAKE_S
    Seconds, 31/10/22 bits from COSID_EPOCH.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Layout(Instant epoch, ChronoUnit unit, int timeBits, int nodeBits, int seqBits, long seqResetThreshold)
    Creates an instance of a Layout record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    static long
    defaultSeqResetThreshold(int seqBits)
    The 4.x default reset threshold: half the sequence range.
    Instant
    epoch()
    Returns the value of the epoch record component.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    final int
    hashCode()
    Returns a hash code value for this object.
    boolean
    isJsSafe()
    Whether every id of this layout is exactly representable in JavaScript.
    static boolean
    isJsSafe(long id)
    Whether id is exactly representable in JavaScript.
    int
    nodeBits()
    Returns the value of the nodeBits record component.
    long
    pack(long time, int node, long seq)
    Packs the parts into an id.
    int
    seqBits()
    Returns the value of the seqBits record component.
    long
    seqResetThreshold()
    Returns the value of the seqResetThreshold record component.
    int
    timeBits()
    Returns the value of the timeBits record component.
    final String
    toString()
    Returns a string representation of this record class.
    int
    totalBits()
     
    ChronoUnit
    unit()
    Returns the value of the unit record component.
    IdParts
    unpack(long id)
    Unpacks an id into its parts.
    Layout
    withNodeBits(int nodeBits)
    This layout with another node part; the time and sequence parts stay as they are.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • LONG_BITS

      public static final int LONG_BITS
      The most bits a long id may take.
      See Also:

    • JS_SAFE_BITS

      public static final int JS_SAFE_BITS
      The most bits a JavaScript number holds exactly.
      See Also:

    • COSID_EPOCH

      public static final Instant COSID_EPOCH
      The 4.x epoch, 2019-12-24T16:00:00Z (D16).

    • SNOWFLAKE_MS

      public static final Layout SNOWFLAKE_MS
      Milliseconds, 41/10/12 bits from COSID_EPOCH: the 4.x default (D16).

    • SNOWFLAKE_S

      public static final Layout SNOWFLAKE_S
      Seconds, 31/10/22 bits from COSID_EPOCH.

    • JS_SAFE_MS

      public static final Layout JS_SAFE_MS
      Milliseconds, 41/3/9 bits: 53 bits, safe in JavaScript.

    • JS_SAFE_S

      public static final Layout JS_SAFE_S
      Seconds, 31/3/19 bits: 53 bits, safe in JavaScript.

    • COSID_80

      public static final Layout COSID_80
      The 80-bit CosId of 4.x: milliseconds since the Unix epoch, 44/20/16 bits; parts only (D4).

  • Constructor Details

    • Layout

      public Layout(Instant epoch, ChronoUnit unit, int timeBits, int nodeBits, int seqBits, long seqResetThreshold)
      Creates an instance of a Layout record class.
      Parameters:
      epoch - the value for the epoch record component
      unit - the value for the unit record component
      timeBits - the value for the timeBits record component
      nodeBits - the value for the nodeBits record component
      seqBits - the value for the seqBits record component
      seqResetThreshold - the value for the seqResetThreshold record component

  • Method Details

    • defaultSeqResetThreshold

      public static long defaultSeqResetThreshold(int seqBits)
      The 4.x default reset threshold: half the sequence range.
      Parameters:
      seqBits - the bits of the sequence part
      Returns:
      2^(seqBits-1) - 1

    • totalBits

      public int totalBits()

    • isJsSafe

      public boolean isJsSafe()
      Whether every id of this layout is exactly representable in JavaScript.
      Returns:
      whether totalBits() is at most 53

    • isJsSafe

      public static boolean isJsSafe(long id)
      Whether id is exactly representable in JavaScript.
      Parameters:
      id - the id
      Returns:
      whether 0 <= id < 2^53

    • withNodeBits

      public Layout withNodeBits(int nodeBits)
      This layout with another node part; the time and sequence parts stay as they are.
      Parameters:
      nodeBits - the bits of the node part
      Returns:
      the layout
      Throws:
      IllegalArgumentException - if a layout that packed a long no longer would

    • pack

      public long pack(long time, int node, long seq)
      Packs the parts into an id.
      Parameters:
      time - the time, in units since the epoch
      node - the node
      seq - the sequence
      Returns:
      the id
      Throws:
      IllegalStateException - if the layout is wider than 63 bits

    • unpack

      public IdParts unpack(long id)
      Unpacks an id into its parts.
      Parameters:
      id - the id
      Returns:
      the parts
      Throws:
      IllegalStateException - if the layout is wider than 63 bits
      IllegalArgumentException - if the id has bits beyond totalBits()

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • epoch

      public Instant epoch()
      Returns the value of the epoch record component.
      Returns:
      the value of the epoch record component

    • unit

      public ChronoUnit unit()
      Returns the value of the unit record component.
      Returns:
      the value of the unit record component

    • timeBits

      public int timeBits()
      Returns the value of the timeBits record component.
      Returns:
      the value of the timeBits record component

    • nodeBits

      public int nodeBits()
      Returns the value of the nodeBits record component.
      Returns:
      the value of the nodeBits record component

    • seqBits

      public int seqBits()
      Returns the value of the seqBits record component.
      Returns:
      the value of the seqBits record component

    • seqResetThreshold

      public long seqResetThreshold()
      Returns the value of the seqResetThreshold record component.
      Returns:
      the value of the seqResetThreshold record component