Tsurugi Tsubakuro/Java

TsurugiのTsubakuro/Java（Java通信ライブラリー）のメモ。

概要

Tsubakuro/Javaは、JavaでTsurugiのDBにアクセスする通信ライブラリー。Java11以降で使用可能。

従来は「Tsubakuro」はJava版しか無かったが、Tsurugi 1.3.0でRust版Tsubakuroが提供されたため、「Tsubakuro」はクライアントライブラリーの総称という位置付けになった。[2025-03-17]
Java版を特に区別したい場合は「Tsubakuro/Java」と呼ぶ。

Tsurugi自体は（現在のところは）JDBCドライバーを提供しておらず、代わりにTsubakuro/JavaやIceaxeを使用する。

IceaxeにはSQLを実行する機能しか無いが、TsubakuroはSQLを実行する機能やKVSアクセスする機能の他にも色々な機能に対応している。
（ただしSQL実行に関してはIceaxeの方が高機能なので、速度面で多少劣っても構わないなら（Iceaxeは内部でTsubakuroを呼び出しており、Tsubakuroをラップしている分オーバーヘッドがある）、Iceaxeの方が便利）

詳細はTsurugiの書籍の第11章『Java通信ライブラリ（Tsubakuro）』を参照。

Tsubakuroを使ってアプリケーションを作る手順としては、まずSessionインスタンスを生成する。[2023-10-06]
その後、クライアント系クラス（SQLの場合はSqlClient、KVSの場合はKvsClient）にSessionをアタッチして使用する。

JavaでTsurugiサーバーと通信する機能はTsubakuroが提供しているが、通信データはprotocol bufferでシリアライズされているので、それが対応している言語であれば通信ライブラリーを作成することは可能。

ライブラリーのダウンロード方法

TsubakuroのjarファイルはMavenセントラルリポジトリー（tsubakuro）で公開されている。

build.gradle：

〜
repositories {
    mavenCentral()
}

dependencies {
    def tsubakuroVersion = '1.0.1'
    implementation "com.tsurugidb.tsubakuro:tsubakuro-session:${tsubakuroVersion}"
    implementation "com.tsurugidb.tsubakuro:tsubakuro-connector:${tsubakuroVersion}"
}

TsubakuroのバージョンとTsurugiサーバーのバージョン付けは一致しない。
2023/10/5時点のバージョンは、Tsubakuroが1.0.1で、Tsurugiサーバーは1.0.0-BETA1。

Tsubakuroのjarファイルは何種類かあるが、とりあえずtsubakuro-sessionとtsubakuro-connectorを指定しておけば、必要なライブラリーは依存関係にだいたい入っている。

• コーディングしてみるだけならtsubakuro-sessionだけあればいい。
• 実行するには、tsubakuro-ipc（IPC接続用）とtsubakuro-stream（TCP接続用）が必要。
• tsubakuro-connectorを指定すると、tsubakuro-ipcとtsubakuro-streamが入る。

実行時にtsubakuro-ipcやtsubakuro-streamが無いと、以下のような例外が発生する。

Exception in thread "main" java.util.NoSuchElementException: suitable connector is not found: tcp://localhost:12345
	at com.tsurugidb.tsubakuro.channel.common.connection.ConnectorHelper.create(ConnectorHelper.java:26)
	at com.tsurugidb.tsubakuro.channel.common.connection.Connector.create(Connector.java:25)
	at com.tsurugidb.tsubakuro.common.SessionBuilder.connect(SessionBuilder.java:50)

なお、エンドポイントのURIのスキーマにipc, tcp以外を指定した場合も同様の例外が発生する。