Package me.ahoo.cosid.snowflake

Class AbstractSnowflakeId

java.lang.Object
me.ahoo.cosid.snowflake.AbstractSnowflakeId
All Implemented Interfaces:
IdGenerator, SnowflakeId, Statistical, StringIdGenerator
Direct Known Subclasses:
MillisecondSnowflakeId, SecondSnowflakeId
public abstract class AbstractSnowflakeId extends Object implements SnowflakeId
Abstract SnowflakeId implementation.

This abstract class provides the base implementation for Snowflake ID generation, handling the common logic for timestamp management, sequence counting, and ID assembly. Subclasses implement getCurrentTime() to provide time in different units (milliseconds, seconds, etc.).

The ID is composed of: timestamp (configurable bits) + machine ID (configurable bits) + sequence (configurable bits)

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final long
    epoch
    Epoch timestamp used as the base for time calculations.
    protected long
    lastTimestamp
    Timestamp of the last generated ID.
    protected final int
    machineBit
    Number of bits allocated for the machine ID portion.
    protected final long
    machineId
    The machine ID value for this instance.
    protected final long
    machineLeft
    Number of bits to shift machine ID left (equal to sequenceBit).
    protected final int
    maxMachineId
    Maximum machine ID value representable by the machine ID bits.
    protected final long
    maxSequence
    Maximum sequence value representable by the sequence bits.
    protected final long
    maxTimestamp
    Maximum timestamp value representable by the timestamp bits.
    protected long
    sequence
    Current sequence counter value.
    protected final int
    sequenceBit
    Number of bits allocated for the sequence portion.
    protected final int
    timestampBit
    Number of bits allocated for the timestamp portion.
    protected final long
    timestampLeft
    Number of bits to shift timestamp left (equal to sequenceBit + machineBit).

    Fields inherited from interface me.ahoo.cosid.snowflake.SnowflakeId

    TOTAL_BIT

  • Constructor Summary

    Constructors
    Constructor
    Description
    AbstractSnowflakeId(long epoch, int timestampBit, int machineBit, int sequenceBit, int machineId, long sequenceResetThreshold)
    Creates a new AbstractSnowflakeId.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    generate()
    Generates the next unique ID.
    protected abstract long
    getCurrentTime()
    Gets the current time in the appropriate unit for this snowflake ID variant.
    long
    getEpoch()
    Get the epoch timestamp used as the base for time calculations.
    long
    getLastTimestamp()
    Get the timestamp of the last ID that was generated.
    int
    getMachineBit()
    Get the number of bits used for the machine ID portion.
    int
    getMachineId()
    Get the machine ID assigned to this generator.
    int
    getMaxMachineId()
    Get the maximum machine ID value that can be represented.
    long
    getMaxSequence()
    Get the maximum sequence value that can be represented.
    long
    getMaxTimestamp()
    Get the maximum timestamp value that can be represented.
    int
    getSequenceBit()
    Get the number of bits used for the sequence portion.
    int
    getTimestampBit()
    Get the number of bits used for the timestamp portion.
    protected long
    nextTime()
    Waits until the current time is greater than the last timestamp.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface me.ahoo.cosid.IdGenerator

    generateAsString, idConverter

    Methods inherited from interface me.ahoo.cosid.snowflake.SnowflakeId

    isSafeJavascript, stat

  • Field Details

    • epoch

      protected final long epoch
      Epoch timestamp used as the base for time calculations.

    • timestampBit

      protected final int timestampBit
      Number of bits allocated for the timestamp portion.

    • machineBit

      protected final int machineBit
      Number of bits allocated for the machine ID portion.

    • sequenceBit

      protected final int sequenceBit
      Number of bits allocated for the sequence portion.

    • maxTimestamp

      protected final long maxTimestamp
      Maximum timestamp value representable by the timestamp bits.

    • maxSequence

      protected final long maxSequence
      Maximum sequence value representable by the sequence bits.

    • maxMachineId

      protected final int maxMachineId
      Maximum machine ID value representable by the machine ID bits.

    • machineLeft

      protected final long machineLeft
      Number of bits to shift machine ID left (equal to sequenceBit).

    • timestampLeft

      protected final long timestampLeft
      Number of bits to shift timestamp left (equal to sequenceBit + machineBit).

    • machineId

      protected final long machineId
      The machine ID value for this instance.

      Note: When machineLeft is greater than 30, overflow can occur during calculation, so machineId should be kept as long during arithmetic operations.

    • sequence

      protected long sequence
      Current sequence counter value.

    • lastTimestamp

      protected long lastTimestamp
      Timestamp of the last generated ID.

  • Constructor Details

    • AbstractSnowflakeId

      public AbstractSnowflakeId(long epoch, int timestampBit, int machineBit, int sequenceBit, int machineId, long sequenceResetThreshold)
      Creates a new AbstractSnowflakeId.
      Parameters:
      epoch - epoch timestamp in milliseconds
      timestampBit - number of bits for timestamp
      machineBit - number of bits for machine ID
      sequenceBit - number of bits for sequence
      machineId - the machine ID value
      sequenceResetThreshold - threshold for resetting sequence on timestamp advance
      Throws:
      IllegalArgumentException - if total bits exceed 63 or machineId is invalid

  • Method Details

    • nextTime

      protected long nextTime()
      Waits until the current time is greater than the last timestamp.
      Returns:
      the next valid timestamp

    • getCurrentTime

      protected abstract long getCurrentTime()
      Gets the current time in the appropriate unit for this snowflake ID variant.
      Returns:
      current time value

    • generate

      public long generate()
      Generates the next unique ID.

      This method is synchronized to ensure thread-safe ID generation.

      Specified by:
      generate in interface IdGenerator
      Returns:
      a unique snowflake ID
      Throws:
      ClockBackwardsException - if system clock has moved backwards
      TimestampOverflowException - if timestamp exceeds maximum value

    • getEpoch

      public long getEpoch()
      Description copied from interface: SnowflakeId
      Get the epoch timestamp used as the base for time calculations.

      This is the timestamp (in milliseconds) that serves as the starting point for the timestamp portion of generated IDs. IDs generated by this instance will have timestamps relative to this epoch.

      Specified by:
      getEpoch in interface SnowflakeId
      Returns:
      The epoch timestamp in milliseconds

    • getTimestampBit

      public int getTimestampBit()
      Description copied from interface: SnowflakeId
      Get the number of bits used for the timestamp portion.

      This determines the range of time that can be represented by the timestamp portion of the ID. More bits allow for a longer time range but leave fewer bits for machine ID and sequence.

      Specified by:
      getTimestampBit in interface SnowflakeId
      Returns:
      The number of timestamp bits

    • getMachineBit

      public int getMachineBit()
      Description copied from interface: SnowflakeId
      Get the number of bits used for the machine ID portion.

      This determines how many unique machines can participate in ID generation. More bits allow for more machines but leave fewer bits for timestamp and sequence.

      Specified by:
      getMachineBit in interface SnowflakeId
      Returns:
      The number of machine ID bits

    • getSequenceBit

      public int getSequenceBit()
      Description copied from interface: SnowflakeId
      Get the number of bits used for the sequence portion.

      This determines how many IDs can be generated per time unit (e.g., per millisecond). More bits allow for higher throughput within a single time unit but leave fewer bits for timestamp and machine ID.

      Specified by:
      getSequenceBit in interface SnowflakeId
      Returns:
      The number of sequence bits

    • getMaxTimestamp

      public long getMaxTimestamp()
      Description copied from interface: SnowflakeId
      Get the maximum timestamp value that can be represented.

      This is the maximum value that can be stored in the timestamp portion of the ID, which determines how long the generator can be used before exhausting the timestamp space.

      Specified by:
      getMaxTimestamp in interface SnowflakeId
      Returns:
      The maximum timestamp value

    • getMaxMachineId

      public int getMaxMachineId()
      Description copied from interface: SnowflakeId
      Get the maximum machine ID value that can be represented.

      This is the maximum value that can be stored in the machine ID portion of the ID, which determines how many unique machines can participate in ID generation.

      Specified by:
      getMaxMachineId in interface SnowflakeId
      Returns:
      The maximum machine ID value

    • getMaxSequence

      public long getMaxSequence()
      Description copied from interface: SnowflakeId
      Get the maximum sequence value that can be represented.

      This is the maximum value that can be stored in the sequence portion of the ID, which determines how many IDs can be generated per time unit.

      Specified by:
      getMaxSequence in interface SnowflakeId
      Returns:
      The maximum sequence value

    • getLastTimestamp

      public long getLastTimestamp()
      Description copied from interface: SnowflakeId
      Get the timestamp of the last ID that was generated.

      This is used for clock synchronization and to ensure proper ordering of generated IDs. It can also help detect clock drift.

      Specified by:
      getLastTimestamp in interface SnowflakeId
      Returns:
      The timestamp of the last generated ID

    • getMachineId

      public int getMachineId()
      Description copied from interface: SnowflakeId
      Get the machine ID assigned to this generator.

      This is the unique identifier for the machine or instance that is generating IDs, which ensures global uniqueness across the distributed system.

      Specified by:
      getMachineId in interface SnowflakeId
      Returns:
      The machine ID