#69 7.0.0 documentation

asciidoc/src/main/docs/asciidoc/basic/api-reference.adoc

@@ -162,14 +162,14 @@ long getAvailableTokens();
 ===== builder
 [source, java]
 ----
-/**
-* Creates the new builder of in-memory buckets.
-*
-* @return new instance of {@link LocalBucketBuilder}
-*/
-static LocalBucketBuilder builder() {
-    return new LocalBucketBuilder();
-}
+    /**
+    * Creates the new builder of in-memory buckets.
+    *
+    * @return new instance of {@link LocalBucketBuilder}
+    */
+    static LocalBucketBuilder builder() {
+        return new LocalBucketBuilder();
+    }
 ----
 
 ===== replaceConfiguration

asciidoc/src/main/docs/asciidoc/distributed/asynchronous.adoc

@@ -50,7 +50,7 @@ public class SmsServlet extends javax.servlet.http.HttpServlet {
         
         smsSender = (SmsSender) ctx.getAttribute("sms-sender");
         
-        FunctionalMapImpl<String, GridBucketState> bucketMap = (FunctionalMapImpl<String, GridBucketState>) ctx.getAttribute("bucket-map");
+        FunctionalMapImpl<String, byte[]> bucketMap = (FunctionalMapImpl<String, byte[]>) ctx.getAttribute("bucket-map");
         this.buckets = Bucket4j.extension(Infinispan.class).proxyManagerForMap(bucketMap);
         
         this.configuration = () -> {

asciidoc/src/main/docs/asciidoc/distributed/concepts.adoc

@@ -0,0 +1,32 @@
+//=== The design
+//
+//
+//
+//When rate-limiter
+//
+//==== Vocubalarity
+//Distributed use-case of Bucket4j brings following entities that need to added to vocubalarity in additionaly to already mentioned:
+//
+//
+
+// BucketProxy Provides a light-weight proxy to bucket which state actually stored in external storage, like in-memory jvm or relational database. Is represented by
+
+//=== Concurrency Guarantees
+//**Question:** is the provided JCache integration safe across multiple JVMs? Does it ensure that two nodes creating a bucket simultaneously on a given Cache<K, V> will only actually create one single bucket (without resetting a previously created one with the same key)?
+//**Answer:** Yes. JCache integration is safe for multi node environment, Bucket4j never replaces bucket which already exists.
+//This behavior is guaranteed by **putIfAbsent** method contract of [javax.cache.Cache](http://static.javadoc.io/javax.cache/cache-api/1.0.0/javax/cache/Cache.html) class.
+//
+//**Question:** Does ProxyManager store buckets internally, could be this a reason of OutOfMemoryError?
+//**Answer:** No. ProxyManager stores nothing about buckets which it returns, the buckets actually stored in in-memory GRID outside client JVM.
+//Think about proxy returned by ``ProxyManager#getBucket`` just about very cheap pointer to data which actually stored somewhere outside.
+//So, independently of count of buckets ProxyManager will never be a reason of crash or extreme memory consumption.
+//
+//**Question:** what will happen if bucket state will be lost in the GRID  because of split-brain, human mistake or pragmatically errors introduced by GRID vendor?
+//**Answer:** ProxyManager automatically detect this kind of situations and save bucket yet another time, to reconstruct bucket it uses provided configuration supplier.
+//Reconstructed bucket remembers nothing about previously consumed tokens, so limit can be exceeded in this kind of GRID failures.
+//
+//**Question:** should I always work with JCache through ProxyManager?
+//**Answer:** It depends. When you have deal with potentially huge and unpredictable amount of buckets, it is always better to use ProxyManager.
+//ProxyManager protects you from common performance pitfalls(like described in https://github.com/vladimir-bukhtoyarov/bucket4j/issues/26[this issue]).
+//But when you have deal with one or few buckets which well known at development time, then it would be better to avoid ProxyManager
+//and work directly with [GridBucket](https://github.com/vladimir-bukhtoyarov/bucket4j/blob/2.0/bucket4j-core/src/main/java/io/github/bucket4j/grid/GridBucket.java) as described in the next example.

asciidoc/src/main/docs/asciidoc/distributed/distributed-checklist.adoc

@@ -1,3 +1,4 @@
+[[distributed-checklist, Distributed usage checklist]]
 === Production checklist especially in the context of distributed systems
 Before using Bucket4j in clustered scenario you need to understand, agree and configure following points:
 

asciidoc/src/main/docs/asciidoc/distributed/distributed-index.adoc

@@ -1,5 +1,7 @@
 == Distributed facilities
 
+include::concepts.adoc[]
+
 include::jcache/jcache-usage.adoc[]
 
 include::jcache/hazelcast.adoc[]

asciidoc/src/main/docs/asciidoc/distributed/jcache/coherence.adoc

@@ -1,3 +1,4 @@
+[[bucket4j-coherence, Bucket4j-Coherence]]
 === Oracle Coherence integration
 Before use ``bucket4j-coherence`` module please read [bucket4j-jcache documentation](jcache-usage.md),
 because ``bucket4j-coherence`` is just a follow-up of ``bucket4j-jcache``.
@@ -23,7 +24,7 @@ To use ``bucket4j-coherence`` extension you need to add following dependency:
 ==== Example of Bucket instantiation
 [source, java]
 ----
-com.tangosol.net.NamedCache<K, GridBucketState> cache = ...;
+com.tangosol.net.NamedCache<K, byte[]> cache = ...;
 ...
 
 Bucket bucket = Bucket4j.extension(Coherence.class).builder()
@@ -34,7 +35,7 @@ Bucket bucket = Bucket4j.extension(Coherence.class).builder()
 ==== Example of ProxyManager instantiation
 [source, java]
 ----
-com.tangosol.net.NamedCache<K, GridBucketState> cache = ...;
+com.tangosol.net.NamedCache<K, byte[]> cache = ...;
 
 ProxyManager proxyManager = Bucket4j.extension(Coherence.class).proxyManagerForCache(cache);
 ----

asciidoc/src/main/docs/asciidoc/distributed/jcache/hazelcast.adoc

@@ -1,3 +1,4 @@
+[[bucket4j-hazelcast, Bucket4j-Hazelcast]]
 === Hazelcast integration
 Before use ``bucket4j-hazelcast`` module please read [bucket4j-jcache documentation](jcache-usage.md),
 because ``bucket4j-hazelcast`` is just a follow-up of ``bucket4j-jcache``.
@@ -37,7 +38,7 @@ just log issue to https://github.com/vladimir-bukhtoyarov/bucket4j/issues[bug tr
 ==== Example of Bucket instantiation
 [source, java]
 ----
-IMap<K, GridBucketState> map = ...;
+IMap<K, byte[]> map = ...;
 ...
 
 Bucket bucket = Bucket4j.extension(Hazelcast.class).builder()
@@ -48,7 +49,7 @@ Bucket bucket = Bucket4j.extension(Hazelcast.class).builder()
 ==== Example of ProxyManager instantiation
 [source, java]
 ----
-IMap<K, GridBucketState> map = ...;
+IMap<K, byte[]> map = ...;
 ...
 
 ProxyManager proxyManager = Bucket4j.extension(Hazelcast.class).proxyManagerForMap(map);
@@ -76,6 +77,6 @@ import io.github.bucket4j.grid.hazelcast.serialization.HazelcastSerializer;
     HazelcastSerializer.addCustomSerializers(serializationConfig, baseTypeIdNumber);
 ----
 
-## Known issues related with Docker and(or) SpringBoot
+==== Known issues related with Docker and(or) SpringBoot
 * [#186 HazelcastEntryProcessorAdapter class not found](https://github.com/vladimir-bukhtoyarov/bucket4j/discussions/186) - check file permissins inside your image.
 * [#182 HazelcastSerializationException with Hazelcast 4.2](https://github.com/vladimir-bukhtoyarov/bucket4j/issues/162) - properly setup classloader for Hazelcast client configuration.

asciidoc/src/main/docs/asciidoc/distributed/jcache/ignite.adoc

@@ -1,3 +1,4 @@
+[[bucket4j-ignite, Bucket4j-Ignite]]
 === Apache Ignite integration
 Before use ``bucket4j-ignite`` module please read [bucket4j-jcache documentation](jcache-usage.md),
 because ``bucket4j-ignite`` is just a follow-up of ``bucket4j-jcache``. 
@@ -25,7 +26,7 @@ To use ``bucket4j-ignite`` extension you need to add following dependency:
 ==== Example of Bucket instantiation
 [source, java]
 ----
-org.apache.ignite.IgniteCache<K, GridBucketState> cache = ...;
+org.apache.ignite.IgniteCache<K, byte[]> cache = ...;
 ...
 
 Bucket bucket = Bucket4j.extension(io.github.bucket4j.grid.ignite.Ignite.class).builder()
@@ -36,7 +37,7 @@ Bucket bucket = Bucket4j.extension(io.github.bucket4j.grid.ignite.Ignite.class).
 ==== Example of ProxyManager instantiation
 [source, java]
 ----
-org.apache.ignite.IgniteCache<K, GridBucketState> cache = ...;
+org.apache.ignite.IgniteCache<K, byte[]> cache = ...;
 ...
 
 ProxyManager proxyManager = Bucket4j.extension(io.github.bucket4j.grid.ignite.Ignite.class).proxyManagerForCache(cache);
@@ -45,7 +46,7 @@ ProxyManager proxyManager = Bucket4j.extension(io.github.bucket4j.grid.ignite.Ig
 ==== Example of Bucket instantiation via Thin Client
 [source, java]
 ----
-org.apache.ignite.client.ClientCache<K, GridBucketState> cache = ...;
+org.apache.ignite.client.ClientCache<K, byte[]> cache = ...;
 org.apache.ignite.client.ClientCompute clientCompute = ...;
 
 ...
@@ -58,7 +59,7 @@ Bucket bucket = Bucket4j.extension(io.github.bucket4j.grid.ignite.Ignite.class).
 ==== Example of ProxyManager instantiation via Thin Client
 [source, java]
 ----
-org.apache.ignite.client.ClientCache<K, GridBucketState> cache = ...;
+org.apache.ignite.client.ClientCache<K, bute[]> cache = ...;
 org.apache.ignite.client.ClientCompute clientCompute = ...;
 ...
 

asciidoc/src/main/docs/asciidoc/distributed/jcache/infinispan.adoc

@@ -1,3 +1,4 @@
+[[bucket4j-infinispan, Bucket4j-Infinispan]]
 === Infinispan integration
 Before use ``bucket4j-infinispan`` module please read [bucket4j-jcache documentation](jcache-usage.md),
 because ``bucket4j-infinispan`` is just a follow-up of ``bucket4j-jcache``.
@@ -74,7 +75,7 @@ all neccessary Protobuffers configs generated by ``Bucket4jProtobufContextInitia
 ==== Example of Bucket instantiation
 [source, java]
 ----
-org.infinispan.functional.FunctionalMap.ReadWriteMap<K, GridBucketState> map = ...;
+org.infinispan.functional.FunctionalMap.ReadWriteMap<K, byte[]> map = ...;
 ...
 Bucket bucket = Bucket4j.extension(Infinispan.class).builder()
                    .addLimit(Bandwidth.simple(1_000, Duration.ofMinutes(1)))
@@ -84,7 +85,7 @@ Bucket bucket = Bucket4j.extension(Infinispan.class).builder()
 ==== Example of ProxyManager instantiation
 [source, java]
 ----
-org.infinispan.functional.FunctionalMap.ReadWriteMap<K, GridBucketState> map = ...;
+org.infinispan.functional.FunctionalMap.ReadWriteMap<K, byte[]> map = ...;
 ...
 
 ProxyManager proxyManager = Bucket4j.extension(Infinispan.class).proxyManagerForMap(map);