以下のトピックでは、PSQL における Java プログラミングの詳細や手順を提供します。

ここでは、PSQL Java インターフェイスのクラスについて説明します。

「ファクトリ」パターンを適用することにより、Driver、Timestamp、FieldDef および PsqlException を除く、ほとんどすべてのクラスは（単一または複数の）ほかのクラスのメソッドを通してのみ作成できます。クラスの説明で、パブリック コンストラクターが使用できない場合、ラベル Constructors の下にコンストラクターのリストは表示されません。

PSQL Java インターフェイスには、API のメソッドを呼び出すときに発生するエラー状態を処理する特別なクラス PsqlException があります。PsqlException は、 ava.lang.Exception を拡張します。PSQL Java クラスの個々のメソッドは PsqlException を返しますが、簡潔にするために以下の節はメソッド定義から省略されています。

図 2 に、すべてのクラスとクラス間の関係を示します。

PSQL Java インターフェイスのクラスは、以下の 3 つのグループに分類できます。

以下のクラスは、一般クラスのグループに属します。

これらのクラスは、密結合型データベースと疎結合型データベースの両方に使用できます。

以下のクラスは、Rowset ファミリ クラス グループに属します。

これらのクラスは PSQL データベースの辞書に見られるメタ データを使用するので、密結合型データベースにのみ適用できます。

これは、PSQL Java インターフェイスの低レベル部分です。このインターフェイス部分を使用する場合、ポジション ブロック、データ バッファーやその他 Btrieve API 特有のプログラミング要素を処理する必要があります。

以下のクラスは、Cursor ファミリ クラス グループに属します。

これらのクラスはメタ データを使用せず、従来の Btrieve オペレーション（BTRV メッセージなど）を直接サポートします。したがって、これらのクラスは一般に疎結合型データベースに適用されます。ただし、これらのクラスを使用して、DDF とデータとの密結合型データベースのテーブルを格納するデータ ファイルにアクセスすることもできます。（しかし、後者では「Rowset ファミリ」を使用する方が便利です。）

以下に、基本的な Java アプリケーションに関連する主なクラスとメソッドを示します。

PSQL Java Class Library リファレンス（Javadoc）に表示されるクラスとメソッドはほかにもありますが、これらはアプリケーションで最も頻繁に使用するクラスです。

Java インターフェイス クラスの構造はフラットです。これらのクラス間に継承関係はありません。

Driver は Session を確立します。Driver を使用して、必要な個数の Session オブジェクトのインスタンスを作成できます。KillallSessions メソッドはソケット接続、データベース接続、開いているファイル、システム リソースをクリーンアップするので、このメソッドを使用してアプリケーションを停止することもできます。

Sessions はドライバーとの接続を使用して、URI によるデータベースへの接続およびトランザクションの開始と終了を行うことができます。セッションごとに一意の Btrieve クライアント ID を取得します。アプリケーションが、特に複数の Btrieve クライアント ID を必要としない限り、通常はアプリケーション全体に対して 1 つの Session を使用することができます。Session および Btrieve クライアントは、Session.close() を呼び出すことによってリセットできます。詳細については、『PSQL Programmer's Guide』の Btrieve クライアントおよび、『PSQL User's Guide』のライセンス モデルを参照してください。

このクラスでインスタンスが作成されるオブジェクトは、データベース自体です。このクラスのメソッドを使用すれば、開発者は密結合型データベースの場合にテーブル名、テーブルなどを取得したりすることができます。疎結合型データベースの場合、開発者は Extended オペレーションなどの Btrieve に似た使い慣れた API でアクセスできます。

このクラスのインスタンスは、テーブルをオブジェクトとして表します。Table オブジェクトを使用して、行セットを作成し、テーブルに関するメタ データ情報を取得できます。

RowSet は、非常に重要なクラスです。このクラスは、関連するテーブルの行にアクセスする場合に使用します。また、このクラスのメソッドから行を挿入、更新および削除できます。

このクラスのインスタンスは、ベース テーブルから得られる一連の行を表します。ベース テーブルを見るもう 1 つの方法である RowSet は、物理的に格納されたテーブルから作成された仮想テーブル（ビュー）です。

行セットには、ベース テーブルのすべての行または行のサブセットを含めることができます。addFirstTerm、addAndTerm などの RowSetMetaData 内の多数のメソッドは、ベース テーブルからのどの行を行セットに組み込むかを決定する制限基準の条件を指定する場合に使用します。

行セットには、ベース行のすべての列を含めることも、ベース行から任意の個数の列を選択して含めることもできます。RowSet オブジェクトが Table.createRowSet で作成された場合、このオブジェクトは呼び出しで明示的または暗黙に指定された noColumns の値に従って初期化されます。noColumns に True を指定すると、行セットに列が含まれません。この場合、アプリケーションでは、RowSetMetaData.addColumns を呼び出すことによって、選択した列を行セットに含めることができます。noColumns に False を指定したり、引数として含めない場合、作成された RowSet にはテーブルのすべての列が含まれます。

