add docs to configuring concurrency

commercetools/internal-docs/src/main/java/com/commercetools/docs/meta/ClientTuning.java

@@ -28,6 +28,21 @@
  * <p>The {@link com.commercetools.api.defaultconfig.ApiRootBuilder} has create methods which allow to pass a preconfigured HTTP client.</p>
  *
  * {@include.example example.ExamplesTest#proxy()}
+ *
+ * <h3 id=limit-requests>Limit concurrent requests</h3>
+ *
+ * <p>By default the client is initialized with a ForkJoinPool. The underlying HTTP client may have it's own configuration for
+ * limiting the maximum number of requests. By default the OkHttp and Apache AsyncHTTP client will be configured for 64 maximum
+ * requests.</p>
+ *
+ * <p>To adjust this instantiate the HTTP client in the client builder</p>
+ *
+ * {@include.example example.ExamplesTest#httpConcurrentLimitation()}
+ *
+ * <p>Another option is to use a middleware which limits the number of requests. The SDK provides for this use case
+ * the {@link io.vrap.rmf.base.client.http.QueueMiddleware}.</p>
+ *
+ * {@include.example example.ExamplesTest#queueConcurrentLimitation()}
  */
 public class ClientTuning {
 }

commercetools/internal-docs/src/test/java/example/ExamplesTest.java

@@ -37,6 +37,7 @@
 import io.vrap.rmf.base.client.ApiHttpResponse;
 import io.vrap.rmf.base.client.ModelBase;
 import io.vrap.rmf.base.client.VrapHttpClient;
+import io.vrap.rmf.base.client.http.QueueMiddleware;
 import io.vrap.rmf.base.client.oauth2.ClientCredentials;
 
 import org.apache.commons.lang3.tuple.Pair;
@@ -442,4 +443,21 @@ public void updateBodyBuilder() {
                 .plusActions(builder -> builder.setKeyBuilder().key("foo"))
                 .build();
     }
+
+    public void httpConcurrentLimitation() {
+        ApiRootBuilder.of(new CtOkHttp4Client(64, 64))
+                // ...
+                .build();
+
+        ApiRootBuilder.of(new CtApacheHttpClient(64, 64))
+                // ...
+                .build();
+    }
+
+    public void queueConcurrentLimitation() {
+        ApiRootBuilder.of()
+                // ...
+                .addMiddleware(new QueueMiddleware(64, Duration.ofSeconds(10)))
+                .build();
+    }
 }

rmf/rmf-java-base/src/main/java/io/vrap/rmf/base/client/http/QueueMiddleware.java

@@ -15,6 +15,11 @@
 import io.vrap.rmf.base.client.ApiHttpRequest;
 import io.vrap.rmf.base.client.ApiHttpResponse;
 
+/**
+ * Implementation of a Queue to limit the number of concurrent requests handled by the client
+ *
+ * @include.example io.vrap.rmf.base.client.QueueMiddlewareTest#queueConfiguration()
+ */
 public class QueueMiddleware implements Middleware, AutoCloseable {
 
     private final FailsafeExecutor<ApiHttpResponse<byte[]>> failsafeExecutor;

rmf/rmf-java-base/src/test/java/io/vrap/rmf/base/client/QueueMiddlewareTest.java

@@ -0,0 +1,14 @@
+package io.vrap.rmf.base.client;
+
+import io.vrap.rmf.base.client.http.QueueMiddleware;
+
+import java.time.Duration;
+
+public class QueueMiddlewareTest {
+
+    public void queueConfiguration() {
+        final ApiHttpClient build = ClientBuilder.of()
+                // ...
+                .addMiddleware(new QueueMiddleware(64, Duration.ofSeconds(10))).build();
+    }
+}