io.github.bucket4j.TokensInheritanceStrategy Maven / Gradle / Ivy
/*-
* ========================LICENSE_START=================================
* Bucket4j
* %%
* Copyright (C) 2015 - 2020 Vladimir Bukhtoyarov
* %%
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
* =========================LICENSE_END==================================
*/
package io.github.bucket4j;
/**
* Specifies the rules for inheritance of available tokens when {@link Bucket#replaceConfiguration(BucketConfiguration, TokensInheritanceStrategy)} happens.
*/
public enum TokensInheritanceStrategy {
/**
* Makes to copy available tokens proportional to bandwidth capacity by following formula:
*
* newAvailableTokens = availableTokensBeforeReplacement * (newBandwidthCapacity / capacityBeforeReplacement)
*
*
*
* Let's describe few examples.
*
*
Example 1: imagine bandwidth that was created by {@code Bandwidth.builder().capacity(100).refillGreedy(10, ofMinutes(1)).build()}.
* At the moment of config replacement it was 40 available tokens. After replacing this bandwidth by following {@code Bandwidth.builder().capacity(200).refillGreedy(10, ofMinutes(1)).build()}
* 40 available tokens will be multiplied by 2(200/100), and after replacement we will have 80 available tokens.
*
*
Example 2: imagine bandwidth that was created by {@code Bandwidth.builder().capacity(100).refillGreedy(10, ofMinutes(1)).build()}.
* At the moment of config replacement it was 40 available tokens. After replacing this bandwidth by following {@code Bandwidth.builder().capacity(20).refillGreedy(10, ofMinutes(1)).build()}
* 40 available tokens will be multiplied by 0.2(20/100), and after replacement we will have 8 available tokens.
*/
PROPORTIONALLY((byte) 0),
/**
* Instructs to copy available tokens as is, but with one exclusion: if available tokens is greater than new capacity,
* available tokens will be decreased to new capacity.
*
*
* Let's describe few examples.
*
*
Example 1: imagine bandwidth that was created by {@code Bandwidth.builder().capacity(100).refillGreedy(10, ofMinutes(1)).build()}.
* At the moment of config replacement it was 40 available tokens. After replacing this bandwidth by following {@code Bandwidth.builder().capacity(200).refillGreedy(10, ofMinutes(1)).build()}
* 40 available tokens will be just copied, and after replacement we will have 40 available tokens.
*
*
Example 2: imagine bandwidth that was created by {@code Bandwidth.builder().capacity(100).refillGreedy(10, ofMinutes(1)).build()}.
* At the moment of config replacement it was 40 available tokens. After replacing this bandwidth by following {@code Bandwidth.builder().capacity(20).refillGreedy(10, ofMinutes(1)).build()}
* 40 available tokens can not be copied as is, because it is greater than new capacity, so available tokens will be reduced to 20.
*/
AS_IS((byte) 1),
/**
* Use this mode when you want just to forget about previous bucket state.
* {@code bucket.replaceConfiguration(newConfiguration, TokensInheritanceStrategy.RESET)} just erases all previous state.
* Using this strategy equals to removing bucket and creating again with new configuration.
*/
RESET((byte) 2),
/**
* Instructs to copy available tokens as is, but with one exclusion: if new bandwidth capacity is greater than old capacity, available tokens will be increased by the difference between the old and the new configuration.
*
*
* The formula is newAvailableTokens = Math.min(availableTokensBeforeReplacement, newBandwidthCapacity) + Math.max(0, newBandwidthCapacity - capacityBeforeReplacement)
*
*
* Let's describe few examples.
*
*
* Example 1: imagine bandwidth that was created by {@code Bandwidth.builder().capacity(100).refillGreedy(10, ofMinutes(1)).build()}.
* At the moment of configuration replacement, it was 40 available tokens.
* After replacing this bandwidth by following {@code Bandwidth.builder().capacity(200).refillGreedy(200, ofMinutes(1)).build()} 40 available tokens will be copied and added to the difference between old and new configuration,
* and after replacement, we will have 140 available tokens.
*
*
* Example 2: imagine bandwidth that was created by {@code Bandwidth.builder().capacity(100).refillGreedy(10, ofMinutes(1)).build()}.
* At the moment of config replacement it was 40 available tokens.
* After replacing this bandwidth by following {@code Bandwidth.builder().capacity(20).refillGreedy(10, ofMinutes(1)).build()},
* and after replacement we will have 20 available tokens.
*
*
* Example 3: imagine bandwidth that was created by {@code Bandwidth.builder().capacity(100).refillGreedy(10, ofMinutes(1)).build()}.
* At the moment of config replacement it was 10 available tokens.
* After replacing this bandwidth by following {@code Bandwidth.builder().capacity(100).refillGreedy(20, ofMinutes(1)).build()},
* and after replacement we will have 10 available tokens.
*/
ADDITIVE((byte) 3)
;
private final byte id;
TokensInheritanceStrategy(byte id) {
this.id = id;
}
private static final TokensInheritanceStrategy[] modes = new TokensInheritanceStrategy[] {
PROPORTIONALLY, AS_IS, RESET, ADDITIVE
};
public static TokensInheritanceStrategy getById(byte id) {
return modes[id];
}
public byte getId() {
return id;
}
}