io.github.bucket4j

Class AbstractBucket

java.lang.Object

io.github.bucket4j.AbstractBucket

All Implemented Interfaces:

Bucket

Direct Known Subclasses:

GridBucket, LockFreeBucket, SynchronizedBucket, UnsafeBucket

public abstract class AbstractBucket
extends Object
implements Bucket

Field Summary

Fields

Modifier and Type	Field and Description
protected static long	UNSPECIFIED_WAITING_LIMIT

Constructor Summary

Constructors

Constructor and Description
AbstractBucket()

Method Summary

Modifier and Type	Method and Description
void	addTokens(long tokensToAdd) Add tokensToAdd to each bandwidth of bucket.
protected abstract void	addTokensImpl(long tokensToAdd)
void	consume(long tokensToConsume, BlockingStrategy blockingStrategy) Consumes numTokens from the bucket.
boolean	consume(long tokensToConsume, long maxWaitTimeNanos, BlockingStrategy blockingStrategy) Consumes a specified number of tokens from the bucket.
protected abstract long	consumeAsMuchAsPossibleImpl(long limit)
protected abstract boolean	consumeOrAwaitImpl(long tokensToConsume, long waitIfBusyNanos, boolean uninterruptibly, BlockingStrategy blockingStrategy)
void	consumeUninterruptibly(long tokensToConsume, BlockingStrategy blockingStrategy) Consumes numTokens from the bucket.
boolean	consumeUninterruptibly(long tokensToConsume, long maxWaitTimeNanos, BlockingStrategy blockingStrategy) Consumes a specified number of tokens from the bucket.
boolean	tryConsume(long tokensToConsume) 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 than not more than limit.
protected abstract boolean	tryConsumeImpl(long tokensToConsume)

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.github.bucket4j.Bucket

createSnapshot, getConfiguration

Field Detail

UNSPECIFIED_WAITING_LIMIT

protected static final long UNSPECIFIED_WAITING_LIMIT

See Also:

Constant Field Values

Constructor Detail

AbstractBucket

public AbstractBucket()

Method Detail

consumeAsMuchAsPossibleImpl

protected abstract long consumeAsMuchAsPossibleImpl(long limit)

tryConsumeImpl

protected abstract boolean tryConsumeImpl(long tokensToConsume)

consumeOrAwaitImpl

protected abstract boolean consumeOrAwaitImpl(long tokensToConsume,
                                              long waitIfBusyNanos,
                                              boolean uninterruptibly,
                                              BlockingStrategy blockingStrategy)
                                       throws InterruptedException

Throws:

InterruptedException

addTokensImpl

protected abstract void addTokensImpl(long tokensToAdd)

tryConsume

public boolean tryConsume(long tokensToConsume)

Description copied from interface: Bucket

Tries to consume a specified number of tokens from this bucket.

Specified by:

tryConsume in interface Bucket

Parameters:

tokensToConsume - The number of tokens to consume from the bucket, must be a positive number.

Returns:

true if the tokens were consumed, false otherwise.

consume

public void consume(long tokensToConsume,
                    BlockingStrategy blockingStrategy)
             throws InterruptedException

Description copied from interface: Bucket

Consumes numTokens from the bucket. If enough tokens are not currently available then this method will block until required number of tokens will be available or current thread is interrupted.

Specified by:

consume in interface Bucket

Parameters:

tokensToConsume - The number of tokens to consume from bucket, must be a positive number.

blockingStrategy - specifies the way to block current thread to amount of time required to refill missed number of tokens in the bucket

Throws:

InterruptedException - in case of current thread has been interrupted during waiting

consume

public boolean consume(long tokensToConsume,
                       long maxWaitTimeNanos,
                       BlockingStrategy blockingStrategy)
                throws InterruptedException

Description copied from interface: Bucket

Consumes a specified number of tokens from the bucket. If required count of tokens is not currently available then this method will block until required number of tokens will be available or current thread is interrupted, or maxWaitTimeNanos has elapsed.

Specified by:

consume in interface Bucket

Parameters:

tokensToConsume - The number of tokens to consume from the bucket.

maxWaitTimeNanos - limit of time which thread can wait.

blockingStrategy - specifies the way to block current thread to amount of time required to refill missed number of tokens in the bucket

Returns:

true if numTokens has been consumed or false when numTokens has not been consumed

Throws:

InterruptedException - in case of current thread has been interrupted during waiting

consumeUninterruptibly

public void consumeUninterruptibly(long tokensToConsume,
                                   BlockingStrategy blockingStrategy)

Description copied from interface: Bucket

Consumes numTokens from the bucket. If enough tokens are not currently available then this method will block until required number of tokens will be available or current thread is interrupted.

Specified by:

consumeUninterruptibly in interface Bucket

Parameters:

tokensToConsume - The number of tokens to consume from bucket, must be a positive number.

blockingStrategy - specifies the way to block current thread to amount of time required to refill missed number of tokens in the bucket

consumeUninterruptibly

public boolean consumeUninterruptibly(long tokensToConsume,
                                      long maxWaitTimeNanos,
                                      BlockingStrategy blockingStrategy)

Description copied from interface: Bucket

Consumes a specified number of tokens from the bucket. If required count of tokens is not currently available then this method will block until required number of tokens will be available or current thread is interrupted.

Specified by:

consumeUninterruptibly in interface Bucket

Parameters:

tokensToConsume - The number of tokens to consume from the bucket.

maxWaitTimeNanos - limit of time which thread can wait.

blockingStrategy - specifies the way to block current thread to amount of time required to refill missed number of tokens in the bucket

Returns:

true if numTokens has been consumed or false when numTokens has not been consumed

tryConsumeAsMuchAsPossible

public long tryConsumeAsMuchAsPossible(long limit)

Description copied from interface: Bucket

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 than not more than limit.

Specified by:

tryConsumeAsMuchAsPossible in interface Bucket

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.

tryConsumeAsMuchAsPossible

public long tryConsumeAsMuchAsPossible()

Description copied from interface: Bucket

Tries to consume as much tokens from this bucket as available at the moment of invocation.

Specified by:

tryConsumeAsMuchAsPossible in interface Bucket

Returns:

number of tokens which has been consumed, or zero if was consumed nothing.

addTokens

public void addTokens(long tokensToAdd)

Description copied from interface: Bucket

Add tokensToAdd to each bandwidth of 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;
      ...
      wallet.consume(50); // get 50 cents from wallet
      try {
          buyCocaCola();
      } catch(NoCocaColaException e) {
          // return money to wallet
          wallet.addTokens(50);
      }
 

Specified by:

addTokens in interface Bucket

Parameters:

tokensToAdd - number of tokens to add