Connect to a cluster using the OBKV-HBase client

OBKV-HBase allows you to connect to an OBKV-HBase cluster using the OBKV-HBase client and perform data operations through HBase-compatible APIs. If your business currently uses native HBase data access logic, you can deploy an OceanBase cluster, create HBase tables on the OBServer server, and manage data using the OBKV-HBase client. This topic explains how to configure the client, connect to OBServer, and perform basic CRUD operations.

OBKV-HBase Java client

The OBKV-HBase client is built on top of the basic interfaces provided by OBKV-Table and wraps HBase-compatible APIs. It currently supports features from both HBase 1.x and 2.x versions.

Prerequisites

Before connecting to an OBKV-HBase cluster and processing data with the OBKV-HBase client, make sure you have completed the following steps:

• Deployed an OceanBase cluster. For supported deployment options, methods, and detailed instructions, see Deployment overview.
• Created a MySQL-compatible tenant. For detailed steps, see Create a tenant.
• Created a database. For detailed steps, see Create a database.
• Created OBKV-HBase data tables.

Example for creating tables:

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

-- Create a test table htable1$family1 associated with 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 to the pom.xml file of your local Java project (or refer to OBKV-HBase demo). For more information about the compatibility of the OBKV-HBase client, see OBKV-HBase client compatibility.

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

Step 2: Set client connection parameters

OBKV-HBase offers different deployment modes for public cloud and on-premises environments, and the client connection parameters you need to configure will vary accordingly. If you have deployed OceanBase Database on-premises, refer to the direct connection mode configuration. If you are using the OBKV service in a public cloud, refer to the cloud mode configuration.

You can set all parameters in either of the following ways:

• In your code, before initializing the connection, use the set method of HBaseConfiguration or Configuration.
• In the OBKV-HBase client configuration file:
  • If you use org.apache.hadoop.hbase.HBaseConfiguration to initialize the connection, set the parameters in the hbase-site.xml file.
  • If you use org.apache.hadoop.conf.Configuration to initialize the connection, set the parameters in the core-site.xml file.

Direct connection mode (on-premises deployment)

By using the Configuration class

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

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

#### Optional parameters
## Format: userName@tenantName#clusterName
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root@obkv#obkvcluster");

## The password of the userName for accessing OceanBase.
conf.set(HBASE_OCEANBASE_PASSWORD, "");
## The URL for obtaining the RS list from the obconfig server. For more information, see the section on obtaining the config URL.
conf.set(HBASE_OCEANBASE_PARAM_URL, "");

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

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

#### Optional parameters
## The timeout for executing a request (based on business characteristics). The unit is ms. The following example indicates a timeout of 1 second.
conf.set("rpc.execute.timeout", "1000");

By using a configuration file

<!--
Assume that the current cluster is as follows
ClusterName: obkvcluster
TenantName: obkv
DataBaseName: test
UserName: root
UserPassWord:
SYS_USER_NAME: sysroot
SYS_USER_PASSWD:
-->

<configuration>
  <property>
    <name>hbase.oceanbase.fullUserName</name>
    <value>root@obkv#obkvcluster</value>
  </property>
  <property>
    <name>hbase.oceanbase.password</name>
    <value></value>
  </property>
  <property>
    <!-- Obtain the RS list URL from the obconfig server. For details, see the section on retrieving the config URL. -->
    <name>hbase.oceanbase.paramURL</name>
    <value>your config url</value>
  </property>
  <property>
    <name>hbase.oceanbase.sysUserName</name>
    <value>sysroot</value>
  </property>
  <property>
    <name>hbase.oceanbase.sysPassword</name>
    <value></value>
  </property>
</configuration>

Obtain the config URL

You can obtain the config URL in the following ways:

• Obtain the config URL from OceanBase Cloud Platform (OCP)

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

  1. Log in to the OCP console.

  2. In the left-side navigation pane, click Clusters to go to the Clusters page.

  3. Click the name of the cluster that you want to access.

  4. On the details page of the cluster, find the ConfigURL parameter. You need to configure this parameter during client initialization.

• 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 the ObRootServiceInfoUrl.

Cloud mode configuration (public cloud)

By using Configuration

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

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

## The username of the user who is created in the database. The username does not need to be in the three-part format.
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");

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

## For details, see the remarks of ODP Address.
conf.set(HBASE_OCEANBASE_ODP_ADDR, "");

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

## Use ODP in cloud mode (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 request execution. You can configure this parameter based on your business requirements.
conf.set("rpc.execute.timeout", "1000");

By using a configuration file

Set the corresponding parameters in the OBKV-HBase client configuration file.

