Connect to an instance by using the OBKV-HBase client

OceanBase Cloud allows you to connect to an Key-Value instance with HBase-compatible tenants by using the OBKV-HBase client and use HBase-compatible APIs to process data. If your business uses the native HBase data operation logic, you can deploy an OceanBase instance, 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 data 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 a Key-Value instance for data processing, make sure that you have completed the following preparations:

• You have created a Key-Value instance. For more information about supported deployment solutions, deployment methods, and detailed deployment operations, see Create an instance.
• You have created an HBase-compatible tenant. For more information about how to create a tenant, see Create a tenant.
• You have created a database.
• You have created an HBase-compatible table. For more information about how to create an HBase-compatible table, see Data model design.

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

OceanBase Database KV-HBase is deployed in different ways in public cloud and private deployment. Therefore, the client connection parameters to be set are different. If you have deployed OceanBase Database in private deployment, configure the parameters in direct mode. If you are using OceanBase Database KV-HBase in public cloud, configure the parameters in cloud mode.

Direct mode configuration (private deployment)

## Assume the current instance is as follows.
## InstanceName: obkvcluster
## TenantName: obkv
## DataBaseName: test
## UserName: root
## SYS_USER_NAME : sysroot

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

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

## The password of the username for accessing OceanBase Database.
conf.set(HBASE_OCEANBASE_PASSWORD, "");

## The URL from which you can obtain the list of Region Servers (RSs). 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 the permissions to access the routing table.
conf.set(HBASE_OCEANBASE_SYS_USER_NAME, "sysroot");

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

#### Optional parameters
## The timeout period for a request, in ms. The timeout period is 1 s in this example.
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 the OceanBase Cloud console.
  2. In the left-side navigation pane, select Instances.
  3. Click the name of the target instance.
  4. On the page that appears, find the ConfigURL parameter, which is required when you initialize a client.

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

  If you do not use OCP, you need to Use CLI to deploy a Config Server and obtain ObRootServiceInfoUrl.

Cloud mode configuration (public cloud)

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

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

## The username of the user to be created in the database. The username does not contain three parts.
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");

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

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

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

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

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

#### Optional parameters
## The timeout period for a request, in ms. The timeout period is 1 s in this example.
conf.set("rpc.execute.timeout", "1000");

You can obtain the ODP address in the topology section on the tenant overview page of the OceanBase Cloud Console.

Connect to an OceanBase instance

After you set the client connection parameters, you can initialize the client. Two methods are supported: OHTableClient and OHTablePool. The two methods differ in the following aspects:

• OHTableClient: Not thread-safe. It contains only one OHTable handle. If multiple threads access the same OHTable simultaneously, it may cause unpredictable issues. 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 the configuration parameters. For more information, see the previous section.
Configuration conf = new Configuration(); // Create the configuration parameters.
conf.set(xxx); // Set the configuration parameters.
OHTableClient hTable = new OHTableClient("test1", conf); // Create the hTable object.
hTable.init(); // Initialize the hTable.
// Perform the related operations.
hTable.close(); // Close the hTable object.

Connect by using OHTablePool

OceanBase KV-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 one of the modes when you instantiate the table pool.

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

• Parameter priority: Table-specific parameters (such as pool.setOdpAddr()) > Configuration parameters > Default parameters.
• After you use an HTable, make sure to close it and return the OHTable to the pool. We recommend that you use the try/finally method to return the HTable.

// Set the configuration parameters. For more information, see the previous section.
Configuration conf = new Configuration(); // Create the configuration parameters.
conf.set(xxx);  // Set the configuration parameters.

// Initialize maxSize, which specifies the maximum number of htable references per table in the pool.
int maxSize = 100;
// Initialize poolType, which specifies the pool mode. The supported modes are Reusable, ThreadLocal, and RoundRobin. We recommend that you use ThreadLocal.
PoolMap.PoolType poolType = PoolMap.PoolType.ThreadLocal;
OHTablePool pool = new OHTablePool(conf, maxSize, poolType);
HTableInterface hTable = pool.getTable("test"); // Obtain the hTable for the specified table.
// Perform the related operations.
hTable.close(); // Return the table to the pool.

OBKV-HBase Client parameters

Besides the connection parameters, we can also set some other configuration parameters by using the Configuration object, as the following example shows, where the RPC timeout for the client is set to 3 seconds.

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

Quick reference of common parameters

OHTable configuration

You can also set the configuration items of a single OHTable through the interface of OHTable:

Supported HBase operations

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

For more information about how to use OBKV-HBase, see OBKV-HBase Demo.

What to do next

• After you deploy the OBKV-HBase client and establish a connection with the instance, you can perform operations on the data.