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

Class Limit.Builder

java.lang.Object
com.github.cowwoc.tokenbucket.Limit.Builder
Enclosing class:
Limit
public static final class Limit.Builder extends Object
Builds a Limit.

  • Method Details

    • tokensPerPeriod

      public long tokensPerPeriod()
      Returns the number of tokens to add to the bucket every period. The default is 1.
      Returns:
      the number of tokens to add to the bucket every period

    • tokensPerPeriod

      public Limit.Builder tokensPerPeriod(long tokensPerPeriod)
      Sets the number of tokens to add to the bucket every period.
      Parameters:
      tokensPerPeriod - the number of tokens to add to the bucket every period
      Returns:
      this
      Throws:
      IllegalArgumentException - if tokensPerPeriod is negative or zero

    • period

      public Duration period()
      Indicates how often tokensPerPeriod should be added to the bucket. The default is 1 second.
      Returns:
      how often tokensPerPeriod should be added to the bucket

    • period

      public Limit.Builder period(Duration period)
      Indicates how often tokensPerPeriod should be added to the bucket.
      Parameters:
      period - indicates how often tokensPerPeriod should be added to the bucket
      Returns:
      this
      Throws:
      IllegalArgumentException - if period is negative or zero
      NullPointerException - if period is null

    • initialTokens

      public long initialTokens()
      Returns the initial number of tokens in the bucket. The value may be negative, in which case the bucket must accumulate a positive number of tokens before they may be consumed. The default is 0.
      Returns:
      the number amount of tokens in the bucket

    • initialTokens

      public Limit.Builder initialTokens(long initialTokens)
      Sets the initial number of tokens in the bucket. The value may be negative, in which case the bucket must accumulate a positive number of tokens before they may be consumed.
      Parameters:
      initialTokens - the initial number of tokens in the bucket
      Returns:
      this

    • maximumTokens

      public long maximumTokens()
      Returns the maximum number of tokens that the bucket may hold before overflowing. The default is Long.MAX_VALUE.
      Returns:
      the maximum number of tokens that the bucket may hold before overflowing (subsequent tokens are discarded)

    • maximumTokens

      public Limit.Builder maximumTokens(long maximumTokens)
      Sets the maximum number of tokens that the bucket may hold before overflowing.
      Parameters:
      maximumTokens - the maximum number of tokens that the bucket may hold before overflowing (subsequent tokens are discarded)
      Returns:
      this
      Throws:
      IllegalArgumentException - if maximumTokens is negative or zero

    • refillSize

      public long refillSize()
      Returns the number of tokens that are refilled at a time.

      At one end of the spectrum, one may refill tokens one at a time during the period. On the other spectrum, one may refill tokensPerPeriod tokens once per period.

      NOTE: When completing a period a smaller number of tokens may be refilled in order to avoid surpassing tokensPerPeriod due to rounding errors.

      The default is 1.

      Returns:
      the minimum number of tokens by which the limit may be refilled

    • refillSize

      public Limit.Builder refillSize(long refillSize)
      Sets the number of tokens that are refilled at a time.

      At one end of the spectrum, one may refill tokens one at a time during the period. On the other spectrum, one may refill tokensPerPeriod tokens once per period.

      NOTE: When completing a period a smaller number of tokens may be refilled in order to avoid surpassing tokensPerPeriod due to rounding errors.

      Parameters:
      refillSize - the minimum number of tokens by which the limit may be refilled
      Returns:
      this
      Throws:
      IllegalArgumentException - if refillSize is negative or zero

    • userData

      public Object userData()
      Returns user data associated with this limit. The default is null.
      Returns:
      the data associated with this limit

    • userData

      public Limit.Builder userData(Object userData)
      Sets user data associated with this limit.
      Parameters:
      userData - the data associated with this limit
      Returns:
      this

    • build

      public Limit build()
      Builds a new Limit.
      Returns:
      a new Limit

    • toString

      public String toString()
      Overrides:
      toString in class Object