The OBKV-Table Java client provides a rich set of APIs for accessing OceanBase AI Database. This topic describes how to initialize the OBKV-Table Java client and connect to a cluster.
Before you use the OBKV-Table client to connect to an OBKV-Table cluster for data processing, make sure that you have completed the preparatory work. For details, see Prepare for development with OBKV-Table.
Install the OBKV-Table Java SDK
To use the OBKV-Table Java SDK in a Maven project, add the corresponding dependency to the pom.xml file. Add the following content to the dependencies section of the file:
<dependency>
<groupId>com.oceanbase</groupId>
<artifactId>obkv-table-client</artifactId>
<version>1.2.12</version>
</dependency>
Note the following:
- The OBKV-Table Java SDK requires JDK 1.8 or later.
- Use the latest version of the JAR file whenever possible. Earlier versions may not support new servers.
- The version number here may not be the latest. You can refer to the published OBKV-Table versions on the Central Repository and replace the version number with the latest published version.
Initialize ObTableClient
ObTableClient is the client handle that the OBKV-Table Java SDK uses to access OceanBase AI Database. The initialization method varies between direct connection mode and ODP mode.
Direct connection mode
Parameter description
In direct connection mode, you need to set the following five parameters for ObTableClient:
- setParamURL(String paramURL)
- setFullUserName(String fullUserName)
- setPassword(String password)
- setSysUserName(String sysUserName)
- setSysPassword(String sysPassword)
The parameters are described as follows:
Parameter name |
Parameter format |
Parameter description |
Parameter example |
|---|---|---|---|
| paramURL | http://ip:port/services?Action=ObRootServiceInfo&ObCluster=clusterName&database=databaseName |
The URL of the parameters, that is, the Config URL described in Prepare for development with OBKV-Table. Note: In direct connection mode, you must specify the database to access in the paramURL parameter by appending &database=databaseName to paramURL. |
http://127.0.0.1:8080/services?Action=ObRootServiceInfo&ObCluster=obkv&database=obkv_table_db
|
| fullUserName | userName@tenantName#clusterName |
The user that accesses the database. It is a fully qualified username (a three-part username) consisting of the username, tenant name, and cluster name, separated by @ and #. |
test@obkv_table#obkv
|
| password | The password that the user uses to access the database, that is, the password corresponding to userName in the fullUserName parameter. |
||
| sysUserName | The username in the SYS tenant, that is, the user under the system tenant mentioned in Prepare for development with OBKV-Table. In direct connection mode, only users under the system tenant have the privilege to access the routing table. | ||
| sysPassword | The password for accessing the SYS tenant, that is, the password corresponding to sysUserName in the sysUserName parameter. |
Initialization example
// Assume the current cluster is as follows.
// Cluster name: obkv
// Tenant name: obkv_table
// Database name: obkv_table_db
// Username: test_user
// Password: admin123
// User in the sys tenant: test_sys_user
// Password of the user in the sys tenant: sys123
// Config URL: http://127.0.0.1:8080/services?Action=ObRootServiceInfo&ObCluster=obkv
String paramURL = "http://127.0.0.1:8080/services?Action=ObRootServiceInfo&ObCluster=obkv&database=obkv_table_db";
ObTableClient obkvHandle = new ObTableClient();
obkvHandle.setParamURL(paramURL);
obkvHandle.setFullUserName("test_user@obkv_table#obkv");
obkvHandle.setPassword("admin123");
obkvHandle.setSysUserName("test_sys_user");
obkvHandle.setSysPassword("sys123");
obkvHandle.init();
ODP mode
In ODP mode, you need to set the following six parameters for ObTableClient:
- setOdpMode(boolean odpMode)
- setOdpAddr(String odpAddr)
- setOdpPort(int odpPort)
- setFullUserName(String fullUserName)
- setPassword(String password)
- setDatabase(String database)
The parameters are described as follows:
Parameter name |
Parameter description |
Parameter example |
|---|---|---|
| odpMode | The ODP mode identifier. true indicates ODP mode, and false indicates direct connection mode. In ODP mode, it must be set to true. |
|
| odpAddr | The domain name or IP address of the ODP server. | |
| odpPort | The port of the ODP server. Note: On the cloud, you need to expose port 3307 to the public network through SLB. In other scenarios, the default port is 2885. |
|
| fullUserName | The fullUserName parameter specifies the username. Its format differs from that in direct connection mode and depends on the scenario.
|
test_user / test_user@obkv_table#obkv |
| password | The password that the user uses to access data. | admin123 |
| database | The name of the database that the user needs to access. |
Initialization example
// Assume the current cluster is as follows.
// Cluster name: obkv
// Tenant name: obkv_table
// Database name: obkv_table_db
// Username: test_user
// Password: admin123
// ODP address: 127.0.0.1
// ODP port: 3307
ObTableClient obkvHandle = new ObTableClient();
obkvHandle.setOdpMode(true);
obkvHandle.setOdpAddr("127.0.0.1");
obkvHandle.setOdpPort(3307);
obkvHandle.setDatabase("obkv_table_db");
obkvHandle.setFullUserName("test_user");
obkvHandle.setPassword("admin123");
obkvHandle.init();
What to do next
- For information about all the operations supported by OBKV-Table, see OBKV-Table operations.
- For information about all the data types supported by OBKV-Table, see Data types supported by OBKV-Table.
- For examples of data operations using the client, see Write data to OBKV-Table.
- You can view the connection configuration of the OBKV-Table client in the following views: