This is an automated email from the ASF dual-hosted git repository.
hxd pushed a commit to branch test_container
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/test_container by this push:
new 95f73d3 add docs for ClsuterInfo API
95f73d3 is described below
commit 95f73d3c70d6e4a3efd30d57e114692ac0efc0ea
Author: xiangdong huang <[email protected]>
AuthorDate: Sat May 8 11:52:05 2021 +0800
add docs for ClsuterInfo API
---
docs/UserGuide/API/Programming-Java-Native-API.md | 98 ++++++++++++++++++++++
docs/UserGuide/Cluster/Cluster-Setup.md | 9 ++
.../UserGuide/API/Programming-Java-Native-API.md | 95 +++++++++++++++++++++
docs/zh/UserGuide/Cluster/Cluster-Setup.md | 9 ++
4 files changed, 211 insertions(+)
diff --git a/docs/UserGuide/API/Programming-Java-Native-API.md
b/docs/UserGuide/API/Programming-Java-Native-API.md
index dcc6958..2e7b465 100644
--- a/docs/UserGuide/API/Programming-Java-Native-API.md
+++ b/docs/UserGuide/API/Programming-Java-Native-API.md
@@ -406,3 +406,101 @@ void createDeviceTemplate
```
+### Cluster information related APIs (only works in the cluster mode)
+
+Cluster information related APIs allow users get the cluster info like where a
storage group will be
+partitioned to, the status of each node in the cluster.
+
+To use the APIs, add dependency in your pom file:
+
+```xml
+<dependencies>
+ <dependency>
+ <groupId>org.apache.iotdb</groupId>
+ <artifactId>iotdb-thrift-cluster</artifactId>
+ <version>0.13.0-SNAPSHOT</version>
+ </dependency>
+</dependencies>
+```
+
+How to open a connection:
+
+```java
+import org.apache.thrift.protocol.TBinaryProtocol;
+import org.apache.thrift.transport.TSocket;
+import org.apache.thrift.transport.TTransport;
+import org.apache.thrift.transport.TTransportException;
+import org.apache.iotdb.rpc.RpcTransportFactory;
+
+ public class CluserInfoClient {
+ TTransport transport;
+ ClusterInfoService.Client client;
+ public void connect() {
+ transport =
+ RpcTransportFactory.INSTANCE.getTransport(
+ new TSocket(
+ // the RPC address
+
IoTDBDescriptor.getInstance().getConfig().getRpcAddress(),
+ // the RPC port
+
ClusterDescriptor.getInstance().getConfig().getClusterRpcPort()));
+ try {
+ transport.open();
+ } catch (TTransportException e) {
+ Assert.fail(e.getMessage());
+ }
+ //get the client
+ client = new ClusterInfoService.Client(new
TBinaryProtocol(transport));
+ }
+ public void close() {
+ transport.close();
+ }
+ }
+```
+
+APIs in `ClusterInfoService.Client`:
+
+
+* Get the physical hash ring of the cluster:
+
+```java
+list<Node> getRing();
+```
+
+* Get data partition information of input path and time range:
+
+```java
+ /**
+ * @param path input path (should contains a Storage group name as its
prefix)
+ * @return the data partition info. If the time range only covers one data
partition, the the size
+ * of the list is one.
+ */
+ list<DataPartitionEntry> getDataPartition(1:string path, 2:long startTime,
3:long endTime);
+```
+
+* Get metadata partition information of input path:
+```java
+ /**
+ * @param path input path (should contains a Storage group name as its
prefix)
+ * @return metadata partition information
+ */
+ list<Node> getMetaPartition(1:string path);
+```
+
+* Get the status (alive or not) of all nodes:
+```java
+ /**
+ * @return key: node, value: live or not
+ */
+ map<Node, bool> getAllNodeStatus();
+```
+
+* get the raft group info (voteFor, term, etc..) of the connected node
+ (Notice that this API is rarely used by users):
+```java
+ /**
+ * @return A multi-line string with each line representing the total time
consumption, invocation
+ * number, and average time consumption.
+ */
+ string getInstrumentingInfo();
+```
+
diff --git a/docs/UserGuide/Cluster/Cluster-Setup.md
b/docs/UserGuide/Cluster/Cluster-Setup.md
index a0751fc..85dfccc 100644
--- a/docs/UserGuide/Cluster/Cluster-Setup.md
+++ b/docs/UserGuide/Cluster/Cluster-Setup.md
@@ -100,6 +100,15 @@ The configuration items described below are in the
`iotdb-cluster.properties` fi
|Default|40010|
|Effective| After restart system, shall NOT change after cluster is up|
+* cluster\_info\_public\_port
+
+|Name|cluster\_info\_public\_port|
+|:---:|:---|
+|Description|The port of RPC service that getting the cluster info (e.g., data
partition)|
+|Type|Int32|
+|Default|6567|
+|Effective| After restart system|
+
* open\_server\_rpc\_port
|Name|open\_server\_rpc\_port|
diff --git a/docs/zh/UserGuide/API/Programming-Java-Native-API.md
b/docs/zh/UserGuide/API/Programming-Java-Native-API.md
index fec6cfe..7a6471b 100644
--- a/docs/zh/UserGuide/API/Programming-Java-Native-API.md
+++ b/docs/zh/UserGuide/API/Programming-Java-Native-API.md
@@ -286,3 +286,98 @@ void testInsertTablet(Tablet tablet)
使用上述接口的示例代码在
```example/session/src/main/java/org/apache/iotdb/SessionExample.java```
+
+
+### 集群信息相关的接口 (仅在集群模式下可用)
+
+集群信息相关的接口允许用户获取如数据分区情况、节点是否当机等信息。
+要使用该API，需要增加依赖：
+
+```xml
+<dependencies>
+ <dependency>
+ <groupId>org.apache.iotdb</groupId>
+ <artifactId>iotdb-thrift-cluster</artifactId>
+ <version>0.13.0-SNAPSHOT</version>
+ </dependency>
+</dependencies>
+```
+
+建立连接与关闭连接的示例:
+
+```java
+import org.apache.thrift.protocol.TBinaryProtocol;
+import org.apache.thrift.transport.TSocket;
+import org.apache.thrift.transport.TTransport;
+import org.apache.thrift.transport.TTransportException;
+import org.apache.iotdb.rpc.RpcTransportFactory;
+
+ public class CluserInfoClient {
+ TTransport transport;
+ ClusterInfoService.Client client;
+ public void connect() {
+ transport =
+ RpcTransportFactory.INSTANCE.getTransport(
+ new TSocket(
+ // the RPC address
+
IoTDBDescriptor.getInstance().getConfig().getRpcAddress(),
+ // the RPC port
+
ClusterDescriptor.getInstance().getConfig().getClusterRpcPort()));
+ try {
+ transport.open();
+ } catch (TTransportException e) {
+ Assert.fail(e.getMessage());
+ }
+ //get the client
+ client = new ClusterInfoService.Client(new
TBinaryProtocol(transport));
+ }
+ public void close() {
+ transport.close();
+ }
+ }
+```
+
+API列表：
+
+* 获取集群中的各个节点的信息（构成哈希环）
+
+```java
+list<Node> getRing();
+```
+
+* 给定一个路径（应包括一个SG作为前缀）和起止时间，获取其覆盖的数据分区情况:
+
+```java
+ /**
+ * @param path input path (should contains a Storage group name as its
prefix)
+ * @return the data partition info. If the time range only covers one data
partition, the the size
+ * of the list is one.
+ */
+ list<DataPartitionEntry> getDataPartition(1:string path, 2:long startTime,
3:long endTime);
+```
+
+* 给定一个路径（应包括一个SG作为前缀），获取其被分到了哪个节点上:
+```java
+ /**
+ * @param path input path (should contains a Storage group name as its
prefix)
+ * @return metadata partition information
+ */
+ list<Node> getMetaPartition(1:string path);
+```
+
+* 获取所有节点的死活状态:
+```java
+ /**
+ * @return key: node, value: live or not
+ */
+ map<Node, bool> getAllNodeStatus();
+```
+
+* 获取当前连接节点的Raft组信息（投票编号等）（一般用户无需使用该接口）:
+```java
+ /**
+ * @return A multi-line string with each line representing the total time
consumption, invocation
+ * number, and average time consumption.
+ */
+ string getInstrumentingInfo();
+```
diff --git a/docs/zh/UserGuide/Cluster/Cluster-Setup.md
b/docs/zh/UserGuide/Cluster/Cluster-Setup.md
index bcceb89..420ee89 100644
--- a/docs/zh/UserGuide/Cluster/Cluster-Setup.md
+++ b/docs/zh/UserGuide/Cluster/Cluster-Setup.md
@@ -95,6 +95,15 @@ iotdb-engines.properties配置文件中的部分内容会不再生效：
|默认值|40010|
|改后生效方式|重启服务生效，集群建立后不可再修改|
+* cluster\_info\_public\_port
+
+|名字|cluster\_info\_public\_port|
+|:---:|:---|
+|描述|用于查看集群信息（如数据分区）的RPC服务的接口|
+|类型|Int32|
+|默认值|6567|
+|改后生效方式| 重启服务生效|
+
* open\_server\_rpc\_port
|名字|open\_server\_rpc\_port|