<!--
Assume that the current cluster is as follows
DataBaseName: test
UserName: root
-->
<configuration>
    <property>
        <name>hbase.oceanbase.fullUserName</name>
        <value>root</value>
    </property>
    <property>
        <name>hbase.oceanbase.password</name>
        <value></value>
    </property>
    <property>
        <!--For details, see the remarks of ODP Address.-->
        <name>hbase.oceanbase.odpAddr</name>
        <value></value>
    </property>
    <property>
        <name>hbase.oceanbase.odpPort</name>
        <value>3307</value>
    </property>
    <property>
        <name>hbase.oceanbase.odpMode</name>
        <value>true</value>
    </property>
    <property>
        <name>hbase.oceanbase.database</name>
        <value>test</value>
    </property>
</configuration>

Obtain the ODP address

You can obtain the OceanBase Database Proxy (ODP) address by logging in to the OB Cloud console and viewing the deployment relationship diagram.

Connect to the OceanBase cluster

After setting the client connection parameters, you can proceed to initialize the client. Currently, three methods are supported: ConnectionFactory, OHTableClient, and OHTablePool. The differences between them are as follows:

• ConnectionFactory (recommended): This is the native HBase client method for creating connections. Through ConnectionFactory, you can create an HBase Connection and operate on different HBase instances. The Connection itself is thread-safe. The client is initialized using configuration files. With this method, HBase applications can be migrated without code changes.
• OHTableClient: Not thread-safe and internally maintains only one OHTable handle. Concurrent access to the same OHTable from multiple threads may cause unpredictable issues (use in single-threaded scenarios).
• OHTablePool: An OHTable pool. You can obtain an OHTable instance for the required table from the pool as needed (use in multi-threaded scenarios).

Connect to OceanBase Database by using ConnectionFactory

1. Modify the HBase connection type

   First, you need to change the Connection type to the OBKV-HBase Connection type. You can do this in either of the following ways:

   • Modify the configuration file

     In the configuration file, set the HBase Connection type to OBKV-HBase's Connection type:

     <property>
         <name>hbase.connection.impl</name>
         <value>com.alipay.oceanbase.hbase.util.OHConnectionImpl</value>
     </property>
     

   • Set the Configuration directly

     In your HBase application code, update the Configuration and add the HBASE_CLIENT_CONNECTION_IMPL setting:

     import org.apache.hadoop.hbase.client;
     
     conf.set(ClusterConnection.HBASE_CLIENT_CONNECTION_IMPL,
              "com.alipay.oceanbase.hbase.util.OHConnectionImpl");
     

2. Create an HBase connection

   // Set the configuration. You can also set the configuration in the configuration file. For more information, see the previous section. This example does not expand on this.
   Configuration conf = new Configuration(); // Create a parameter
   conf.set(xxx); // Set each parameter
   Connection connection = ConnectionFactory.createConnection(c);
   TableName tableName = TableName.valueOf("your hbase table");
   Table hTable = connection.getTable(tableName);
   // Execute the relevant logic
   hTable.close(); // Close the htable object
   connection.close(); // Close the connection object
   

Connect to OceanBase Database by using OHTable

// Set the configuration. For more information, see the previous section. This example does not expand on this.
Configuration conf = new Configuration(); // Create a parameter
conf.set(xxx); // Set each parameter
OHTableClient hTable = new OHTableClient("test1", conf); // Create an htable object
hTable.init(); // Initialize the hTable
// Execute the relevant logic
hTable.close(); // Close the htable object

Connect to OceanBase Database by using OHTablePool

OBKV-HBase provides a table pool mechanism for managing operation instances of multiple tables. The resource pool currently supports three modes: Reusable, RoundRobin, and ThreadLocal. You can specify the desired mode when creating the table pool.

This works in the same way as HBase's HTablePool. To obtain an HTable for a specific table, use pool.getTable("xx"). Please note:

• Parameter precedence: Table-specific parameters (such as pool.setOdpAddr()) take priority over parameters set in Conf, which in turn take priority over default parameters.
• After using an HTable, remember to call close() to return the OHTable to the pool. It is recommended to use a try/finally block to ensure the HTable is returned.

// Set the configuration. For more information, see the previous section. This example does not expand on this.
Configuration conf = new Configuration(); // Create a parameter
conf.set(xxx);  // Set each parameter

// Initialize maxSize, which indicates the maximum number of htable references for each table in the pool.
int maxSize = 100;
// Initialize poolType, which can be Reusable, ThreadLocal, or 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 corresponding table
// Execute the relevant logic
hTable.close(); // Return the table to the pool

OBKV-HBase client parameters

In addition to connection parameters, you can set other parameters using Configuration. For example, the following sets the client RPC timeout to 3 seconds.

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

Quick reference for common parameters

OHTable configuration

You can also set the configuration of a single OHTable by using the OHTable interface:

Supported HBase operations

After you initialize the client as described in the preceding steps, you can perform operations. This chapter describes some operations of the OHTable interface. For more information about the OHTable interface, see OHTable.java.

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

What to do next

After you deploy the OBKV-HBase client and establish a connection to the cluster, you can perform operations on the data. For more information about data operations, see Data operations.