Connect to a cluster by using the OBKV-HBase client

You can use the OBKV-HBase client to connect to an OBKV-HBase cluster and use HBase-compatible APIs to process data. If your business uses the data operation logic of native HBase, you can deploy an OceanBase cluster, create HBase tables on OBServer nodes, and perform data operations on the OBKV-HBase client. This topic describes how to configure the client, connect to an OceanBase cluster, and perform basic data add, delete, modify, and query operations.

OBKV-HBase client

The OBKV-HBase client encapsulates HBase-compatible APIs based on the basic APIs provided by OBKV-Table. At present, the OBKV-HBase client supports the features of HBase 0.94.

Preparations

Before you use the OBKV-HBase client to connect to an OBKV-HBase cluster for data processing, make sure that the following conditions are met:

• You have deployed an OceanBase cluster. For more information about the supported deployment solutions, deployment methods, and deployment procedure, see Deployment.
• You have created a MySQL tenant. For more information, see Create a tenant.
• You have created a database. For more information, see Create a database.
• You have created an OBKV-HBase data table. For more information, see Data model design.

Here is an example of table creation:

 CREATE TABLE test1$family1 (
       K varbinary(1024),
       Q varbinary(256),
       T bigint,
       V varbinary(1048576) NOT NULL,
       PRIMARY KEY(K, Q, T))
       TABLEGROUP =  htable1;

Step 1: Add client dependencies

Add the JAR dependency package of the OBKV-HBase client to the pom.xml file of the local Java project by referring to the following code. You can also refer to the OBKV-HBase client demo project.

<dependency>
    <groupId>com.oceanbase</groupId>
    <artifactId>obkv-hbase-client</artifactId>
    <version>0.1.4</version>
</dependency>

Step 2: Set client connection parameters

The deployment method of OBKV-HBase in a public cloud is different from that in a private environment. The client connection parameters are also different. If you deploy your OceanBase cluster in a private environment, see the configuration in direct connection mode. If you use the OBKV service in a public cloud, see the configuration in on-cloud mode.

Configuration in direct connection mode

## Assume that the information about the current cluster is as follows:
## ClusterName: obkvcluster
## TenantName: obkv
## DataBaseName: test
## UserName: root
## SYS_USER_NAME: sysroot

#### Required parameters
Configuration conf = new Configuration();

## The format is userName@tenantName#clusterName.
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root@obkv#obkvcluster");

## The password of the user specified by userName for accessing OceanBase Database.
conf.set(HBASE_OCEANBASE_PASSWORD, "");

## The URL for obtaining the RegionServer list from the Config Server of OceanBase Database. For more information, see the description about how to obtain the ConfigUrl.
conf.set(HBASE_OCEANBASE_PARAM_URL, "");

## The username of a user in the sys tenant. Only a user in the sys tenant can access the routing table.
conf.set(HBASE_OCEANBASE_SYS_USER_NAME, "sysroot");

## The password of the user in the sys tenant.
conf.set(HBASE_OCEANBASE_SYS_PASSWORD, "");         

#### Optional parameters
## The timeout period for executing a request, in ms, which is specified based on the business characteristics. In the following example, the timeout period is 1s.
conf.set("rpc.execute.timeout", "1000");             

You can obtain the ConfigUrl in either of the following ways:

• Obtain the ConfigUrl from OceanBase Cloud Platform (OCP)

  If OCP is used, you can perform the following steps to obtain the ConfigUrl from OCP:

  1. Log on to the OCP console.
  2. In the left-side navigation pane, select Clusters. Scroll down to the cluster list.
  3. Click the name of the target cluster.
  4. On the overview page of the cluster, find the ConfigUrl parameter. You need to configure this parameter during client initialization.

• Deploy the Config Server by using OceanBase Deployer (OBD) and obtain the ConfigUrl

  If OCP is not used, you need to deploy the Config Server by using the CLI and obtain ObRootServiceInfoUrl.

Configuration in on-cloud mode

## Assume that the information about the current cluster is as follows:
## DataBaseName: test
## UserName: root

