# Java客户端

> 此文档主要是TuGraph Java SDK的使用说明，需要注意的是TuGraph Java SDK将来不再更新维护，建议使用 [bolt客户端](./5.bolt-client.md)

## 1.编译java client代码
```shell
cd deps/tugraph-db-client-java
sh local_build.sh
```
## 2.使用示例

### 2.1.实例化client对象

添加maven依赖

```xml
<dependency>
    <groupId>com.antgroup.tugraph</groupId>
    <artifactId>tugraph-db-java-rpc-client</artifactId>
    <version>1.4.1</version>
</dependency>
```

引入依赖
```java
import com.antgroup.tugraph.TuGraphDbRpcClient;
```

#### 2.1.1.实例化单节点client对象
当以单节点模式启动server时，client按照如下格式进行实例化
```java
TuGraphDbRpcClient client = new TuGraphDbRpcClient("127.0.0.1:19099", "admin", "73@TuGraph");
```
```
public TuGraphDbRpcClient(String url, String user, String pass)
@param url: tugraph host looks like ip:port
@param user: login user name
@param password: login password
```

#### 2.1.2.实例化HA集群直连连接client对象
当服务器上部署的HA集群可以使用ha_conf中配置的网址直接连接时，client按照如下格式进行实例化。
```java
TuGraphDbRpcClient client = new TuGraphDbRpcClient("127.0.0.1:19099", "admin", "73@TuGraph");
```
```
public TuGraphDbRpcClient(String url, String user, String pass)
@param url: tugraph host looks like ip:port
@param user: login user name 
@param password: login password
```
用户只需要传入HA集群中的任意一个节点的url即可，client会根据server端返回的查询信息自动维护连接池，在HA集群横向扩容时
也不需要手动重启client。

#### 2.1.3.实例化HA集群间接连接client对象
当服务器上部署的HA集群不能使用ha_conf中配置的网址直接连接而必须使用间接网址（如阿里云公网网址）连接时，
client按照如下格式进行实例化
```java
List<String> urls = new ArrayList<>();
urls.add("189.33.97.23:9091");
urls.add("189.33.97.24:9091");
urls.add("189.33.97.25:9091");
TuGraphDbRpcClient client = new TuGraphDbRpcClient(urls, "admin", "73@TuGraph");
```
```
public TuGraphDbRpcClient(List<String> urls, String user, String password)
@param urls: tugraph host list
@param user: login user name
@param password: login password
```
因为用户连接的网址和server启动时配置的信息不同，不能通过向集群发请求的方式自动更新client连接池，所以需要在启动
client时手动传入所有集群中节点的网址，并在集群节点变更时手动重启client。

### 2.2.调用cypher
```java
    String res = client.callCypher("CALL db.edgeLabels()", "default", 10);
    log.info("db.edgeLabels() : " + res);
```
```
    @param cypher: inquire statement.
    @param graph: the graph to query.
    @param timeout: Maximum execution time, overruns will be interrupted
    @param url: (Optional) Node address of calling cypher
    @return: the result of cypher query execution
    public String callCypher(String cypher, String graph, double timeout, String url)
```
本接口支持在单机模式和HA模式下使用。其中，在HA模式下的client中，通过指定url参数可以定向向某个server发送读请求。
注：JAVA不支持默认参数，因此，JAVA中的默认参数是使用重载函数实现的。

### 2.3.向leader发送cypher请求
```java
    String res = client.callCypherToLeader("CALL db.edgeLabels()", "default", 10);
    log.info("db.edgeLabels() : " + res);
```
```
    @param cypher: inquire statement.
    @param graph: the graph to query.
    @param timeout: Maximum execution time, overruns will be interrupted
    @return: the result of cypher query execution
    public String callCypherToLeader(String cypher, String graph, double timeout)
```
本接口只支持在HA模式下使用，在HA模式下的client中，为防止向未同步数据的follower发送请求，
用户可以直接向leader发送请求，leader由集群选出。

