[GitHub] [ignite] artem-budnikov commented on a change in pull request #8131: IGNITE-13330 Java thin client documentation update

[GitBox <gi...@apache.org>]

artem-budnikov commented on a change in pull request #8131:
URL: https://github.com/apache/ignite/pull/8131#discussion_r469093563



##########
File path: docs/_docs/thin-clients/java-thin-client.adoc
##########
@@ -170,19 +181,96 @@ 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:
+
+* Get or set cluster state
+* Get a list of all cluster members
+* Create logical Cluster Groups
 
-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 by the client are duplicated. Consider the following code:
+== Cluster groups

Review comment:
       I think this section should be a subsection of "Cluster API" and should give an example of how to get a group of nodes for a specific purpose. Also, "Cluster groups" is an incorrect term. I know it's used in the API itself, but it should be "Node groups".  In fact, you don't have to use the term, you can simple say something like "here is how you can group nodes based on some characteristic (server nodes, clients, attributes, etc.)." and give an example.

##########
File path: docs/_docs/thin-clients/java-thin-client.adoc
##########
@@ -170,19 +181,96 @@ 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:
+
+* Get or set cluster state
+* Get a list of all cluster members
+* Create logical Cluster Groups
 
-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 by the client are duplicated. Consider the following code:
+== Cluster groups
 
+API to create logical groups of cluster 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.
 [source, java]
 -------------------------------------------------------------------------------
-include::{sourceCodeFile}[tag=results-to-map,indent=0]
+include::{sourceCodeFile}[tag=client-cluster-groups,indent=0]
 -------------------------------------------------------------------------------
 
+The `ClientCluster` instance (see link:#cluster-api[Cluster API]) it's a root cluster group, which includes all nodes in the cluster.
+
+////
+*TODO: fix link*
+////
+
+Refer to link:clustering/cluster-groups[Cluster groups] to get more information about logical nodes grouping.

Review comment:
       Please change the link: as of now, the cluster groups page is located here: distributed-computing/cluster-groups. I know this is not the best location, I'll deal with it later ( I'm thinking of creating the "Cluster API" section at the top level of the docs).




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org