Module io.github.bucket4j.core

Package io.github.bucket4j

Interface BandwidthBuilder.BandwidthBuilderRefillStage

Enclosing class:

BandwidthBuilder

public static interface BandwidthBuilder.BandwidthBuilderRefillStage

Stage is responsible for configuration of refilling speed

Method Summary

Modifier and Type	Method	Description
BandwidthBuilder.BandwidthBuilderBuildStage	refillGreedy(long tokens, Duration period)	Configures refill that does refill of tokens in greedy manner, it will try to add the tokens to bucket as soon as possible.
BandwidthBuilder.BandwidthBuilderBuildStage	refillIntervally(long tokens, Duration period)	Configures refill that does refill of tokens in intervally manner.
BandwidthBuilder.BandwidthBuilderBuildStage	refillIntervallyAligned(long tokens, Duration period, Instant timeOfFirstRefill)	Configures refill that does refill of tokens in intervally manner.
BandwidthBuilder.BandwidthBuilderBuildStage	refillIntervallyAlignedWithAdaptiveInitialTokens(long tokens, Duration period, Instant timeOfFirstRefill)	Configures refill that does refill of tokens in intervally manner.

Method Detail

refillGreedy

BandwidthBuilder.BandwidthBuilderBuildStage refillGreedy(long tokens,
                                                         Duration period)

Configures refill that does refill of tokens in greedy manner, it will try to add the tokens to bucket as soon as possible. For example refill "10 tokens per 1 second" will add 1 token per each 100 millisecond, in other words refill will not wait 1 second to regenerate a bunch of 10 tokens.

The three refills bellow do refill of tokens with same speed:

      limit -> refillGreedy(600, Duration.ofMinutes(1))
      limit -> refillGreedy(10, Duration.ofSeconds(1))
      limit -> refillGreedy(1, Duration.ofMillis(100))
 

If greediness is undesired then you can specify the fixed interval refill via refillIntervally(long, Duration)

Parameters:

tokens - amount of tokens

period - the period within tokens will be fully regenerated

Returns:

the final build stage

refillIntervally

BandwidthBuilder.BandwidthBuilderBuildStage refillIntervally(long tokens,
                                                             Duration period)

Configures refill that does refill of tokens in intervally manner. "Intervally" in opposite to "greedy" will wait until whole period will be elapsed before regenerate tokens

Parameters:

tokens - amount of tokens

period - the period within tokens will be fully regenerated

Returns:

the final build stage

refillIntervallyAligned

BandwidthBuilder.BandwidthBuilderBuildStage refillIntervallyAligned(long tokens,
                                                                    Duration period,
                                                                    Instant timeOfFirstRefill)

Configures refill that does refill of tokens in intervally manner. "Intervally" in opposite to "greedy" will wait until whole period will be elapsed before regenerate tokens.
In additional to refillIntervally(long, Duration) this method allows to specify the time when first refill should happen via timeOfFirstRefill. This option can be used to configure clear interval boundary i.e. start of second, minute, hour, day.

 
         // imagine that wall clock is 16:20, the first refill will happen at 17:00
         // first refill will happen in the beginning of next hour
         Instant firstRefillTime = ZonedDateTime.now()
                 .truncatedTo(ChronoUnit.HOURS)
                 .plus(1, ChronoUnit.HOURS)
                 .toInstant();

        Bandwidth.builder(limit ->
             limit.capacity(600)
             .refillIntervallyAligned(400, Duration.ofHours(1), firstRefillTime)
        )
  

Parameters:

tokens - amount of tokens

period - the period within tokens will be fully regenerated

timeOfFirstRefill - the time of first refill, typically it should be a moment in the future

Returns:

the final build stage

refillIntervallyAlignedWithAdaptiveInitialTokens

BandwidthBuilder.BandwidthBuilderBuildStage refillIntervallyAlignedWithAdaptiveInitialTokens(long tokens,
                                                                                             Duration period,
                                                                                             Instant timeOfFirstRefill)

Configures refill that does refill of tokens in intervally manner. "Intervally" in opposite to "greedy" will wait until whole period will be elapsed before regenerate tokens.
In additional to refillIntervally(long, Duration) it is possible to specify the time when first refill should happen via timeOfFirstRefill. This option can be used to configure clear interval boundary i.e. start of second, minute, hour, day. Also for refill type, initial amount of tokens in the bandwidth will be calculated by following formula:

     Math.min(capacity, Math.max(0, bandwidthCapacity - refillTokens) + (timeOfFirstRefillMillis - nowMillis)/refillPeriod * refillTokens)
 

Bellow the list of examples of how does this formula can be applied:

 
         // imagine that wall clock is 16:20, the first refill will happen at 17:00
         // first refill will happen in the beginning of next hour
         Instant firstRefillTime = ZonedDateTime.now()
                 .truncatedTo(ChronoUnit.HOURS)
                 .plus(1, ChronoUnit.HOURS)
                 .toInstant();

        // initial tokens will be 266
        Bandwidth.builder(limit ->
             limit.capacity(400)
             .refillIntervallyAlignedWithAdaptiveInitialTokens(400, Duration.ofHours(1), firstRefillTime)
        )
        // calculated by formula min(400, max(0, 400 - 400) +  40/60*400) = min(400, 0 + 266) = 266

        // initial tokens will be 300
        Bandwidth.builder(limit ->
              limit.capacity(400)
              .refillIntervallyAlignedWithAdaptiveInitialTokens(300, Duration.ofHours(1), firstRefillTime)
        )
        // calculated by formula min(400, max(0, 400 - 300) +  40/60*300) = min(400, 100 + 200) = 300

        // initial tokens will be 333
        Bandwidth.builder(limit ->
               limit.capacity(400)
               .refillIntervallyAlignedWithAdaptiveInitialTokens(200, Duration.ofHours(1), firstRefillTime)
        )
        // calculated by formula min(400, max(0, 400 - 200) +  40/60*200) = min(400, 200 + 133) = 333

        // initial tokens will be 366
        Bandwidth.builder(limit ->
                limit.capacity(400)
                .refillIntervallyAlignedWithAdaptiveInitialTokens(100, Duration.ofHours(1), firstRefillTime)
        )
        // calculated by formula min(400, max(0, 400 - 100) +  40/60*100) = min(400, 300 + 66) = 366
 

Restrictions:

• If useAdaptiveInitialTokens is true then any attempt to explicitly specify initial amount of tokens via BandwidthBuilder.BandwidthBuilderBuildStage.initialTokens(long) will fail with exception, because it is impossible at the same time to specify tokens in explicitly and adaptively manners.
• It is impossible to use this method together with nanoTime based clock LocalBucketBuilder.withNanosecondPrecision(), because we need in System.currentTimeMillis() based clock in order to properly measure the distance from timeOfFirstRefill

Parameters:

tokens - amount of tokens

period - the period within tokens will be fully regenerated

timeOfFirstRefill - the time of first refill, typically it should be a moment in the future

Returns:

the final build stage