#### Required parameters
Configuration conf = new Configuration();

## The username of a user created in the database. You can directly specify it without using the three-segment format.
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");    

## The password of the user.
conf.set(HBASE_OCEANBASE_PASSWORD, "");       

## For more information, see the description about how to obtain the ODP address in this topic.
conf.set(HBASE_OCEANBASE_ODP_ADDR, "");        

## The ODP port for OBKV is fixed to 3307.
conf.setInt(HBASE_OCEANBASE_ODP_PORT, "3307");     

## The ODP mode is always used in the case of on-cloud deployment.
conf.setBoolean(HBASE_OCEANBASE_ODP_MODE, true);  

## The name of the database.
conf.set(HBASE_OCEANBASE_DATABASE, "test");              

#### Optional parameters
## The timeout period for executing a request, which is configured based on the business characteristics.
conf.set("rpc.execute.timeout", "1000");             

To obtain the ODP address, log on to the OceanBase Cloud console and view the deployment diagram. The private address in the diagram is the ODP address.

Connect to the OceanBase cluster

After you configure the client connection parameters, you need to initialize the client by using OHTableClient or OHTablePool.

• OHTableClient: It is not thread-safe and has only one OHTable handle. Concurrent access from multiple threads to the same OHTable will lead to unexpected issues. OHTableClient applies to single-thread scenarios.
• OHTablePool: It is a pool of OHTables. The corresponding OHTable instance of a table is obtained from the pool as needed. OHTablePool applies to multi-thread scenarios.

Connect to the cluster by using an OHTable

// Set the Configuration. You can see the description in the previous section.
Configuration conf = new Configuration(); // Create a Configuration.
conf.set(xxx); // Set the parameters.
OHTableClient hTable = new OHTableClient("test1", conf); // Create an HTable object.
hTable.init(); // Initialize the HTable object.
// Execute related logic.
hTable.close(); // Close the HTable object.

Connect to the cluster by using an OHTablePool

OBKV-HBase provides OHTablePools for you to manage the operation instances of multiple tables in a pool. At present, three pool types are supported: Reusable, RoundRobin, and ThreadLocal. You can specify a type when you instantiate an OHTablePool.

Similar to using an HTablePool in HBase, you can use pool.getTable("xx") to obtain the corresponding HTable of a table from an OHTablePool. Take note of the following considerations:

• Priorities of parameters: dedicated table parameters such as pool.setOdpAddr() > parameters configured by using conf > default parameters.
• After you finish using an HTable, call the close() function to return the OHTable to the pool. We recommend that you use the try or finally method to return the HTable.

// Set the Configuration. You can see the description in the previous section.
Configuration conf = new Configuration(); // Create a Configuration.
conf.set(xxx); // Set the parameters.

// Initialize maxSize, which specifies the maximum number of HTable references for each table in the pool.
int maxSize = 100;
// Initialize poolType. Valid values are Reusable, ThreadLocal, and RoundRobin. The recommended value is ThreadLocal.
PoolMap.PoolType poolType = PoolMap.PoolType.ThreadLocal;
OHTablePool pool = new OHTablePool(conf, maxSize, poolType);
HTableInterface hTable = pool.getTable("test"); // Obtain the HTable of the corresponding table.
// Execute related logic.
hTable.close(); // Return the table to the pool.

OBKV-HBase client parameters

In addition to connection parameters, you can also set other parameters in a Configuration for the OBKV-HBase client. The following example sets the RPC timeout period to 3s for the client.

conf.set("rpc.execute.timeout", "3000");

Quick reference table of common parameters

OHTable parameters

In addition to using a Configuration, you can call OHTable APIs to set parameters for a single OHTable.

Supported HBase operations

After you initialize the client, you can perform HBase operations. This topic describes some of the OHTable APIs. For more information about APIs, see OHTable.java.

For the demo of OBKV-HBase, see OBKV-HBase client demo project.

What to do next

After you deploy the OBKV-HBase client and connect to the cluster, you can perform operations on data as needed. For data operation examples, see Data operation examples.