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 Bandwidth[]	bandwidths
protected BucketConfiguration	configuration
protected TimeMeter	timeMeter
protected static long	UNSPECIFIED_WAITING_LIMIT

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractBucket(BucketConfiguration configuration)

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) Consumes numTokens from the bucket.
boolean	consume(long tokensToConsume, long maxWaitTimeNanos) 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)
void	consumeUninterruptibly(long tokensToConsume) Consumes numTokens from the bucket.
boolean	consumeUninterruptibly(long tokensToConsume, long maxWaitTimeNanos) Consumes a specified number of tokens from the bucket.
BucketConfiguration	getConfiguration() Returns configuration of this 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

Field Detail

UNSPECIFIED_WAITING_LIMIT

protected static final long UNSPECIFIED_WAITING_LIMIT

See Also:

Constant Field Values

configuration

protected final BucketConfiguration configuration

bandwidths

protected final Bandwidth[] bandwidths

timeMeter

protected final TimeMeter timeMeter

Constructor Detail

AbstractBucket

protected AbstractBucket(BucketConfiguration configuration)

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)
                                       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)
             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.

Throws:

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

consume

public boolean consume(long tokensToConsume,
                       long maxWaitTimeNanos)
                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.

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)

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.

consumeUninterruptibly

public boolean consumeUninterruptibly(long tokensToConsume,
                                      long maxWaitTimeNanos)

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.

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

getConfiguration

public BucketConfiguration getConfiguration()

Description copied from interface: Bucket

Returns configuration of this bucket.

Specified by:

getConfiguration in interface Bucket

Returns:

configuration