OBKV-HBase Javaクライアントを使用したクラスタへの接続

OBKV-HBaseは、OBKV-HBaseクライアントを使用してOBKV-HBaseクラスタに接続し、HBase互換のAPIを用いてデータ処理を行うことをサポートします。既にネイティブなHBaseのデータ操作ロジックを利用する業務がある場合、OceanBaseデータベースクラスタをデプロイし、OBServerサーバー側でHBaseテーブルを作成し、OBKV-HBaseクライアントを通じてデータ操作を行うことができます。本記事では、クライアントの設定、OBServerへの接続、および基本的な追加・削除・変更・検索操作の方法について説明します。

OBKV-HBaseクライアント

OBKV-HBaseクライアントは、OBKV-Tableが提供する基本インターフェースを基盤とし、クライアント側でHBase互換のAPIをカプセル化しています。現在、HBase 1.x/2.x系の機能と互換性があります。

前提条件

OBKV-HBaseクライアントを使用してOBKV-HBaseクラスタに接続し、データ処理を実行する前に、以下の準備が整っていることを確認してください：

• OceanBaseクラスタがデプロイ済みであること。サポートされているデプロイメントプラン、デプロイ方法、および詳細なデプロイ手順については、デプロイの概要を参照してください。
• MySQLテナントが作成済みであること。テナント作成の詳細な操作については、テナントの作成を参照してください。
• データベースが作成済みであること。データベース作成の詳細な操作については、データベースの作成を参照してください。
• OBKV-HBaseデータテーブルが作成済みであること。OBKV-HBaseデータテーブル作成の詳細な操作については、データベーススキーマ設計を参照してください。

テーブル作成例：

-- まず、テーブルグループ htable1 を作成します
CREATE TABLEGROUP htable1;

-- htable1 テーブルグループにバインドされたテストテーブル htable1$family1 を作成します
CREATE TABLE htable1$family1 (
       K varbinary(1024),
       Q varbinary(256),
       T bigint,
       V varbinary(1048576) NOT NULL,
       PRIMARY KEY(K, Q, T))
       TABLEGROUP =  htable1;

ステップ1：クライアントの依存関係を追加する

OBKV-HBaseクライアントのJARパッケージ依存関係を、ローカルJavaプロジェクトのpom.xmlファイルに追加します（またはOBKV-HBase使用デモを参照してください）。OBKV-HBaseクライアントの互換性に関する説明については、OBKV-HBaseクライアント互換性を参照してください。

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

ステップ2：クライアント接続パラメータの設定

OBKV-HBaseは、パブリッククラウドとプライベートデプロイメントで構成が異なり、設定が必要なクライアント接続パラメータもそれぞれ異なります。OceanBaseクラスタをプライベートデプロイメントしている場合は、直接接続モードの設定を参照してください。パブリッククラウドのOBKVサービスを使用している場合は、クラウドモードを参照してください。

また、すべての構成パラメータは、以下の2つの方法で設定できます：

• HBaseConfigurationまたはConfigurationのsetメソッドを使用し、コード内でConnectionを初期化する前に設定します。
• OBKV-HBaseクライアントの設定ファイルで設定します。
  • org.apache.hadoop.hbase.HBaseConfigurationを使用して接続を初期化する場合は、hbase-site.xml ファイルで設定します。
  • org.apache.hadoop.conf.Configurationを使用して接続を初期化する場合は、core-site.xml ファイルで設定します。

直接接続モードの設定 (プライベートデプロイメント)

Configurationによる設定

## 現在のクラスタを以下のように仮定します
## ClusterName：obkvcluster
## TenantName：obkv
## DataBaseName: test
## UserName：root
## SYS_USER_NAME : sysroot

#### 必須項目
Configuration conf = new Configuration();

#### オプション項目
## 形式はuserName@tenantName#clusterNameです
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root@obkv#obkvcluster");

## fullUserNameで指定したユーザーがOceanBaseにアクセスするためのパスワードです
conf.set(HBASE_OCEANBASE_PASSWORD, "");
## obconfig serverからRSlistのURLを取得します。詳細については、Config URLの取得に関する内容を参照してください。
conf.set(HBASE_OCEANBASE_PARAM_URL, "");