通常、アプリケーションは行セットを開いたり閉じたりする必要はありません。関連するデータ ファイルは RowSet オブジェクトの作成時に開かれ、また、アプリケーションが RowSet.close を明示的に呼び出すか、あるいは、さらに高レベルの関連オブジェクト、たとえば、Table、Database などを閉じた結果としてデータ ファイルが閉じられます。

行セットの要素は、Row オブジェクトを通じてアクセスできます。行を取得する複数のオプションがあります。

行セットに関する重要な追加情報については、PSQL Java Class Library リファレンス（Javadoc）を参照してください。

このクラスのインスタンスは、RowSet 内の行の行バッファーを表します。Row クラスによって、行、および行内の列の値にアクセスできます。RowSet を使用して、行の取得、更新または削除を行ったり、挿入のための行を作成することができます。

このクラスには独自のメソッドがありませんが、Buffer から継承されたメソッドを使用して行バッファー内で列の値を取得または設定することができます。

以下の一連の手順は、アプリケーションまたはアプレットで通常使用されます。最初の 2 つの手順は、密結合型データベースでも、疎結合型データベースでも同じです。

ここで、ケース 1：アプリケーションが密結合型データベースのテーブルにアクセスする（Btrieve データベースは DDF を使用）またはケース 2： 疎結合型データベースのデータ ファイル、または密結合型データベースのテーブルを標準的な方法で格納するデータ ファイルにアプリケーションがアクセスするを選択してください。

以降では、これらの概要手順についてさらに詳しく説明します。

Java Btrieve アプリケーションを作成するには、まず以下の手順に従います。

環境が、環境設定の方法で説明しているように正しくセットアップされているかどうかを確認する必要があります。

また、psql.jar が CLASSPATH 環境変数内にあるかどうかを確認します。この手順は、インストール手順で既に実行しているはずです。PSQL Java インターフェイス クラス ライブラリ内のクラスにアクセスするには、Java ソース ファイルにパッケージをインポートする必要があります。

現在、PSQL Java インターフェイスのクラス ライブラリは、データベースとデータベース テーブルの作成をサポートしていません。これらの作業を実行するには PSQL Control Center を使用します。データベースのデータ辞書ファイル（DDF）およびデータ ファイルを作成したら、Java API クラスを使用してテーブルを追加してアクセスすることができます。

PSQL Control Center とテーブルの作成の詳細については、『PSQL User's Guide』を参照してください。

PSQL データベースに接続するには、エンジンに直接接続します。

ここで、「MyTable」 はデータベース テーブルの名前です。テーブル名では大文字と小文字を区別します。

また、データベースのテーブル名のリストを取得することもできます。

Table オブジェクトがあれば、TableMetaData オブジェクトからの列とインデックスに関する情報が得られます。

いくつかの例を以下に示します。

Table の行にアクセスするには、Table オブジェクトでしか作成できない RowSet オブジェクトが必要です。

同じテーブルから複数の RowSet オブジェクトを作成できます。RowSet オブジェクトは、テーブルの行を取得したり、新しい行を挿入したり、既存の行を削除および更新する場合に使用します。すべてのテーブルの行を繰り返し取得するには、RowSet オブジェクトを作成し、PsqlEOFException が発生するまで getNext() を呼び出します。

RowSet オブジェクトがあれば、RowSetMetaData から RowSet に関する情報を得ることができます。

詳細については、PSQL Java Class Library リファレンス（Javadoc）の RowSetMetaData クラスのメソッドを参照してください。

前に示したように、getNext メソッドを繰り返し呼び出し、行セットのすべての行を取得することができます。行セットの RowSetMetaData オブジェクトの direction プロパティを変更すれば、後方へ繰り返すことができます。

このプロパティを設定した後、getNext メソッドの動作は getPrevious になります。

Row オブジェクトは、Buffer クラスから多数の accessor メソッドまたは mutator メソッドを継承します。これらのメソッドで、Row オブジェクトのバッファーに対して列データを設定または取得できます。

ここで ColumnName は列 0 に対してデータ辞書で定義されている名前です。列名は大文字と小文字を区別します。

行セット内の行を制限またはフィルター処理するには、RowSetMetaData の addFirstTerm、addOrTerm および addAndTerm を使用する必要があります。たとえば、テーブルの最初の列に整数データが入っていて、その最初の列の値が 23 より大きい行をすべて取得する場合は、以下の手順に従います。

RowSetMetaData の addOrTerm および addAndTerm を使用して項を追加することができます。これらのメソッドを使用して、SQL の WHERE 句に似た、さらに複雑なフィルター処理条件を設定できます。

RowSetMetaData のメソッド addColumns と dropColumns を使用すれば、SQL の select ステートメントのような取得する列のサブセットを指定できます。デフォルトでは、noColumns パラメーターに True を設定して行セットが作成されない限り、行セットはすべての列データを取得します。

この場合、列は取得されません。その代わり、行セットを作成後、行の一部または全部を削除できます。

次に、対象の列のセットを行セットに追加できます。

行セットに列を追加するには、列名または列番号を使用できます。詳細については、PSQL Java Class Library リファレンス（Javadoc）の RowSetMetaData クラスの addColumns メソッドと dropColumns メソッドの項を参照してください。

