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

Interface Container

All Known Implementing Classes:
com.github.cowwoc.tokenbucket.internal.AbstractContainer, Bucket, ContainerList
public interface Container
A container of tokens.

  • Method Details

    • getUserData

      Object getUserData()
      Returns the data associated with this container.
      Returns:
      the data associated with this container

    • getChildren

      List<Container> getChildren()
      Returns the children containers.
      Returns:
      the children containers

    • getListeners

      List<ContainerListener> getListeners()
      Returns the listeners associated with this container.
      Returns:
      an unmodifiable list

    • tryConsume

      ConsumptionResult tryConsume()
      Consumes a single token, only if one is available at the time of invocation. Consumption order is not guaranteed to be fair.
      Returns:
      the result of the operation

    • tryConsume

      ConsumptionResult tryConsume(long tokens)
      Consumes tokens tokens, only if they are available at the time of invocation. Consumption order is not guaranteed to be fair.
      Parameters:
      tokens - the number of tokens to consume
      Returns:
      the result of the operation
      Throws:
      IllegalArgumentException - if tokens is negative or zero. If the request can never succeed because the container cannot hold the requested number of tokens.

    • tryConsume

      ConsumptionResult tryConsume(long tokens, long timeout, TimeUnit unit) throws InterruptedException
      Consumes the requested number of tokens, only if they become available within the given waiting time. Consumption order is not guaranteed to be fair.
      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:
      NullPointerException - if unit is null
      IllegalArgumentException - if tokens is negative or zero. If timeout is negative. If the request can never succeed because the container cannot hold the requested number of tokens.
      InterruptedException - if the thread is interrupted while waiting for tokens to become available

    • tryConsume

      ConsumptionResult tryConsume(long minimumTokens, long maximumTokens)
      Consumes [minimumTokens, maximumTokens] tokens, only if they are available at the time of invocation. Consumption order is not guaranteed to be fair.
      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:
      IllegalArgumentException - if the arguments are negative or zero. If minimumTokens > maximumTokens. If the request can never succeed because the container cannot hold the requested number of tokens.

    • tryConsume

      ConsumptionResult tryConsume(long minimumTokens, long maximumTokens, long timeout, TimeUnit unit) throws InterruptedException
      Consumes [minimumTokens, maximumTokens] tokens, only if they become available within the given waiting time. Consumption order is not guaranteed to be fair.
      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:
      NullPointerException - if unit is null
      IllegalArgumentException - if tokens is negative or zero. If timeout is negative. If minimumTokens > maximumTokens. If the request can never succeed because the container cannot hold the requested number of tokens.
      InterruptedException - if the thread is interrupted while waiting for tokens to become available

    • consume

      ConsumptionResult consume() throws InterruptedException
      Consumes a single token, blocking until it becomes available. Consumption order is not guaranteed to be fair.
      Returns:
      the result of the operation
      Throws:
      InterruptedException - if the thread is interrupted while waiting for tokens to become available

    • consume

      ConsumptionResult consume(long tokens) throws InterruptedException
      Consumes the specified number of tokens, blocking until they become available. Consumption order is not guaranteed to be fair.
      Parameters:
      tokens - the number of tokens to consume
      Returns:
      the result of the operation
      Throws:
      IllegalArgumentException - if tokens is negative or zero. If the request can never succeed because the container cannot hold the requested number of tokens.
      InterruptedException - if the thread is interrupted while waiting for tokens to become available

    • consume

      ConsumptionResult consume(long minimumTokens, long maximumTokens) throws InterruptedException
      Consumes [minimumTokens, maximumTokens] tokens, blocking until they become available. Consumption order is not guaranteed to be fair.
      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:
      NullPointerException - if unit is null
      IllegalArgumentException - if tokens or timeout are negative or zero. If minimumTokens > maximumTokens. If the request can never succeed because the container cannot hold the requested number of tokens.
      InterruptedException - if the thread is interrupted while waiting for tokens to become available