### 2.4.调用GQL
```java
    String res = client.callGql("CALL db.edgeLabels()", "default", 10);
    log.info("db.edgeLabels() : " + res);
```
```
    @param gql: inquire statement.
    @param graph: the graph to query.
    @param timeout: Maximum execution time, overruns will be interrupted
    @param url: (Optional) Node address of calling GQL
    @return: the result of GQL query execution
    public String callGql(String gql, String graph, double timeout, String url)
```
本接口支持在单机模式和HA模式下使用。其中，在HA模式下的client中，通过指定url参数可以定向向某个server发送读请求。
注：JAVA不支持默认参数，因此，JAVA中的默认参数是使用重载函数实现的。

### 2.5.向leader发送GQL请求
```java
    String res = client.callGqlToLeader("CALL db.edgeLabels()", "default", 10);
    log.info("db.edgeLabels() : " + res);
```
```
    @param gql: inquire statement.
    @param graph: the graph to query.
    @param timeout: Maximum execution time, overruns will be interrupted
    @return: the result of cypher query execution
    public String callGqlToLeader(String cypher, String graph, double timeout)
```
本接口只支持在HA模式下使用，在HA模式下的client中，为防止向未同步数据的follower发送请求，
用户可以直接向leader发送请求，leader由集群选出。

### 2.6.调用存储过程
```java
    String result = client.callProcedure("CPP", "khop", kHopParamGen(), 1000, false, "default");
    log.info("testCallProcedure : " + result);
```
```
    @param procedureType: the procedure type, currently supported CPP and PY
    @param procedureName: procedure name
    @param param: the execution parameters
    @param procedureTimeOut: Maximum execution time, overruns will be interrupted
    @param inProcess: Running query or not
    @param graph: the graph to query
    @param jsonFormat: (Optional) Return format of calling stored procedure
    @param url: (Optional) Node address of calling procedure
    @return: the result of procedure execution
    public String callProcedure(String procedureType, String procedureName, String param, double procedureTimeOut,
            boolean inProcess, String graph, String url)
```
本接口支持在单机模式和HA模式下使用，默认以字符串格式直接返回存储过程的执行结果，指定jsonFormat为true可以返回json格式的执行结果。
其中，在HA模式下的client中，通过指定url参数可以定向向某个server发送读请求。

### 2.7.向leader调用存储过程
```java
    String result = client.callProcedureToLeader("CPP", "khop", kHopParamGen(), 1000, false, "default");
    log.info("testCallProcedureToLeader : " + result);
```
```
    @param procedureType: the procedure type, currently supported CPP and PY
    @param procedureName: procedure name
    @param param: the execution parameters
    @param procedureTimeOut: Maximum execution time, overruns will be interrupted
    @param inProcess: Running query or not
    @param graph: the graph to query
    @param jsonFormat: (Optional) Return format of calling stored procedure
    @return: the result of procedure execution
    public String callProcedureToLeader(String procedureType, String procedureName, String param, double procedureTimeOut,
            boolean inProcess, String graph)
```
本接口支持在HA模式下使用，默认以字符串格式直接返回存储过程的执行结果，指定jsonFormat为true可以返回json格式的执行结果。

### 2.8.加载存储过程
```java
    boolean result = client.loadProcedure("./test/procedure/khop.so", "CPP", "khop", "SO", "test loadprocedure", true, "v1", "default");
    log.info("loadProcedure : " + result);
```
```
    @param sourceFile: the source_file contain procedure code
    @param procedureType: the procedure type, currently supported CPP and PY
    @param procedureName: procedure name
    @param codeType: code type, currently supported PY, SO, CPP, ZIP
    @param procedureDescription: procedure description
    @param readOnly: procedure is read only or not
    @param version: The version of procedure
    @param graph: the graph to query.
    @return: the result of procedure execution
    public boolean loadProcedure(String sourceFile, String procedureType, String procedureName, String codeType,
                              String procedureDescription, boolean readOnly, String version, String graph) throws Exception
```
本接口支持在单机模式和HA模式下使用。其中，由于加载存储过程是写请求，HA模式下的client只能向leader发送加载存储过程请求。