列番号で行内の列データにアクセスする場合、列番号は addColumns メソッドと dropColumns メソッドによって生成される新しい順序の影響を受けるので、注意してください。たとえば、FirstName は最初は行セットの列番号 3 であった場合、すべての列を削除した後に LastName と FirstName を追加すると、FirstName の列番号は 1 になります。

定義されたインデックスを比較演算子と共に使用すれば、行を取得できます。たとえば、インデックス Last_Name が仮想テーブルの LastName 列で作成されている場合、以下のことを実行して Smith という LastName を持つ行を検索することができます。

インデックスが重複キー値を許可する場合は、比較演算子に適合する最初の行が返されます。返された行は現在の行になるので、インデックスに基づいて、行セットの getNext メソッドで次の論理行を取得できます。

テーブルの TableMetaData オブジェクトからインデックス名のリストを取得できます。

インデックスに名前を付けなくてもよいことに注意してください。その場合、代わりにインデックス番号を使用してください。インデックス番号はゼロから始まります。

次に示すように NCC（No-currency-change：カレンシー変更なし）が示されていない場合は、insertRow のように、新しく更新された行が行セットの現在の行になります。

トランザクションを使用すると、一連のオペレーションを 1 つのオペレーションに結合し、これをコミットまたは中止することができます。

Session クラスのトランザクション メソッドを使用して、一連のオペレーションをトランザクションにすることができます。

次に、トランザクションの例を示します。

トランザクションは「排他的」にすることも「並行」にすることもできます。トランザクションの詳細については、『PSQL Programmer's Guide』を参照してください。

setObject（）および getObject（）メソッドは、java io Serializable インターフェイスを実装する Java オブジェクトを格納および取得するのに使用できます。setBinaryStream（）および getBinaryStream（）メソッドは、Java InputStreams を使用したバイナリ データの格納および取得に使用できます。次のインターフェイスを持つ「単純な」Employee オブジェクトがあるとします。

また、C:\Employees\Java Duke\report.txt というファイルが存在し、読み込めるとします。この場合、Employee オブジェクトのインスタンスを作成し、さまざまなメソッドを使用して設定を行い、データベースの Employee_Data 列に格納することができます。さらに、そのファイルを Manager_Report 列に格納することもできます。

詳細については、バイナリ ラージ オブジェクトのサポートを参照してください。

ここでは、PSQL Java プログラマに役立つと思われる情報を示します。

Java クラス ライブラリにバイナリ ラージ オブジェクト（BLOB）処理のサポートが追加されました。BLOB は大きな（最大 4 ギガバイト）バイナリ データを表し、PSQL エンジンでは、LONGVARBINARY データ型として示されます。Java クラス ライブラリは、次のメソッドでこれらのデータ型をサポートします。これらは PSQL.database.Row クラスにあります。

ここで、columnNumber は、行バッファー内の列のシーケンス番号です。シーケンス番号はゼロから始まります。columnName は行バッファー内の列の名前です。object はデータベースに格納されるシリアル化可能な Java オブジェクトです。inStream は、データベースにバイトをストリームとして書き込むのに使用します。

上記のメソッドは 2 つのカテゴリに分割されます。1 つは、Serialized Java オブジェクトで動作するもので、もう 1 つは JavaInputStream オブジェクトで動作するものです。これらのカテゴリは、それぞれ次のセクションで詳しく説明します。次のセクションの例では、以下のスキーマで Employee という名前のテーブルが作成されていることを前提としてます。

table Employees (SS_Num ubigint primary key,
   Employee_Data longvarbinary not null,
   Manager_Report longvarbinary not null)

PSQL データベース エンジンでは、1 バイト整数は 0 ～ 255 の値を持つものと解釈されます。一方 Java では、このバイト型は符号付きで、-128 ～ 127 の値を持つものと解釈されます。

このような解釈の違いがあるので、データが誤って解釈されないように、コードから以下のプロシージャを実行する必要があります。

theOneByteInt = row.getByte("OneByte") & 0x00FF;

listCourses.add(theOneByteInt + " ");

Java データ型の詳細について、あるいはその他の Java 言語に関する情報は、http://java.sun.com/docs/books/tutorial/index.html を参照してください。

本 SDK コンポーネントに付属するサンプル データベース ファイルを使用して、Java アプリケーションを作成することができます。プログラミングの欠陥によりデータベース ファイルを壊してしまった場合は、SDK でインストールされたバックアップ ディレクトリからデータベース ファイルを復元できます。

Java API に付属の追加サンプルがあります。まず、本 SDK コンポーネントで提供する 2 つのテーブルの結合を実証するサンプル、次に DEMODATA データベースへ接続するサンプル、最後に、オブジェクトのシリアル化を実証するサンプルです。

デフォルトの場所にインストールしたという前提で、これらのサンプルは以下のディレクトリに置かれます。

PSQL ファイルのデフォルトの保存場所については、『Getting Started with PSQL』の PSQL ファイルはどこにインストールされますか？を参照してください。