Module io.github.bucket4j.core
Package io.github.bucket4j

Class Bandwidth

  • All Implemented Interfaces:
    ComparableByContent<Bandwidth>
    public class Bandwidth
extends Object
implements ComparableByContent<Bandwidth>

    Anatomy of bandwidth:

    The bandwidth is key building block for bucket. The bandwidth consists from capacity and refill. Where:
    • Capacity - defines the maximum count of tokens which can be hold by bucket.
    • Refill - defines the speed in which tokens are regenerated in bucket.

    Classic and simple bandwidth definitions:

    The bandwidth can be initialized in the two way:
    • Simple - most popular way, which does not require from you to fully understand the token-bucket algorithm. Use this way when you just want to specify easy limitation N tokens per M time window.
    • classic(long, Refill) Classic} - hard way to specify limitation, use it when you want to utilize the whole power of token-bucket.

    Multiple bandwidths:

    Most likely you will use only one bandwidth per bucket, but in general it is possible to specify more than one bandwidth per bucket, and bucket will handle all bandwidth in strongly atomic way. Strongly atomic means that token will be consumed from all bandwidth or from nothing, in other words any token can not be partially consumed.
    Example of multiple bandwidth: 
    // Adds bandwidth that restricts to consume not often 1000 tokens per 1 minute and not often than 100 tokens per second
 Bucket bucket = Bucket.builder().
      .addLimit(Bandwidth.create(1000, Duration.ofMinutes(1)));
      .addLimit(Bandwidth.create(100, Duration.ofSeconds(1)));
      .build()

    • Method Detail

      • simple

        public static Bandwidth simple​(long capacity,
                               Duration period)
        Specifies simple limitation capacity tokens per period time window.
        Parameters:
        capacity -
        period -
        Returns:

      • classic

        public static Bandwidth classic​(long capacity,
                                Refill refill)
        Specifies limitation in conventional interpretation of token-bucket algorithm.
        Parameters:
        capacity -
        refill -
        Returns:

      • withInitialTokens

        public Bandwidth withInitialTokens​(long initialTokens)
        By default new created bandwidth has amount tokens that equals its capacity. This method allows to replace initial tokens.
        Parameters:
        initialTokens -
        Returns:
        the copy of this bandwidth with new value ofof initial tokens.

      • isIntervallyAligned

        public boolean isIntervallyAligned()

      • getTimeOfFirstRefillMillis

        public long getTimeOfFirstRefillMillis()

      • getCapacity

        public long getCapacity()

      • getInitialTokens

        public long getInitialTokens()

      • getRefillPeriodNanos

        public long getRefillPeriodNanos()

      • getRefillTokens

        public long getRefillTokens()

      • isUseAdaptiveInitialTokens

        public boolean isUseAdaptiveInitialTokens()

      • isRefillIntervally

        public boolean isRefillIntervally()

      • isGready

        public boolean isGready()

      • getId

        public String getId()

      • hasId

        public boolean hasId()

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object