Package me.ahoo.cosid.snowflake

Interface SnowflakeId

All Superinterfaces:
IdGenerator, Statistical, StringIdGenerator
All Known Subinterfaces:
SnowflakeFriendlyId
All Known Implementing Classes:
AbstractSnowflakeId, ClockSyncSnowflakeId, DefaultSnowflakeFriendlyId, MillisecondSnowflakeId, SecondSnowflakeId, StringSnowflakeId
public interface SnowflakeId extends IdGenerator
Snowflake algorithm ID generator.

This interface implements the Twitter Snowflake ID generation algorithm, which creates sortable, unique IDs across a distributed system. The algorithm combines several components to form a 63-bit (positive long) ID: 

 | timestamp | machine ID | sequence |
 |-----------|------------|----------|
 | 41 bits   | 10 bits    | 12 bits  |

The components are:

  • Timestamp: Milliseconds since a custom epoch
  • Machine ID: Unique identifier for the machine/instance
  • Sequence: Counter for IDs generated in the same millisecond

This design ensures IDs are:

  • Universally unique within the system
  • Roughly time-ordered (sortable)
  • Efficient to generate (no coordination required)

SnowflakeId

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    TOTAL_BIT
    The total number of bits used for Snowflake IDs (63 bits).

  • Method Summary

    Modifier and Type
    Method
    Description
    static long
    defaultSequenceResetThreshold(int sequenceBit)
    Calculate the default sequence reset threshold.
    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.
    default boolean
    isSafeJavascript()
    Check if this Snowflake ID generator is safe for use in JavaScript.
    default IdGeneratorStat
    stat()
    Get statistical information about this Snowflake ID generator.

    Methods inherited from interface me.ahoo.cosid.IdGenerator

    generate, generateAsString, idConverter

  • Field Details

    • TOTAL_BIT

      static final int TOTAL_BIT
      The total number of bits used for Snowflake IDs (63 bits).

      Snowflake IDs use 63 bits rather than 64 because the most significant bit is reserved to ensure all IDs are positive long values.

      See Also:

  • Method Details

    • getEpoch

      long getEpoch()
      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.

      Returns:
      The epoch timestamp in milliseconds

    • getTimestampBit

      int getTimestampBit()
      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.

      Returns:
      The number of timestamp bits

    • getMachineBit

      int getMachineBit()
      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.

      Returns:
      The number of machine ID bits

    • getSequenceBit

      int getSequenceBit()
      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.

      Returns:
      The number of sequence bits

    • isSafeJavascript

      default boolean isSafeJavascript()
      Check if this Snowflake ID generator is safe for use in JavaScript.

      JavaScript can only safely represent integers up to 2^53 - 1. This method checks if the total bit size of the ID (timestamp + machine + sequence) is less than or equal to the maximum safe JavaScript number of bits, as defined in SafeJavaScriptSnowflakeId.JAVA_SCRIPT_MAX_SAFE_NUMBER_BIT.

      Returns:
      true if the ID is JavaScript-safe, false otherwise

    • getMaxTimestamp

      long getMaxTimestamp()
      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.

      Returns:
      The maximum timestamp value

    • getMaxMachineId

      int getMaxMachineId()
      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.

      Returns:
      The maximum machine ID value

    • getMaxSequence

      long getMaxSequence()
      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.

      Returns:
      The maximum sequence value

    • getLastTimestamp

      long getLastTimestamp()
      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.

      Returns:
      The timestamp of the last generated ID

    • getMachineId

      int getMachineId()
      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.

      Returns:
      The machine ID

    • defaultSequenceResetThreshold

      static long defaultSequenceResetThreshold(int sequenceBit)
      Calculate the default sequence reset threshold.

      This utility method calculates a threshold value that can be used to determine when to reset the sequence counter, typically to half of the maximum sequence value.

      Parameters:
      sequenceBit - The number of bits used for the sequence portion
      Returns:
      The default sequence reset threshold

    • stat

      default IdGeneratorStat stat()
      Get statistical information about this Snowflake ID generator.

      This method provides detailed information about the generator's configuration and current state, including all the key parameters that define its behavior.

      Specified by:
      stat in interface IdGenerator
      Specified by:
      stat in interface Statistical
      Returns:
      Statistical information about this Snowflake ID generator