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 Details

    • 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:
      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