Bucket (bucket4j-core 5.0.0-beta.01-09-2020 API)

All Known Subinterfaces:

BucketProxy, LocalBucket

All Known Implementing Classes:

AbstractBucket, DefaultBucketProxy, LockFreeBucket, SynchronizedBucket
```
public interface Bucket
```
Performs rate limiting using algorithm based on top of ideas of Token Bucket.
Use following links for further details:
- Basic example of usage
- Advanced examples of usage

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`void`	`addTokens(long tokensToAdd)` Add `tokensToAdd` to bucket.
`BlockingBucket`	`asBlocking()` Returns the `BlockingBucket` view of this bucket, that provides operations which are able to block caller thread.
`ScheduledBucket`	`asScheduler()` TODO
`VerboseBucket`	`asVerbose()` Returns the verbose view of this bucket.
`static LocalBucketBuilder`	`builder()` Creates the new builder of in-memory buckets.
`long`	`consumeIgnoringRateLimits(long tokens)` Consumes `tokens` from bucket ignoring all limits.
`BucketState`	`createSnapshot()` Creates the copy of internal state.
`EstimationProbe`	`estimateAbilityToConsume(long numTokens)` Estimates ability to consume a specified number of tokens.
`long`	`getAvailableTokens()` Returns amount of available tokens in this bucket.
`void`	`replaceConfiguration(BucketConfiguration newConfiguration)` Replaces configuration of this bucket instance.
`Bucket`	`toListenable(BucketListener listener)` Returns new copy of this bucket instance decorated by `listener`.
`boolean`	`tryConsume(long numTokens)` Tries to consume a specified number of tokens from this bucket.
`ConsumptionProbe`	`tryConsumeAndReturnRemaining(long numTokens)` Tries to consume a specified number of tokens from this bucket.
`long`	`tryConsumeAsMuchAsPossible()` Tries to consume as much tokens from this bucket as available at the moment of invocation.
`long`	`tryConsumeAsMuchAsPossible(long limit)` Tries to consume as much tokens from bucket as available in the bucket at the moment of invocation, but tokens which should be consumed is limited by `limit`.

- Method Detail
  - builder
```
static LocalBucketBuilder builder()
```
    Creates the new builder of in-memory buckets.
    
    Returns:
    
    new instance of LocalBucketBuilder
  - asBlocking
```
BlockingBucket asBlocking()
```
    Returns the BlockingBucket view of this bucket, that provides operations which are able to block caller thread.
    
    Returns:
    
    the view to bucket that can be used as scheduler
  - asScheduler
```
ScheduledBucket asScheduler()
```
    TODO
  - asVerbose
```
VerboseBucket asVerbose()
```
    Returns the verbose view of this bucket.
  - tryConsume
```
boolean tryConsume(long numTokens)
```
    Tries to consume a specified number of tokens from this bucket.
    
    Parameters:
    
    numTokens - The number of tokens to consume from the bucket, must be a positive number.
    
    Returns:
    
    true if the tokens were consumed, false otherwise.
  - consumeIgnoringRateLimits
```
long consumeIgnoringRateLimits(long tokens)
```
    Consumes tokens from bucket ignoring all limits. In result of this operation amount of tokens in the bucket could became negative. There are two possible reasons to use this method:
    - An operation with high priority should be executed independently of rate limits, but it should take effect to subsequent operation with bucket.
    - You want to apply custom blocking strategy instead of default which applied on asScheduler().consume(tokens)
    Parameters:
    
    tokens - amount of tokens that should be consumed from bucket.
    
    Returns:
    the amount of rate limit violation in nanoseconds calculated in following way:
    
    zero if rate limit was not violated. For example bucket had 5 tokens before invocation of consumeIgnoringRateLimits(2), after invocation there are 3 tokens remain in the bucket, since limits were not violated zero returned as result.
    
    Positive value which describes the amount of rate limit violation in nanoseconds. For example bucket with limit 10 tokens per 1 second, currently has the 2 tokens available, last refill happen 100 milliseconds ago, and consumeIgnoringRateLimits(6) called. 300_000_000 will be returned as result and available tokens in the bucket will became -3, and any variation of tryConsume... will not be successful for 400 milliseconds(time required to refill amount of available tokens until 1).
  - tryConsumeAndReturnRemaining
