Package me.ahoo.cosid.segment

Interface IdSegmentDistributor

All Superinterfaces:
Grouped
All Known Subinterfaces:
GroupedIdSegmentDistributor
All Known Implementing Classes:
DefaultGroupedIdSegmentDistributor, DefaultGroupedIdSegmentDistributor.GroupedBinding, IdSegmentDistributor.Atomic, IdSegmentDistributor.Mock, JdbcIdSegmentDistributor, MongoIdSegmentDistributor, ProxyIdSegmentDistributor, SpringRedisIdSegmentDistributor, ZookeeperIdSegmentDistributor
public interface IdSegmentDistributor extends Grouped
ID segment distributor for allocating contiguous blocks of IDs in distributed systems.

This interface provides the contract for distributing segments (contiguous blocks) of IDs across distributed instances. It is a key component of the segment-based ID generation algorithm, ensuring that each instance receives unique ranges of IDs.

The distributor is responsible for:

  • Allocating unique ID segments within a namespace
  • Managing segment size (step) configuration
  • Providing segment chain functionality for advanced use cases
  • Supporting time-to-live for segments

Common implementations include:

  • Redis-based distribution
  • ZooKeeper-based distribution
  • JDBC-based distribution

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    IdSegmentDistributor.Atomic
    Atomic implementation of IdSegmentDistributor for testing purposes.
    static class 
    IdSegmentDistributor.Mock
    Mock implementation of IdSegmentDistributor for testing purposes.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final long
    DEFAULT_OFFSET
    The default offset for ID segments.
    static final int
    DEFAULT_SEGMENTS
    The default number of segments to allocate at once.
    static final long
    DEFAULT_STEP
    The default step size for ID segments.

  • Method Summary

    Modifier and Type
    Method
    Description
    default boolean
    allowReset()
    Check if this distributor allows segment resetting.
    static void
    ensureStep(long step)
    Ensure that the specified step size is valid.
    String
    getName()
    Get the name for this distributor.
    String
    getNamespace()
    Get the namespace for this distributor.
    default String
    getNamespacedName()
    Get the namespaced name for this distributor.
    static String
    getNamespacedName(String namespace, String name)
    Create a namespaced name from namespace and name components.
    long
    getStep()
    Get the step size for ID segments.
    default long
    getStep(int segments)
    Get the total step size for the specified number of segments.
    default IdSegment
    nextIdSegment()
    Allocate the next ID segment with infinite time-to-live.
    default IdSegment
    nextIdSegment(int segments, long ttl)
    Allocate the next ID segment with multiple segments and specified time-to-live.
    default IdSegment
    nextIdSegment(long ttl)
    Allocate the next ID segment with the specified time-to-live.
    default IdSegmentChain
    nextIdSegmentChain(IdSegmentChain previousChain)
    Allocate the next ID segment chain with default configuration.
    default IdSegmentChain
    nextIdSegmentChain(IdSegmentChain previousChain, int segments, long ttl)
    Allocate the next ID segment chain with custom configuration.
    default long
    nextMaxId()
    Allocate the next maximum ID using the default step size.
    long
    nextMaxId(long step)
    Allocate the next maximum ID for the specified step size.

    Methods inherited from interface me.ahoo.cosid.segment.grouped.Grouped

    group

  • Field Details

    • DEFAULT_SEGMENTS

      static final int DEFAULT_SEGMENTS
      The default number of segments to allocate at once.
      See Also:

    • DEFAULT_OFFSET

      static final long DEFAULT_OFFSET
      The default offset for ID segments.
      See Also:

    • DEFAULT_STEP

      static final long DEFAULT_STEP
      The default step size for ID segments.

      This determines the size of each allocated segment, representing the number of IDs in each contiguous block.

      See Also:

  • Method Details

    • getNamespace

      @Nonnull String getNamespace()
      Get the namespace for this distributor.

      The namespace provides a logical grouping for ID segments, allowing multiple independent segment spaces within the same system.

      Returns:
      The namespace

    • getName

      @Nonnull String getName()
      Get the name for this distributor.

      The name uniquely identifies this distributor within its namespace.

      Returns:
      The name

    • getNamespacedName

      default String getNamespacedName()
      Get the namespaced name for this distributor.

      This is a convenience method that combines the namespace and name into a single string identifier.

      Returns:
      The namespaced name (namespace.name)

    • getNamespacedName

      static String getNamespacedName(String namespace, String name)
      Create a namespaced name from namespace and name components.
      Parameters:
      namespace - The namespace
      name - The name
      Returns:
      The namespaced name (namespace.name)

    • getStep

      long getStep()
      Get the step size for ID segments.

      The step size determines how many IDs are allocated in each segment. Larger steps reduce coordination overhead but may lead to ID gaps.

      Returns:
      The step size

    • getStep

      default long getStep(int segments)
      Get the total step size for the specified number of segments.

      This method calculates the total step size when allocating multiple segments at once, which is useful for prefetching scenarios.

      Parameters:
      segments - The number of segments
      Returns:
      The total step size

    • allowReset

      default boolean allowReset()
      Check if this distributor allows segment resetting.

      Some distributors support resetting to earlier segments, while others only move forward to prevent ID conflicts.

      Returns:
      true if resetting is allowed, false otherwise

    • nextMaxId

      long nextMaxId(long step)
      Allocate the next maximum ID for the specified step size.

      This method allocates a new range of IDs by returning the maximum ID in the allocated range. The range starts at the previous maximum plus one and ends at the returned value.

      Parameters:
      step - The step size for allocation
      Returns:
      The maximum ID in the allocated range

    • nextMaxId

      default long nextMaxId()
      Allocate the next maximum ID using the default step size.
      Returns:
      The maximum ID in the allocated range

    • nextIdSegment

      @Nonnull default IdSegment nextIdSegment()
      Allocate the next ID segment with infinite time-to-live.
      Returns:
      The allocated ID segment

    • nextIdSegment

      @Nonnull default IdSegment nextIdSegment(long ttl)
      Allocate the next ID segment with the specified time-to-live.
      Parameters:
      ttl - The time-to-live for the segment
      Returns:
      The allocated ID segment

    • nextIdSegment

      @Nonnull default IdSegment nextIdSegment(int segments, long ttl)
      Allocate the next ID segment with multiple segments and specified time-to-live.

      This method allocates a merged segment that represents multiple individual segments, useful for prefetching scenarios.

      Parameters:
      segments - The number of segments to allocate
      ttl - The time-to-live for the segment
      Returns:
      The allocated merged ID segment

    • nextIdSegmentChain

      @Nonnull default IdSegmentChain nextIdSegmentChain(IdSegmentChain previousChain)
      Allocate the next ID segment chain with default configuration.
      Parameters:
      previousChain - The previous segment chain
      Returns:
      The allocated ID segment chain

    • nextIdSegmentChain

      @Nonnull default IdSegmentChain nextIdSegmentChain(IdSegmentChain previousChain, int segments, long ttl)
      Allocate the next ID segment chain with custom configuration.

      This method allocates a new segment chain that extends the previous chain, providing the foundation for the segment chain ID generation algorithm.

      Parameters:
      previousChain - The previous segment chain
      segments - The number of segments to allocate
      ttl - The time-to-live for the segment
      Returns:
      The allocated ID segment chain

    • ensureStep

      static void ensureStep(long step)
      Ensure that the specified step size is valid.
      Parameters:
      step - The step size to validate