### 2.9.列举存储过程
```java
    String result = client.listProcedures("CPP", "any", "default");
    log.info("listProcedures : " + result);
```
```
    @param procedureType: the procedure type, currently supported CPP and PY
    @param version: The version of procedure
    @param graph: the graph to query.
    @param url: (Optional) Node address of listing procedure
    @return: the list of procedure
    public String listProcedures(String procedureType, String version, String graph, String url) throws Exception
```
本接口支持在单机模式和HA模式下使用。其中，在HA模式下的client中，通过指定url参数可以定向向某个server发送读请求。

### 2.10.删除存储过程
```java
    String result = client.deleteProcedure("CPP", "sortstr", "default");
    log.info("loadProcedure : " + result);
```
```
    @param procedureType: the procedure type, currently supported CPP and PY
    @param procedureName: procedure name
    @param graph: the graph to query.
    @return: the result of procedure execution
    public boolean deleteProcedure(String procedureType, String procedureName, String graph) throws Exception
```
本接口支持在单机模式和HA模式下使用。其中，由于删除存储过程是写请求，HA模式下的client只能向leader发送删除存储过程请求。

### 2.11.从字节流中导入schema
```java
    boolean ret = client.importSchemaFromContent(schema, "default", 1000);
    log.info("importSchemaFromContent : " + ret);
```
```
    @param schema: the schema to be imported
    @param graph: the graph to query.
    @param timeout: Maximum execution time, overruns will be interrupted
    @return: the result of import schema
    public boolean importSchemaFromContent(String schema, String graph, double timeout) throws UnsupportedEncodingException 
```
本接口支持在单机模式和HA模式下使用。其中，由于导入schema是写请求，HA模式下的client只能向leader发送导入schema请求。

### 2.12.从字节流中导入点边数据
```java
    boolean ret = client.importDataFromContent(personDesc, person, ",", true, 16, "default", 1000);
    log.info("importDataFromContent : " + ret);
```
```
    @param desc: data format description
    @param data: the data to be imported
    @param delimiter: data separator
    @param continueOnError: whether to continue when importing data fails
    @param threadNums: maximum number of threads
    @param graph: the graph to query.
    @param timeout: Maximum execution time, overruns will be interrupted
    @return: the result of import data
    public boolean importDataFromContent(String desc, String data, String delimiter, boolean continueOnError,
            int threadNums, String graph, double timeout) throws UnsupportedEncodingException
```
本接口支持在单机模式和HA模式下使用。其中，由于导入点边数据是写请求，HA模式下的client只能向leader发送导入点边数据请求。

### 2.13.从文件中导入schema
```java
    boolean ret = client.importSchemaFromFile("./test/data/yago.conf", "default", 1000);
    log.info("importSchemaFromFile : " + ret);
```
```
    @param schemaFile: the schema_file contain schema
    @param graph: the graph to query.
    @param timeout: Maximum execution time, overruns will be interrupted
    @return: the result of import schema
    public boolean importSchemaFromFile(String schemaFile, String graph, double timeout) 
            throws UnsupportedEncodingException, IOException
```
本接口支持在单机模式和HA模式下使用。其中，由于导入schema是写请求，HA模式下的client只能向leader发送导入schema请求。

### 2.14.从文件中导入点边数据
```java
    boolean ret = client.importDataFromFile("./test/data/yago.conf", ",", true, 16, 0, "default", 1000000000);
    log.info("importDataFromFile : " + ret);
```
```
    @param confFile: data file contain format description and data
    @param delimiter: data separator
    @param continueOnError: whether to continue when importing data fails
    @param threadNums: maximum number of threads
    @param skipPackages: skip packages number
    @param graph: the graph to query.
    @param timeout: Maximum execution time, overruns will be interrupted
    @return: the result of import data
    public boolean importDataFromFile(String confFile, String delimiter, boolean continueOnError, int threadNums,
            int skipPackages, String graph, double timeout) throws IOException, UnsupportedEncodingException
```
本接口支持在单机模式和HA模式下使用。其中，由于导入点边数据是写请求，HA模式下的client只能向leader发送导入点边数据请求。