## システムテナント内のユーザー名です。ルーティングテーブルにアクセスする権限があるのは、システムテナント内のユーザーのみです。
conf.set(HBASE_OCEANBASE_SYS_USER_NAME, "sysroot");

## システムテナント内のユーザーパスワードです。
conf.set(HBASE_OCEANBASE_SYS_PASSWORD, "");

#### オプション項目
## リクエストの実行タイムアウト時間（ビジネス特性に応じて選択）。単位はmsです。以下はタイムアウト時間1秒を示します。
conf.set("rpc.execute.timeout", "1000");

設定ファイルによる設定

<!--
現在のクラスタを以下のように仮定します
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>
    <!-- obconfig serverからRSlistのURLを取得します。詳細については、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>

Config URLの取得

以下の方法でConfig URLを取得できます：

• OCPからConfig URLを取得する

  OCPを使用している場合は、OCPからConfig URLを取得できます。

  1. OceanBase Cloud Platform（OCP）にログインします。

  2. 左側のナビゲーションバーでクラスタを選択し、下にスクロールしてクラスタリストを見つけます。

  3. アクセスするクラスタ名をクリックして開きます。

  4. クラスタの詳細ページでConfigURLパラメータを見つけます。このパラメータはクライアントの初期化時に設定する必要があります。

• obdを使用してConfig Serverをデプロイし、Config URLを取得する

  OCPを使用していない場合は、コマンドラインを使用してConfig Serverをデプロイする必要があり、ObRootServiceInfoUrlを取得する必要があります。

クラウドモードの設定（パブリッククラウド）

Configurationによる設定

## 現在のクラスタは以下のとおりです
## DataBaseName: test
## UserName：root

#### 必須項目
Configuration conf = new Configuration();

## データベースに作成したユーザー名。3要素の形式ではなく、ユーザー名のみを指定します
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");

## ユーザーパスワード
conf.set(HBASE_OCEANBASE_PASSWORD, "");

## ODP Addressの備考を参照
conf.set(HBASE_OCEANBASE_ODP_ADDR, "");

## OBKVのポートは3307（固定）
conf.setInt(HBASE_OCEANBASE_ODP_PORT, "3307");

## クラウドでODPモードを使用する場合（固定）
conf.setBoolean(HBASE_OCEANBASE_ODP_MODE, true);

## データベースのデータベース名
conf.set(HBASE_OCEANBASE_DATABASE, "test");

#### 任意項目
## リクエストの実行タイムアウト時間（業務特性に基づいて設定）
conf.set("rpc.execute.timeout", "1000");

設定ファイルによる設定

OBKV-HBaseクライアントの設定ファイルに対応するパラメータを設定します。

<!--
現在のクラスタは以下のとおりです
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>
        <!-- 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>

ODP Addressの取得

ODP Addressは以下の方法で取得できます。OceanBase Cloudテナントのダッシュボードに移動し、デプロイメント関係図を確認します。

OceanBaseクラスタへの接続

クライアント接続パラメータの設定が完了したら、クライアントの初期化を開始します。現在、ConnectionFactory、OHTableClient、OHTablePool の3つの方法がサポートされています。3つの違いは以下の通りです：

• ConnectionFactory（推奨）：ネイティブHBaseクライアントによる接続作成方法です。ConnectionFactoryを使用してHBaseのConnectionを作成し、異なるHBaseに対する操作を実行できます。Connection自体はスレッドセーフです。設定ファイルを用いてクライアントを初期化します。この方法では、コードを変更することなくHBase業務の移行が可能です。
• OHTableClient：非スレッドセーフです。内部には1つのOHTableハンドルしかなく、複数のスレッドが同じOHTableに同時にアクセスすると予測不可能な問題が発生する可能性があります（単一スレッドシナリオでの使用）。
• OHTablePool：OHTableプールです。必要な場合、プールから対応するテーブルのOHTableインスタンスを取得して使用します（マルチスレッドシナリオでの使用）。

