This is an automated email from the ASF dual-hosted git repository.
abudnikov pushed a commit to branch IGNITE-7595
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/IGNITE-7595 by this push:
new 5fc59fe IGNITE-13330 Java thin client documentation update (#8131)
5fc59fe is described below
commit 5fc59feab57822bd6d3297116ffc5be1fa019da8
Author: Aleksey Plekhanov <[email protected]>
AuthorDate: Mon Aug 17 13:09:17 2020 +0300
IGNITE-13330 Java thin client documentation update (#8131)
* IGNITE-13330 Java thin client documentation update
* IGNITE-13330 Java thin client features and examples added
* Review fixes
---
.../org/apache/ignite/snippets/JavaThinClient.java | 68 +++++++++++++
docs/_docs/thin-client-comparison.csv | 5 +
docs/_docs/thin-clients/java-thin-client.adoc | 106 +++++++++++++++++++--
3 files changed, 173 insertions(+), 6 deletions(-)
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 45525e2..329bbc6 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
@@ -323,4 +323,72 @@ public class JavaThinClient {
//end::system-views[]
}
+
+ void partitionAwareness() {
+ //tag::partition-awareness[]
+ ClientConfiguration cfg = new ClientConfiguration()
+ .setAddresses("node1_address:10800", "node2_address:10800",
"node3_address:10800")
+ .setPartitionAwareness(true);
+
+ try (IgniteClient client = Ignition.startClient(cfg)) {
+ ClientCache<Integer, String> cache = client.cache("myCache");
+ // Put, get or remove data from the cache...
+ } catch (ClientException e) {
+ System.err.println(e.getMessage());
+ }
+ //end::partition-awareness[]
+ }
+
+ void cientCluster() {
+ ClientConfiguration clientCfg = new
ClientConfiguration().setAddresses("127.0.0.1:10800");
+ //tag::client-cluster[]
+ try (IgniteClient client = Ignition.startClient(clientCfg)) {
+ ClientCluster clientCluster = client.cluster();
+ clientCluster.state(ClusterState.ACTIVE);
+ }
+ //end::client-cluster[]
+ }
+
+ void clientClusterGroups() {
+ ClientConfiguration clientCfg = new
ClientConfiguration().setAddresses("127.0.0.1:10800");
+ //tag::client-cluster-groups[]
+ try (IgniteClient client = Ignition.startClient(clientCfg)) {
+ ClientClusterGroup serversInDc1 =
client.cluster().forServers().forAttribute("dc", "dc1");
+ serversInDc1.nodes().forEach(n -> System.out.println("Node ID: " +
n.id()));
+ }
+ //end::client-cluster-groups[]
+ }
+
+ void clientCompute() {
+ //tag::client-compute-setup[]
+ ThinClientConfiguration thinClientCfg = new ThinClientConfiguration()
+ .setMaxActiveComputeTasksPerConnection(100);
+
+ ClientConnectorConfiguration clientConnectorCfg = new
ClientConnectorConfiguration()
+ .setThinClientConfiguration(thinClientCfg);
+
+ IgniteConfiguration igniteCfg = new IgniteConfiguration()
+ .setClientConnectorConfiguration(clientConnectorCfg);
+
+ Ignite ignite = Ignition.start(igniteCfg);
+ //end::client-compute-setup[]
+
+ ClientConfiguration clientCfg = new
ClientConfiguration().setAddresses("127.0.0.1:10800");
+ //tag::client-compute-task[]
+ try (IgniteClient client = Ignition.startClient(clientCfg)) {
+ // Suppose MyTask class is already deployed to the cluster
+ client.compute().execute(MyTask.class.getName(), "argument");
+ }
+ //end::client-compute-task[]
+ }
+
+ void clientServices() {
+ ClientConfiguration clientCfg = new
ClientConfiguration().setAddresses("127.0.0.1:10800");
+ //tag::client-services[]
+ try (IgniteClient client = Ignition.startClient(clientCfg)) {
+ // Suppose implementation of MyService interface is already
deployed to the cluster as a service with name "MyService"
+ client.services().serviceProxy("MyService",
MyService.class).myServiceMethod();
+ }
+ //end::client-services[]
+ }
}
diff --git a/docs/_docs/thin-client-comparison.csv
b/docs/_docs/thin-client-comparison.csv
index 535b5d5..ee2fe80 100644
--- a/docs/_docs/thin-client-comparison.csv
+++ b/docs/_docs/thin-client-comparison.csv
@@ -8,3 +8,8 @@ SSL/TLS,{yes},{yes},{yes},{yes},{yes},{yes}
Authentication,{yes},{yes},{yes},{yes},{yes},{yes}
Partition Awareness,{yes},{yes},{yes},{yes},{yes},No
Failover,{yes},No,{yes},{yes},{yes},{yes}
+Transactions,{yes},No,No,No,No,No
+Cluster API,{yes},{yes},No,No,No,No
+Cluster discovery,No,{yes},No,No,No,No
+Compute,{yes},{yes},No,No,No,No
+Service invocation,{yes},No,No,No,No,No
\ No newline at end of file
diff --git a/docs/_docs/thin-clients/java-thin-client.adoc
b/docs/_docs/thin-clients/java-thin-client.adoc
index 2a24446..adbc6f6 100644
--- a/docs/_docs/thin-clients/java-thin-client.adoc
+++ b/docs/_docs/thin-clients/java-thin-client.adoc
@@ -59,7 +59,18 @@ You can provide addresses of multiple nodes. In this case,
the thin client rando
include::{sourceCodeFile}[tag=connect-to-many-nodes,indent=0]
-------------------------------------------------------------------------------
-Note that the code above provides a failover mechanism in case of server node
failures but with a caveat that cache queries may return duplicate results.
Refer to the <<Handling Node Failures>> section for more information.
+Note that the code above provides a failover mechanism in case of server node
failures. Refer to the <<Handling Node Failures>> section for more information.
+
+== Partition Awareness
+
+include::includes/partition-awareness.adoc[]
+
+The following code sample illustrates how to use the partition awareness
feature with the java thin client.
+
+[source, java]
+----
+include::{sourceCodeFile}[tag=partition-awareness,indent=0]
+----
== Using Key-Value API
@@ -170,19 +181,102 @@ NOTE: The `getAll()` method retrieves the results from
the cursor and closes it.
Read more about using `SqlFieldsQuery` and SQL API in the
link:SQL/sql-api[Using SQL API] section.
-== Handling Exceptions
+== Cluster API
-=== Handling Node Failures
+Cluster functionality (APIs for accessing cluster and nodes) is provided via
the `ClientCluster` interface. You can get an instance of `ClientCluster` from
`IgniteClient` as follows:
+[source, java]
+-------------------------------------------------------------------------------
+include::{sourceCodeFile}[tag=client-cluster,indent=0]
+-------------------------------------------------------------------------------
-When you provide the addresses of multiple nodes in the client configuration,
the client automatically switches to the next node if the current connection
fails and retries any ongoing operation.
+Through the `ClientCluster` interface you can:
-In the case of atomic operations, failover to another node is transparent to
the user. However, if you execute a scan query or a SELECT query, it may
return duplicate results. This can happen because queries return data in pages,
and if the node that the client is connected to goes down while the client
retrieves the pages, the client connects to another node and executes the query
again. To avoid this, you have to write some code in your application that
checks if the entries returned [...]
+* Get or set cluster state
+* Get a list of all cluster members
+* Create logical groups of nodes
+=== Logical nodes grouping
+
+API to create logical groups of nodes within your cluster is provided by
`ClientClusterGroup` interface. Instance of this interface can be obtained from
a parent `ClientClusterGroup` instance using node-filtering methods.
+
+The `ClientCluster` instance it's a root cluster nodes group, which includes
all nodes in the cluster.
+
+Here is how you can use this API to get all server nodes in certain
data-center (assuming node attribute "dc" is set to bind node and data-center):
[source, java]
-------------------------------------------------------------------------------
-include::{sourceCodeFile}[tag=results-to-map,indent=0]
+include::{sourceCodeFile}[tag=client-cluster-groups,indent=0]
-------------------------------------------------------------------------------
+Refer to link:distributed-computing/cluster-groups[Cluster groups] to get more
information about logical nodes grouping.
+
+== Executing compute tasks
+
+The Java thin client has basic functionality to execute compute tasks. By
default this feature is disabled on server-side. To enable this functionality
server-side configuration property `maxActiveComputeTasksPerConnection` should
be set excplicitly to value more than 0:
+
+[tabs]
+--
+tab:XML[]
+[source,xml]
+----
+<bean class="org.apache.ignite.configuration.IgniteConfiguration"
id="ignite.cfg">
+ <property name="clientConnectorConfiguration">
+ <bean
class="org.apache.ignite.configuration.ClientConnectorConfiguration">
+ <property name="thinClientConfiguration">
+ <bean
class="org.apache.ignite.configuration.ThinClientConfiguration">
+ <property name="maxActiveComputeTasksPerConnection"
value="100" />
+ </bean>
+ </property>
+ </bean>
+ </property>
+</bean>
+----
+tab:Java[]
+[source,java]
+----
+include::{sourceCodeFile}[tag=client-compute-setup,indent=0]
+----
+--
+
+Compute tasks execution functionality provided by `ClientCompute` interface,
which can be obtained from `IgniteClient` instance.
+
+Currently, thin client only have an ability to run already deployed tasks by
task name. To run some custom task users should deploy classes related to this
task to the server manually.
+[source, java]
+-------------------------------------------------------------------------------
+include::{sourceCodeFile}[tag=client-compute-task,indent=0]
+-------------------------------------------------------------------------------
+
+Nodes set to execute compute tasks can be limited using cluster groups and
corresponding `IgniteClient.compute(ClientClusterGroup)` method.
+
+See link:distributed-computing/distributed-computing[distributed computing]
for more information about compute grid functionality.
+
+== Service invocation
+
+The Java thin client is able to invoke grid-managed services. API for this
functionality is provided by `ClientServices` interface, which can be obtained
from `IgniteClient` instance.
+
+Only already deployed to cluster services can be invoked, there is no
functionality to deploy services by thin clients.
+[source, java]
+-------------------------------------------------------------------------------
+include::{sourceCodeFile}[tag=client-services,indent=0]
+-------------------------------------------------------------------------------
+
+////
+*TODO: fix link*
+////
+
+See link:service-grid/service-grid[Service Grid] for more information about
grid-managed services.
+
+== Handling Exceptions
+
+=== Handling Node Failures
+
+When you provide the addresses of multiple nodes in the client configuration,
the client automatically switches to the next node if the current connection
fails and retries any ongoing operation.
+
+In the case of atomic operations, failover to another node is transparent to
the user. However, if you execute a scan query or a SELECT query, iteration
over query cursor may throw an `ClientConnectionException`. This can happen
because queries return data in pages, and if the node that the client is
connected to goes down while the client retrieves the pages, to keep query
result consistent exception is thrown.
+
+If explicit transaction is started, cache operations binded to this
transaction also can throw an `ClientException` in case of failed connection to
server node.
+
+User code should handle these exceptions and implement retry logic accordingly.
+
== Security
=== SSL/TLS
