Package org.apache.synapse.commons.throttle.core

# Interface DistributedCounterManager

public interface DistributedCounterManager
This interface used to replicate throttling counters and windows in distributed manner.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `long`
  `addAndGetCounter(String key, long value)`
  This method used to add and return the distributed counter value.
  `long`
  `asyncAddCounter(String key, long value)`
  This method is used to increment distributed counter asynchronously.
  `long`
  `asyncGetAlterAndSetExpiryOfCounter(String key, long value, long expiryTimeStamp)`
  This method is used to get and then alter and then set expiry time of the DistributedCounter.
  `long`
  `asyncGetAndAddCounter(String key, long value)`
  This method is used to get and then increment distributed counter asynchronously.
  `long`
  `asyncGetAndAlterCounter(String key, long value)`
  This method used to alter the DistributedCounter.
  `long`
  `getCounter(String key)`
  Returns the Distributed Counter for specific key.
  `long`
  `getKeyLockRetrievalTimeout()`
  `long`
  `getTimestamp(String key)`
  This method returns shared TimeStamp of distributed Key.
  `long`
  `getTtl(String key)`
  `String`
  `getType()`
  `default long[]`
  `getWindowState(String key)`
  Atomically reads the window timestamp and counter for the given key.
  `default long`
  `incrWindowCounter(String key, long delta, long expiryTime)`
  Atomically increments the window counter by `delta`, refreshes the TTL to `expiryTime`, and returns the new value.
  `boolean`
  `isEnable()`
  `void`
  `removeCounter(String key)`
  This method used to remove specified key.
  `void`
  `removeLock(String key)`
  `void`
  `removeTimestamp(String key)`
  This method removes the timestamp relevant to key.
  `void`
  `setCounter(String key, long value)`
  Sets the Distributed counter with value.
  `void`
  `setCounterWithExpiry(String key, long value, long expiryTime)`
  Sets the Distributed counter with the given value while setting expiry time too.
  `void`
  `setExpiry(String key, long expiryTimeStamp)`
  `long`
  `setLock(String key, String value)`
  `boolean`
  `setLockWithExpiry(String key, String value, long expiryTimeStamp)`
  `void`
  `setTimestamp(String key, long timeStamp)`
  This method set the Timestamp to distributed map.
  `void`
  `setTimestampWithExpiry(String key, long timeStamp, long expiryTimeStamp)`
  This method set the Timestamp to distributed map with an expiry time.
  `default void`
  `setWindow(String key, long count, long ts, long expiryTime)`
  Unconditionally sets a throttle window by overwriting both timestamp and counter, then setting the TTL.