```
ConsumptionProbe tryConsumeAndReturnRemaining(long numTokens)
```
    Tries to consume a specified number of tokens from this bucket.
    
    Parameters:
    
    numTokens - The number of tokens to consume from the bucket, must be a positive number.
    
    Returns:
    
    ConsumptionProbe which describes both result of consumption and tokens remaining in the bucket after consumption.
  - estimateAbilityToConsume
```
EstimationProbe estimateAbilityToConsume(long numTokens)
```
    Estimates ability to consume a specified number of tokens.
    
    Parameters:
    
    numTokens - The number of tokens to consume, must be a positive number.
    
    Returns:
    
    EstimationProbe which describes the ability to consume.
  - tryConsumeAsMuchAsPossible
```
long tryConsumeAsMuchAsPossible()
```
    Tries to consume as much tokens from this bucket as available at the moment of invocation.
    
    Returns:
    
    number of tokens which has been consumed, or zero if was consumed nothing.
  - tryConsumeAsMuchAsPossible
```
long tryConsumeAsMuchAsPossible(long limit)
```
    Tries to consume as much tokens from bucket as available in the bucket at the moment of invocation, but tokens which should be consumed is limited by limit.
    
    Parameters:
    
    limit - maximum number of tokens to consume, should be positive.
    
    Returns:
    
    number of tokens which has been consumed, or zero if was consumed nothing.
  - addTokens
```
void addTokens(long tokensToAdd)
```
    Add tokensToAdd to bucket. Resulted count of tokens are calculated by following formula:
```
newTokens = Math.min(capacity, currentTokens + tokensToAdd)
```
    in other words resulted number of tokens never exceeds capacity independent of tokensToAdd.
    Example of usage
    The "compensating transaction" is one of obvious use case, when any piece of code consumed tokens from bucket, tried to do something and failed, the "addTokens" will be helpful to return tokens back to bucket:
```
      Bucket wallet;
      ...
      if(wallet.tryConsume(50)) {// get 50 cents from wallet
         try {
             buyCocaCola();
         } catch(NoCocaColaException e) {
             // return money to wallet
             wallet.addTokens(50);
         }
      };
 
```
    Parameters:
    
    tokensToAdd - number of tokens to add
  - getAvailableTokens
```
long getAvailableTokens()
```
    Returns amount of available tokens in this bucket.
    This method designed to be used only for monitoring and testing, you should never use this method for business cases, because available tokens can be changed by concurrent transactions for case of multithreaded/multi-process environment.
    
    Returns:
    
    amount of available tokens
  - replaceConfiguration
```
void replaceConfiguration(BucketConfiguration newConfiguration)
```
    Replaces configuration of this bucket instance.
    Rules of reconfiguration:
    - New configuration can be applied if and only if it describes same count of bandwidths which already configured, else IncompatibleConfigurationException will be thrown. In other words you must not try to reduce or increase count of bandwidths, it is impossible to create bucket with one bandwidth and reconfigure to use two bandwidths and vice-versa.
    - If new configuration defines capacity which greater than current available tokens, then current available tokens stay unchanged.
    - If new configuration defines capacity which lesser than current available tokens, then current available tokens will be reduced to capacity. For example: if bandwidth at moment of reconfiguration has 90 tokens, and new capacity is 70 tokens then available tokens will be reduced from 90 to 70 according to new rules.
    Parameters:
    
    newConfiguration - the new configuration for this bucket
    
    Throws:
    
    IncompatibleConfigurationException - if newConfiguration incompatible with previous configuration
  - createSnapshot
```
BucketState createSnapshot()
```
    Creates the copy of internal state.
    This method is designed to be used only for monitoring and testing, you should never use this method for business cases.
    
    Returns:
    
    snapshot of internal state
  - toListenable
```
Bucket toListenable(BucketListener listener)
```
    Returns new copy of this bucket instance decorated by listener. The created bucket will share same tokens with source bucket and vice versa. See javadocs for BucketListener in order to understand semantic of listener.
    
    Parameters:
    
    listener - the listener of bucket events.
    
    Returns:
    
    new bucket instance decorated by listener

Interface Bucket

Method Summary

Method Detail

builder

asBlocking

asScheduler

asVerbose

tryConsume

consumeIgnoringRateLimits

tryConsumeAndReturnRemaining

estimateAbilityToConsume

tryConsumeAsMuchAsPossible

tryConsumeAsMuchAsPossible

addTokens

Example of usage

getAvailableTokens

replaceConfiguration

createSnapshot

toListenable