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 Bucket.toListenable(BucketListener) method.

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

    Answer: it depends:
    • 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 Detail

      • NOPE

        static final BucketListener NOPE
        The default listener that do nothing.

    • Method Detail

      • 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