[ignite] branch master updated: IGNITE-14128 Add documentation for Java thin client async API (#8753)

[mm...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mmuzaf pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git


The following commit(s) were added to refs/heads/master by this push:
     new f1cb467  IGNITE-14128 Add documentation for Java thin client async API (#8753)
f1cb467 is described below

commit f1cb467587bbf5993047453a9e7e462f79d900e9
Author: Pavel Tupitsyn <pt...@apache.org>
AuthorDate: Sat Feb 6 00:42:14 2021 +0300

    IGNITE-14128 Add documentation for Java thin client async API (#8753)
---
 .../java/org/apache/ignite/snippets/JavaThinClient.java   | 14 ++++++++++++++
 docs/_docs/thin-clients/java-thin-client.adoc             | 15 ++++++++++++++-
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/JavaThinClient.java b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/JavaThinClient.java
index a6bdf2b..42b6873 100644
--- a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/JavaThinClient.java
+++ b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/JavaThinClient.java
@@ -438,6 +438,20 @@ public class JavaThinClient {
         //end::client-services[]
     }
 
+    void asyncApi() throws Exception {
+        ClientConfiguration clientCfg = new ClientConfiguration().setAddresses("127.0.0.1:10800");
+        //tag::async-api[]
+        IgniteClient client = Ignition.startClient(clientCfg);
+        ClientCache<Integer, String> cache = client.getOrCreateCache("cache");
+
+        IgniteClientFuture<Void> putFut = cache.putAsync(1, "hello");
+        putFut.get(); // Blocking wait.
+
+        IgniteClientFuture<String> getFut = cache.getAsync(1);
+        getFut.thenAccept(val -> System.out.println(val)); // Non-blocking continuation.
+        //end::async-api[]
+    }
+
     private static class MyTask {
     }
 
diff --git a/docs/_docs/thin-clients/java-thin-client.adoc b/docs/_docs/thin-clients/java-thin-client.adoc
index e77cf9c..3975a6c 100644
--- a/docs/_docs/thin-clients/java-thin-client.adoc
+++ b/docs/_docs/thin-clients/java-thin-client.adoc
@@ -157,7 +157,7 @@ To start a transaction, obtain the `ClientTransactions` object from `IgniteClien
 `ClientTransactions` has a number of  `txStart(...)` methods, each of which starts a new transaction and returns an object (`ClientTransaction`) that represents the transaction.
 Use this object to commit or rollback the transaction.
 
-[source, ruby]
+[source, java]
 ----
 include::{sourceCodeFile}[tags=tx,indent=0]
 ----
@@ -342,3 +342,16 @@ Configure link:security/authentication[authentication on the cluster side] and p
 include::{sourceCodeFile}[tag=client-authentication,indent=0]
 -------------------------------------------------------------------------------
 
+
+== Async APIs
+
+Most network-bound thin client APIs have an async counterpart, for example, `ClientCache.get` and `ClientCache.getAsync`.
+
+[source, java]
+-------------------------------------------------------------------------------
+include::{sourceCodeFile}[tag=async-api,indent=0]
+-------------------------------------------------------------------------------
+
+* Async methods do not block the calling thread
+* Async methods return `IgniteClientFuture<T>` which is a combination of `Future<T>` and `CompletionStage<T>`.
+* Async continuations are executed using `ClientConfiguration.AsyncContinuationExecutor`, which defaults to `ForkJoinPool#commonPool()`. For example, `cache.getAsync(1).thenAccept(val -> System.out.println(val))` will execute the `println` call using a thread from the `commonPool`.
\ No newline at end of file