- ## Method Details

  - ### getCounter

    long getCounter(String key)
    Returns the Distributed Counter for specific key.
    Parameters:
      `key` - key to check in distributed map.
    Returns:
      value of distributed counter.

  - ### setCounter

    void setCounter(String key, long value)
    Sets the Distributed counter with value.
    Parameters:
      `key` - key to add in distributed map.
      `value` - value of distributed counter.

  - ### setCounterWithExpiry

    void setCounterWithExpiry(String key, long value, long expiryTime)
    Sets the Distributed counter with the given value while setting expiry time too.
    Parameters:
      `key` - counter key name
      `value` - counter value
      `expiryTime` - expiry time in milliseconds

  - ### addAndGetCounter

    long addAndGetCounter(String key, long value)
    This method used to add and return the distributed counter value.
    Parameters:
      `key` - key to add in distributed map.
      `value` - value to add to distributed counter.
    Returns:
      added value of distributed counter.

  - ### removeCounter

    void removeCounter(String key)
    This method used to remove specified key.
    Parameters:
      `key` - key to check in distributed map.

  - ### asyncGetAndAddCounter

    long asyncGetAndAddCounter(String key, long value)
    This method is used to get and then increment distributed counter asynchronously.
    Parameters:
      `key` - key to check in distributed map.
      `value` - value to add to distributed counter.
    Returns:
      the original distributed counter value.

  - ### asyncAddCounter

    long asyncAddCounter(String key, long value)
    This method is used to increment distributed counter asynchronously.
    Parameters:
      `key` - key to update in distributed map.
      `value` - value to increment
    Returns:
      the updated distributed counter value.

  - ### asyncGetAndAlterCounter

    long asyncGetAndAlterCounter(String key, long value)
    This method used to alter the DistributedCounter.
    Parameters:
      `key` - key to check in distributed map.
      `value` - value of distributed counter.
    Returns:
      the original distributed counter value.

  - ### asyncGetAlterAndSetExpiryOfCounter

    long asyncGetAlterAndSetExpiryOfCounter(String key, long value, long expiryTimeStamp)
    This method is used to get and then alter and then set expiry time of the DistributedCounter.
    Parameters:
      `key` - key to alter in distributed counter.
      `value` - value to alter in distributed counter.
      `expiryTimeStamp` - expiry time to set.
    Returns:
      the original distributed counter value.

  - ### getTimestamp

    long getTimestamp(String key)
    This method returns shared TimeStamp of distributed Key.
    Parameters:
      `key` - key to check in distributed map.
    Returns:
      timestamp value of key.

  - ### setTimestamp

    void setTimestamp(String key, long timeStamp)
    This method set the Timestamp to distributed map.
    Parameters:
      `key` - key to add in distributed map.
      `timeStamp` - timestamp to add.

  - ### setTimestampWithExpiry

    void setTimestampWithExpiry(String key, long timeStamp, long expiryTimeStamp)
    This method set the Timestamp to distributed map with an expiry time.
    Parameters:
      `key` - key to add in distributed map.
      `timeStamp` - timestamp to add.
      `expiryTimeStamp` - expiry timestamp to set

  - ### removeTimestamp

    void removeTimestamp(String key)
    This method removes the timestamp relevant to key.
    Parameters:
      `key` - key to check in distributed map.

  - ### isEnable

    boolean isEnable()

  - ### getType

    String getType()

  - ### setExpiry

    void setExpiry(String key, long expiryTimeStamp)

  - ### getTtl

    long getTtl(String key)

  - ### setLock

    long setLock(String key, String value)

  - ### setLockWithExpiry

    boolean setLockWithExpiry(String key, String value, long expiryTimeStamp) throws DistributedCounterException
    Throws:
      `DistributedCounterException`

  - ### getKeyLockRetrievalTimeout

    long getKeyLockRetrievalTimeout()

  - ### removeLock

    void removeLock(String key)

  - ### getWindowState

    default long[] getWindowState(String key) throws DistributedCounterException
    Atomically reads the window timestamp and counter for the given key.
    Parameters:
      `key` - distributed store key
    Returns:
      long[2]: {timestamp, counter}
    Throws:
      `DistributedCounterException`

  - ### setWindow

    default void setWindow(String key, long count, long ts, long expiryTime) throws DistributedCounterException
    Unconditionally sets a throttle window by overwriting both timestamp and counter, then setting the TTL. Must be called while holding the per-caller window lock so no concurrent writer can race. Stale data from a previous window is overwritten atomically.
    Parameters:
      `key` - distributed store key
      `count` - initial counter value
      `ts` - window first-access time in milliseconds
      `expiryTime` - absolute expiry timestamp in milliseconds (ts + unitTime)
    Throws:
      `DistributedCounterException`

  - ### incrWindowCounter

    default long incrWindowCounter(String key, long delta, long expiryTime) throws DistributedCounterException
    Atomically increments the window counter by `delta`, refreshes the TTL to `expiryTime`, and returns the new value. Refreshing the TTL guards against the narrow race where the hash key expires between the caller's pre-check and this call — without a TTL the HINCRBY-created hash would persist indefinitely.
    Parameters:
      `key` - distributed store key
      `delta` - value to add to the counter
      `expiryTime` - absolute window-end timestamp in ms (sharedTimestamp + unitTime)
    Returns:
      new global counter value after the increment
    Throws:
      `DistributedCounterException`