ConnectionFactoryを使用した接続

1. HBase Connectionタイプの変更

   まず、ConnectionタイプをOBKV-HBaseに変更する必要があります。これは以下の2つの方法で変更できます。

   • 設定ファイルの変更

     設定ファイル内でHBase ConnectionタイプをOBKV-HBaseに変更します：

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

   • Configurationの直接設定

     HBase業務コード内のConfigurationを変更し、HBASE_CLIENT_CONNECTION_IMPL設定を追加します：

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

2. HBase接続の作成

   // configurationの設定。ここでは設定ファイルからも設定可能です。前のセクションを参照してください。ここでは詳細は説明しません。
   Configuration conf = new Configuration(); // パラメータの作成
   conf.set(xxx); // 各パラメータの設定
   Connection connection = ConnectionFactory.createConnection(c);
   TableName tableName = TableName.valueOf("your hbase table");
   Table hTable = connection.getTable(tableName);
   // 関連するロジックの実行
   hTable.close(); // hTableオブジェクトを閉じる
   connection.close(); // connectionオブジェクトを閉じる
   

OHTableを使用した接続

// configurationの設定。前のセクションを参照してください。ここでは詳細は説明しません。
Configuration conf = new Configuration(); // パラメータの作成
conf.set(xxx); // 各パラメータの設定
OHTableClient hTable = new OHTableClient("test1", conf); // hTableオブジェクトの作成
hTable.init(); // hTableの初期化
// 関連するロジックの実行
hTable.close(); // hTableオブジェクトを閉じる

OHTablePoolによる接続

OBKV-HBaseは、複数のTable操作インスタンスを管理するテーブルプールを提供します。Reusable、RoundRobin、ThreadLocalの3つの方式があり、テーブルプールをインスタンス化する際に指定できます。

使い方はHBaseのHTablePoolと同じです。特定のテーブルのHTableが必要な場合、pool.getTable("xx") を使用して対応するHTableを取得します。注意点は以下の通りです：

• パラメータの使用優先順位：テーブル専用パラメータ（例：pool.setOdpAddr()など）> Conf設定のパラメータ > デフォルトパラメータ。
• HTableの使用後はclose()を忘れずに行い、OHTableをプールに返却してください。try/finallyを使用してHTableを返すことを推奨します。

// configurationを設定します。詳細は前のセクションを参照してください。
Configuration conf = new Configuration(); // 設定パラメータの作成
conf.set(xxx);  // 各設定パラメータの設定

// maxSizeを初期化します。これはプール内の各テーブルの最大HTable参照数を表します。
int maxSize = 100;
// poolTypeを初期化します。Reusable / ThreadLocal / RoundRobinの3種類があります。ThreadLocalの使用を推奨します。
PoolMap.PoolType poolType = PoolMap.PoolType.ThreadLocal;
OHTablePool pool = new OHTablePool(conf, maxSize, poolType);
HTableInterface hTable = pool.getTable("test"); // 対応するテーブルのhTableを取得
// 関連ロジックの実行
hTable.close(); // tableをプールに返却

OBKV-HBaseクライアントのパラメータ

接続パラメータに加えて、Configurationを使用してその他のパラメータを設定することができます。以下の例では、クライアントのRPCタイムアウト時間を3秒に設定しています。

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

よく使われるパラメータの一覧

高度な構成パラメータ

上記の一般的なパラメータに加えて、OBKV-HBaseは以下の高度な機能の設定もサポートしています：

OHTableの設定

Configurationに加えて、OHTableのインターフェースを使用して個々のOHTableのパラメータを設定することもできます。

対応するHBase操作

上記の手順でクライアントを初期化した後、操作を実行できます。この章では、一部のOHTableインターフェース操作について説明します。より詳細なインターフェース情報については、OHTable.javaを参照してください。

OBKV-HBaseの使用デモについては、OBKV-HBase 使用 Demoを参照してください。

次のステップ

OBKV-HBaseクライアントをデプロイし、クラスタへの接続を確立すると、データに対する操作を実行できます。データ操作の具体的な例については、データ操作の例を参照してください。