Connect to a cluster by using the OBKV-HBase client

OBKV-HBase allows you to connect to an OBKV-HBase cluster by using the OBKV-HBase client and process data with HBase-compatible APIs. If your business uses native HBase data operation logic, you can deploy an OceanBase cluster, create an HBase table on the OBServer, and use the OBKV-HBase client for data operations. This topic describes how to configure the client, connect to the OBServer, and perform basic CRUD operations.

OBKV-HBase client

The OBKV-HBase client provides basic interfaces based on OBKV-HBase and encapsulates HBase-compatible APIs. It is currently compatible with 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 you have completed the following preparations:

• You have created an OBKV cluster. For more information about supported deployment solutions, deployment methods, and detailed deployment operations, see Create an instance.
• You have created an OBKV tenant. For more information about how to create a tenant, see Create a tenant.
• You have created a database.
• You have created an OBKV-HBase table.

Here is an example:

-- First, create a table group named htable1.
CREATE TABLEGROUP htable1;

-- Create a test table named htable1$family1 that is bound to the htable1 table group.
 CREATE TABLE htable1$family1 (
       K varbinary(1024),
       Q varbinary(256),
       T bigint,
       V varbinary(1048576) NOT NULL,
       PRIMARY KEY(K, Q, T)) 
       TABLEGROUP =  htable1;

Step 1: Add the client dependency

Add the OBKV-HBase client JAR package dependency to the pom.xml file of your local Java project (or refer to OBKV-HBase Demo).

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

Step 2: Set client connection parameters

OBKV-HBase is deployed in different ways in public cloud and private deployment. Therefore, the client connection parameters to be set are different. If you deploy an OceanBase cluster in private deployment, configure the parameters in direct connection mode. If you use the public cloud OBKV service, configure the parameters in cloud mode.

Direct connection mode configuration (private deployment)

## Assume 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 userName in fullUserName for accessing OceanBase
conf.set(HBASE_OCEANBASE_PASSWORD, "");

## The URL for obtaining the RS list from the obconfig server. For more information, see Config URL.
conf.set(HBASE_OCEANBASE_PARAM_URL, "");

## The username in the sys tenant. Only users in the sys tenant have permissions to 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
## Request execution timeout (configure based on your business characteristics), in ms. The following example sets the timeout to 1s.
conf.set("rpc.execute.timeout", "1000");             

You can obtain the Config URL in the following ways:

• Obtain the Config URL from OCP

  If you use OCP, you can obtain the Config URL from OCP.

  1. Log in to OceanBase Cloud Platform.
  2. In the left-side navigation pane, select Instances and find Instance List.
  3. Click the name of the instance to access.
  4. On the instance details page, find the ConfigURL parameter, which is required when you initialize the client.

• Deploy a Config Server by using OBD and obtain the Config URL

  If you do not use OCP, you need to Deploy a Config Server by using the CLI and obtain ObRootServiceInfoUrl.

Cloud mode configuration (public cloud)

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

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

## The username of the newly created database user. Do not use the three-part format.
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");    

## User password
conf.set(HBASE_OCEANBASE_PASSWORD, "");       

## For more information, see the remarks on ODP Address
conf.set(HBASE_OCEANBASE_ODP_ADDR, "");        

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

## ODP mode is used in the cloud (fixed)
conf.setBoolean(HBASE_OCEANBASE_ODP_MODE, true);  

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

#### Optional parameters
## Request execution timeout (configure based on your business characteristics)
conf.set("rpc.execute.timeout", "1000");             

You can obtain the ODP address as follows: Go to the tenant workbench in OceanBase Cloud and view the deployment relationship diagram.

Connect to an OceanBase cluster

After you set the client connection parameters, you can initialize the client. Two methods are supported: OHTableClient and OHTablePool. The differences are as follows:

• OHTableClient: Not thread-safe. It contains only one OHTable handle. If multiple threads access the same OHTable simultaneously, unpredictable issues may occur. This method is suitable for single-threaded scenarios.
• OHTablePool: An OHTable pool. You can obtain an OHTable instance for a specific table from the pool when needed. This method is suitable for multi-threaded scenarios.

Connect by using OHTable

// Set configuration. For more information, see the previous section. Details are omitted here.
Configuration conf = new Configuration(); // Create configuration items
conf.set(xxx); // Set each configuration item
OHTableClient hTable = new OHTableClient("test1", conf); // Create an hTable object
hTable.init(); // Initialize hTable
// Perform related operations
hTable.close(); // Close the hTable object

Connect by using OHTablePool

OBKV-HBase manages multiple table operation instances by using the table pool mode. The resource pool supports three modes: Reusable, RoundRobin, and ThreadLocal. You can specify a mode when you instantiate the table pool.

The usage is similar to HTablePool in HBase. When you need an HTable for a specific table, use pool.getTable("xx") to obtain the corresponding HTable. Note the following:

• Parameter priority: table-specific parameters (such as pool.setOdpAddr()) > parameters set in Conf > default parameters.
• After you use an HTable, call close() to return the OHTable to the pool. We recommend using try/finally to return the HTable.

// Set configuration. For more information, see the previous section. Details are omitted here.
Configuration conf = new Configuration(); // Create configuration items
conf.set(xxx);  // Set each configuration item

// Initialize maxSize, which indicates the maximum number of hTable references per table in the pool
int maxSize = 100;
// Initialize poolType. Supported values: Reusable, ThreadLocal, and RoundRobin. ThreadLocal is recommended.
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
// Perform related operations
hTable.close(); // Return the table to the pool

OBKV-HBase client configuration items

In addition to connection parameters, you can set other configuration items through Configuration. The following example sets the RPC timeout of the client to 3s:

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

Quick reference of common configuration items

OHTable configuration

In addition to Configuration, you can set configuration items for a single OHTable through OHTable interfaces:

Supported HBase operations

After you initialize the client based on the preceding steps, you can perform operations. This topic describes some OHTable interface operations. For more interface information, see OHTable.java.

For OBKV-HBase usage demos, see OBKV-HBase Demo.

What to do next

• After you deploy the OBKV-HBase client and establish a connection with the cluster, you can perform data operations. For specific data operation examples, see data operation examples.