Module io.github.bucket4j.core

Package io.github.bucket4j

Interface BucketListener

All Known Implementing Classes:

SimpleBucketListener

public interface BucketListener

Interface for listening bucket related events. The typical use-cases of this interface are logging and monitoring.

The bucket can be decorated by listener via:

• Via LocalBucketBuilder.withListener(BucketListener) method at building time of local bucket.
• Via RemoteBucketBuilder.withListener(BucketListener) method at building time of distributed bucket.
• Via RemoteAsyncBucketBuilder.withListener(BucketListener) method at building time of async distributed bucket.
• Via Bucket.toListenable(BucketListener) method on bucket instance. Use this method when listener is not known at bucket build time.

Question: How many listeners is need to create in case of application uses many buckets?

Answer: it depends on:

• If you want to have aggregated statistics for all buckets then create single listener per application and reuse this listener for all buckets.
• If you want to measure statistics independently per each bucket then use listener per bucket model.

Question: where is methods of listener are invoking in case of distributed usage?

Answer: listener always invoked on client side, it is means that each client JVM will have own totally independent for same bucket.

Question: Why does bucket invoke the listener on client side instead of server side in case of distributed scenario? What I need to do if I need in aggregated stat across the whole cluster?

Answer: Because of planned expansion to non-JVM back-ends such as Redis, MySQL, PostgreSQL. It is not possible to serialize and invoke listener on this non-java back-ends, so it was decided to invoke listener on client side, in order to avoid inconsistency between different back-ends in the future. You can do post-aggregation of monitoring statistics via features built-into your monitoring database or via mediator(like StatsD) between your application and monitoring database.

See Also:

• SimpleBucketListener

Field Summary

Fields

Modifier and Type	Field	Description
static final BucketListener	NOPE	The default listener that do nothing.

Method Summary

Modifier and Type	Method	Description
default void	beforeParking(long nanos)	This method is called each time when thread is going to be parked for wait of tokens refill in result of interaction with BlockingBucket
void	onConsumed(long tokens)	This method is called whenever tokens is consumed.
void	onDelayed(long nanos)	This method is called each time when delayed task was submit to ScheduledExecutorService because of wait for tokens refill in result of interaction with SchedulingBucket
void	onInterrupted(InterruptedException e)	This method is called each time when thread was interrupted during the wait of tokens refill in result of interaction with BlockingBucket
void	onParked(long nanos)	This method is called each time when thread was parked for wait of tokens refill in result of interaction with BlockingBucket
void	onRejected(long tokens)	This method is called whenever consumption request for tokens is rejected.

Field Details

NOPE

static final BucketListener NOPE

The default listener that do nothing.

Method Details

onConsumed

void onConsumed(long tokens)

This method is called whenever tokens is consumed.

Parameters:

tokens - amount of tokens that consumed

onRejected

void onRejected(long tokens)

This method is called whenever consumption request for tokens is rejected.

Parameters:

tokens - amount of tokens that rejected

onParked

void onParked(long nanos)

This method is called each time when thread was parked for wait of tokens refill in result of interaction with BlockingBucket

Parameters:

nanos - amount of nanoseconds for which thread was parked

beforeParking

default void beforeParking(long nanos)

This method is called each time when thread is going to be parked for wait of tokens refill in result of interaction with BlockingBucket

Parameters:

nanos - amount of nanoseconds for which thread will be parked

onInterrupted

void onInterrupted(InterruptedException e)

This method is called each time when thread was interrupted during the wait of tokens refill in result of interaction with BlockingBucket

Parameters:

e - InterruptedException

onDelayed

void onDelayed(long nanos)

This method is called each time when delayed task was submit to ScheduledExecutorService because of wait for tokens refill in result of interaction with SchedulingBucket

Parameters:

nanos - amount of nanoseconds for which thread was parked