Module me.ahoo.cosid.core
Package me.ahoo.cosid.segment

Interface RangeStore

All Superinterfaces:
AutoCloseable
public interface RangeStore extends AutoCloseable
Reserves ranges atomically, the segment primitive of a store (04-segment.md ยง1).

Invariants, verified by the TCK: the ranges of a key are pairwise disjoint and strictly increasing in completion order (S1); the first range of a new key starts at initialOffset, once (S2); the returned range is authoritative (S3); gaps are allowed, duplicates never (S4); values stay in [0, Long.MAX_VALUE) (S5); a sealed key is never recreated (S6).

Failures (R1-spi-03): an operation that fails for another reason than its outcome throws a RuntimeException of the backend's choosing (a driver exception, or the store's own wrapper of one). A timeout is recognised with StoreTimeoutException.isTimeout(Throwable), whether the backend throws a StoreTimeoutException or one as the cause; the runtime counts those as store timeouts. No common base class is promised beyond RuntimeException.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
     
    Range
    reserve(String key, long size, long initialOffset)
    Atomically reserves [start, start + size); a missing key is created at initialOffset.
    default boolean
    seal(String key)
    Seals the key: every later reserve(java.lang.String, long, long) fails and the key's value is kept.

  • Method Details

    • reserve

      Range reserve(String key, long size, long initialOffset)
      Atomically reserves [start, start + size); a missing key is created at initialOffset.
      Parameters:
      key - the range key, {namespace}/{generator} or {namespace}/{generator}/{period}
      size - the size of the range, positive
      initialOffset - where the first range of a new key starts
      Returns:
      the reserved range
      Throws:
      RangeSealedException - if the key is sealed
      RangeExhaustedException - if the range would pass Long.MAX_VALUE

    • seal

      default boolean seal(String key)
      Seals the key: every later reserve(java.lang.String, long, long) fails and the key's value is kept. Optional.
      Parameters:
      key - the range key
      Returns:
      whether the store sealed the key; false if it does not support sealing

    • close

      default void close()
      Specified by:
      close in interface AutoCloseable