Module com.github.cowwoc.tokenbucket
Package com.github.cowwoc.tokenbucket

Class Bucket

java.lang.Object
com.github.cowwoc.tokenbucket.internal.AbstractContainer
com.github.cowwoc.tokenbucket.Bucket
All Implemented Interfaces:
Container
public final class Bucket extends com.github.cowwoc.tokenbucket.internal.AbstractContainer
A container with Limits.

Thread safety: This class is thread-safe.

  • Method Details

    • builder

      public static Bucket.Builder builder()
      Builds a new bucket.
      Returns:
      a Bucket builder

    • getLimits

      public List<Limit> getLimits()
      Returns the limits associated with this bucket.
      Returns:
      an unmodifiable list

    • getLimitWithLowestRefillRate

      public Limit getLimitWithLowestRefillRate()
      Returns the limit with the lowest refill rate. Note that this differs from the concept of refillSize as the former corresponds to the number of tokens refilled per fixed period of time.
      Returns:
      the limit with the lowest refill rate

    • updateConfiguration

      public Bucket.ConfigurationUpdater updateConfiguration()
      Updates this Bucket's configuration.

      The Bucket will be locked until Bucket.ConfigurationUpdater.close() is invoked.

      Returns:
      the configuration updater

    • getListeners

      public List<ContainerListener> getListeners()
      Description copied from interface: Container
      Returns the listeners associated with this container.
      Specified by:
      getListeners in interface Container
      Overrides:
      getListeners in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Returns:
      an unmodifiable list

    • getUserData

      public Object getUserData()
      Description copied from interface: Container
      Returns the data associated with this container.
      Specified by:
      getUserData in interface Container
      Overrides:
      getUserData in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Returns:
      the data associated with this container

    • tryConsume

      public ConsumptionResult tryConsume()
      Description copied from interface: Container
      Consumes a single token, only if one is available at the time of invocation. Consumption order is not guaranteed to be fair.
      Specified by:
      tryConsume in interface Container
      Overrides:
      tryConsume in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Returns:
      the result of the operation

    • tryConsume

      public ConsumptionResult tryConsume(long tokens)
      Description copied from interface: Container
      Consumes tokens tokens, only if they are available at the time of invocation. Consumption order is not guaranteed to be fair.
      Specified by:
      tryConsume in interface Container
      Overrides:
      tryConsume in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Parameters:
      tokens - the number of tokens to consume
      Returns:
      the result of the operation

    • tryConsume

      public ConsumptionResult tryConsume(long tokens, long timeout, TimeUnit unit) throws InterruptedException
      Description copied from interface: Container
      Consumes the requested number of tokens, only if they become available within the given waiting time. Consumption order is not guaranteed to be fair.
      Specified by:
      tryConsume in interface Container
      Overrides:
      tryConsume in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Parameters:
      tokens - the number of tokens to consume
      timeout - the maximum number of time to wait
      unit - the unit of timeout
      Returns:
      the result of the operation
      Throws:
      InterruptedException - if the thread is interrupted while waiting for tokens to become available

    • tryConsume

      public ConsumptionResult tryConsume(long minimumTokens, long maximumTokens)
      Description copied from interface: Container
      Consumes [minimumTokens, maximumTokens] tokens, only if they are available at the time of invocation. Consumption order is not guaranteed to be fair.
      Specified by:
      tryConsume in interface Container
      Overrides:
      tryConsume in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Parameters:
      minimumTokens - the minimum number of tokens to consume (inclusive)
      maximumTokens - the maximum number of tokens to consume (inclusive)
      Returns:
      the result of the operation

    • tryConsume

      public ConsumptionResult tryConsume(long minimumTokens, long maximumTokens, long timeout, TimeUnit unit) throws InterruptedException
      Description copied from interface: Container
      Consumes [minimumTokens, maximumTokens] tokens, only if they become available within the given waiting time. Consumption order is not guaranteed to be fair.
      Specified by:
      tryConsume in interface Container
      Overrides:
      tryConsume in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Parameters:
      minimumTokens - the minimum number of tokens to consume (inclusive)
      maximumTokens - the maximum number of tokens to consume (inclusive)
      timeout - the maximum amount of time to wait
      unit - the unit of timeout
      Returns:
      the result of the operation
      Throws:
      InterruptedException - if the thread is interrupted while waiting for tokens to become available

    • consume

      public ConsumptionResult consume() throws InterruptedException
      Description copied from interface: Container
      Consumes a single token, blocking until it becomes available. Consumption order is not guaranteed to be fair.
      Specified by:
      consume in interface Container
      Overrides:
      consume in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Returns:
      the result of the operation
      Throws:
      InterruptedException - if the thread is interrupted while waiting for tokens to become available

    • consume

      public ConsumptionResult consume(long tokens) throws InterruptedException
      Description copied from interface: Container
      Consumes the specified number of tokens, blocking until they become available. Consumption order is not guaranteed to be fair.
      Specified by:
      consume in interface Container
      Overrides:
      consume in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Parameters:
      tokens - the number of tokens to consume
      Returns:
      the result of the operation
      Throws:
      InterruptedException - if the thread is interrupted while waiting for tokens to become available

    • consume

      public ConsumptionResult consume(long minimumTokens, long maximumTokens) throws InterruptedException
      Description copied from interface: Container
      Consumes [minimumTokens, maximumTokens] tokens, blocking until they become available. Consumption order is not guaranteed to be fair.
      Specified by:
      consume in interface Container
      Overrides:
      consume in class com.github.cowwoc.tokenbucket.internal.AbstractContainer
      Parameters:
      minimumTokens - the minimum number of tokens to consume (inclusive)
      maximumTokens - the maximum number of tokens to consume (inclusive)
      Returns:
      the result of the operation
      Throws:
      InterruptedException - if the thread is interrupted while waiting for tokens to become available

    • toString

      public String toString()
      Overrides:
      toString in class Object