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

OBKV-HBase は、OBKV-HBase クライアントを介して OBKV-HBase クラスタに接続し、HBase 互換の API を使用したデータ処理に対応しています。現在、ネイティブの HBase データ操作ロジックを使用している業務がある場合、OceanBase データベースクラスタをデプロイし、OBServer サーバー側で HBase Table を作成して、OBKV-HBase クライアント経由でデータ操作を行うことができます。本記事では、クライアントの設定、OBServer への接続、および基本的な CRUD 操作の実行方法について説明します。

OBKV-HBase クライアント

OBKV-HBase クライアントは、OBKV-HBase が提供する基本インターフェースに基づき、クライアント側に HBase 互換の API をカプセル化しており、現在 HBase 0.94 バージョンの機能と互換性があります。

準備作業

OBKV-HBase クライアントを使用して OBKV-HBase クラスタに接続し、データ処理を行う前に、以下の準備作業が完了していることを確認してください。

• OBKV クラスタが作成されていること。対応するデプロイプラン、デプロイメント方法、および詳細なデプロイメント操作については、クラスタの作成 をご参照ください。
• OBKV テナントが作成されていること。テナントの作成に関する詳細な操作については、テナントの作成 をご参照ください。
• データベースが作成されていること。
• 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使用デモ を参照してください）。

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

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

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

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

## 現在のクラスタが以下のようであると仮定します
## 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 内の userName が 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 で、以下はタイムアウト時間 1s を示します
conf.set("rpc.execute.timeout", "1000");

以下の方法を参考にして Config URL を取得できます。

• OCP から Config URL を取得する

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

1. OceanBase Cloud Platform にログインします。
2. 左側のナビゲーションペインで クラスタ を選択し、下にスクロールして クラスタリスト を見つけます。
3. アクセスするクラスタ名をクリックして開きます。
4. クラスタの詳細情報ページで ConfigURL パラメータを見つけます。このパラメータはクライアントの初期化時に設定する必要があります。

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

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

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

## クラスタを以下のように仮定します
## DataBaseName: test
## UserName：root

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

## データベースで新規作成されたユーザー名。3 段階形式ではなく、username を使用します
conf.set(HBASE_OCEANBASE_FULL_USER_NAME, "root");

## ユーザー Password
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);

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

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

以下の方法で ODP Address を取得できます。OceanBase Cloud のテナントワークベンチにアクセスし、デプロイメント関係図を確認します。

OceanBase クラスタへの接続

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

• OHTableClient：スレッドセーフではありません。内部に OHTable ハンドルが 1 つしかなく、マルチスレッドで同じ OHTable に同時にアクセスすると予期しない問題が発生する可能性があります（シングルスレッドシナリオで使用）。
• OHTablePool：OHTable プールです。必要なときにプールから対応するテーブルの OHTable インスタンスを取得して使用します（マルチスレッドシナリオで使用）。

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 の操作インスタンスを管理するための Table pool プーリングモードを提供しています。現在、リソースプールには Reusable、RoundRobin、ThreadLocal の 3 つの方式が含まれています。table pool のインスタンス化時に、使用するモードを指定できます。

使用方法は HBase の HTablePool と同様です。特定の Table の HTable が必要な場合は、pool.getTable("xx") を使用して対応する HTable を取得します。以下の点に注意してください。

• パラメータの使用優先度：Table 専用パラメータ（pool.setOdpAddr() など） > Conf で設定されたパラメータ > デフォルトパラメータ。
• HTable の使用後は必ず close() を呼び出し、OHTable を Pool に返却してください。try/finally 方式を使用して HTable を返却することをお勧めします。

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

// maxSize を初期化します。これは pool 内の各テーブルの最大 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(); // retrun table to the pool

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

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

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

よく使用されるパラメータのクイックリファレンス

OHTable の設定

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

対応する HBase 操作

上記の手順に従ってクライアントの初期化が完了すると、操作の実行を開始できます。本章では一部の OHTable インターフェース操作について説明します。インターフェースの詳細情報については、OHTable.java をご参照ください。

関連する OBKV-HBase 使用のデモについては、OBKV-HBase使用デモ をご参照ください。

次のステップ

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