TimeBucketCounterBase (Apache Tomcat 9.0.121 API Documentation)
Description: declaration: package: org.apache.catalina.util, class: TimeBucketCounterBase

# Class TimeBucketCounterBase

java.lang.Object
org.apache.catalina.util.TimeBucketCounterBase

Direct Known Subclasses:
  `TimeBucketCounter`

public abstract class TimeBucketCounterBase extends Object
This class maintains a thread safe hash map that has timestamp-based buckets followed by a string for a key, and a counter for an integer value. Each time the increment() method is called it adds the key if it does not exist, increments its value and returns it.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TimeBucketCounterBase(int bucketDuration, ScheduledExecutorService executorService)`
  Creates a new TimeBucketCounter with the specified lifetime.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `destroy()`
  Stops threads created by this object and cleans up resources.
  `protected final String`
  `genKey(String identifier)`
  Generates the key of timeBucket counter maps with the specific identifier, and the timestamp is implicitly equivalent to "now".
  `protected final String`
  `genKey(String identifier, long timestamp)`
  Generates the key of timeBucket counter maps with the specific identifier and timestamp.
  `int`
  `getBucketDuration()`
  Returns the duration of each time bucket.
  `protected abstract long`
  `getBucketIndex(long timestamp)`
  Calculate the bucket index for the specific timestamp.
  `int`
  `getCurrentBucketPrefix()`
  Returns current bucket prefix
  `abstract long`
  `getMillisUntilNextBucket()`
  When we want to test a full bucket duration we need to sleep until the next bucket starts.
  `abstract double`
  `getRatio()`
  Returns the ratio between the configured duration param and the actual duration.
  `final int`
  `increment(String identifier)`
  Increments the counter for the passed identifier in the current time bucket and returns the new value.
  `void`
  `periodicEvict()`
  Periodic evict, perform removal of obsolete bucket items.

  ### Methods inherited from class Object

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

- ## Constructor Details

  - ### TimeBucketCounterBase

    public TimeBucketCounterBase(int bucketDuration, ScheduledExecutorService executorService)
    Creates a new TimeBucketCounter with the specified lifetime.
    Parameters:
      `bucketDuration` - duration in seconds, e.g. for 1 minute pass 60
      `executorService` - the executor service that will be used to run the maintenance task
    Throws:
      `NullPointerException` - if executorService is `null`.
      `IllegalArgumentException` - if bucketDuration is not strictly positive

- ## Method Details

  - ### getBucketDuration

    public int getBucketDuration()
    Returns the duration of each time bucket.
    Returns:
      the bucket duration in seconds

  - ### getRatio

    public abstract double getRatio()
    Returns the ratio between the configured duration param and the actual duration.
    Returns:
      the ratio between the configured duration param and the actual duration.

  - ### increment

    public final int increment(String identifier)
    Increments the counter for the passed identifier in the current time bucket and returns the new value.
    Parameters:
      `identifier` - an identifier for which we want to maintain count, e.g. IP Address
    Returns:
      the count within the current time bucket

  - ### genKey

    protected final String genKey(String identifier)
    Generates the key of timeBucket counter maps with the specific identifier, and the timestamp is implicitly equivalent to "now".
    Parameters:
      `identifier` - an identifier for which we want to maintain count
    Returns:
      key of timeBucket counter maps

  - ### genKey

    protected final String genKey(String identifier, long timestamp)
    Generates the key of timeBucket counter maps with the specific identifier and timestamp.
    Parameters:
      `identifier` - of target request
      `timestamp` - when target request received
    Returns:
      key of timeBucket counter maps

  - ### getBucketIndex

    protected abstract long getBucketIndex(long timestamp)
    Calculate the bucket index for the specific timestamp.
    Parameters:
      `timestamp` - the specific timestamp in milliseconds
    Returns:
      prefix the bucket key prefix for the specific timestamp

  - ### getCurrentBucketPrefix

    public int getCurrentBucketPrefix()
    Returns current bucket prefix
    Returns:
      bucket index

  - ### getMillisUntilNextBucket

    public abstract long getMillisUntilNextBucket()
    When we want to test a full bucket duration we need to sleep until the next bucket starts.

    WARNING: This method is used for test purpose.

    Returns:
      the number of milliseconds until the next bucket

  - ### destroy

    public void destroy()
    Stops threads created by this object and cleans up resources.

  - ### periodicEvict

    public void periodicEvict()
    Periodic evict, perform removal of obsolete bucket items. Absence of this operation may result in OOM after a long run.