javax.sql.rowset.serial (Java SE 15 & JDK 15)

Javaプログラミング言語でのSQL型とデータ型の直列化可能マッピングを可能にするユーティリティ・クラスを提供します。

標準JDBC RowSet実装は、これらのユーティリティ・クラスを、未接続のRowSetオブジェクトを直列化するための補助として利用できます。未接続のRowSetを回線経由で別のVMに転送したり、アプリケーション内のレイヤー間で転送したりする場合に便利です。

1.0 SerialArray

Javaプログラミング言語でのSQL ARRAY値の直列化可能マッピングです。

SerialArrayクラスは、ArrayオブジェクトからSerialArrayインスタンスを作成するためのコンストラクタと、基底型とそのSQL名を取得するためのメソッドと、SerialArrayオブジェクトの一部または全部をコピーするためのメソッドを提供します。

2.0 SerialBlob

Javaプログラミング言語でのSQL BLOB値の直列化可能マッピングです。

SerialBlobクラスは、Blobオブジェクトからインスタンスを作成するためのコンストラクタを提供します。 Blobオブジェクトは、SerialBlobオブジェクトを構築する前に、クライアントにSQL BLOB値のデータを渡す必要があります。 SQL BLOB値のデータは、クライアント上で、Blob.getBytesメソッドによってバイト配列として生成されます。または、Blob.getBinaryStreamメソッドによって未解釈のバイト・ストリームとして生成されます。

SerialBlobメソッドは、SerialBlobオブジェクトをバイト配列またはストリームとしてコピーできます。また、SerialBlobオブジェクト内で、指定されたパターンのバイトまたはBlobオブジェクトを見つけることもできます。

3.0 SerialClob

Javaプログラミング言語でのSQL CLOB値の直列化可能マッピングです。

SerialClobクラスは、Clobオブジェクトからインスタンスを作成するためのコンストラクタを提供します。 Clobオブジェクトは、SerialClobオブジェクトを構築する前に、クライアントにSQL CLOB値のデータを渡す必要があります。 SQL CLOB値のデータは、クライアント上で、Unicode文字のストリームとして生成されます。

SerialClobメソッドは、SerialClobオブジェクトから部分文字列を取得したり、文字パターンの開始位置を検索したりする機能を提供します。

5.0 SerialDatalink

Javaプログラミング言語でのSQL DATALINK値の直列化可能マッピングです。 DATALINK値は、元のデータ・ソースが管理する基礎となるデータ・ソース外のファイルを参照します。

RowSet実装は、RowSet.getURL()メソッドを使って、外部データの操作用のjava.net.URLオブジェクトを取得できます。

    java.net.URL url = rowset.getURL(1);

6.0 SerialJavaObject

Javaプログラミング言語でのSQL JAVA_OBJECT値の直列化可能なマッピングです。 Javaオブジェクト・インスタンスがSerializableインタフェースを実装すると想定して、直列化処理を単純にラップします。

しかし、Javaオブジェクトが現在直列化可能でなく、直列化処理を実行できない場合、このクラスは、オブジェクト・インスタンスを直列化可能な状態にするため、staticメンバー以外のすべてのメンバーを直列化しようとします。 staticフィールドや一時フィールドは直列化できません。直列化しようとすると、SerialException がスローされます。

7.0 SerialRef

SQL REF型とJavaプログラミング言語間の直列化可能マッピングです。

SerialRefクラスは、Ref型からSerialRefインスタンスを作成するためのコンストラクタを提供し、Refオブジェクト型を取得および設定するためのメソッドを提供します。

8.0 SerialStruct

Javaプログラミング言語でのSQL構造型の直列化可能マッピングです。まだ直列化可能な状態にない属性は、直列化可能フォームにマップされます。属性そのものが構造型である場合も、その属性のまだ直列化可能な状態にないものは、直列化可能フォームにマップされます。

さらに、MapオブジェクトがいずれかのコンストラクタまたはgetAttributesメソッドに渡される場合、構造型は、Mapオブジェクトに指定されたマッピングに従って、カスタム・マップされます。
SerialStructクラスは、Structオブジェクトからインスタンスを作成するためのコンストラクタと、データベース内のSQL構造型のSQL型名を取得するためのメソッドと、その属性値を取得するためのメソッドを提供します。

9.0 SQLInputImpl

ユーザー定義型(UDT)のカスタム・マッピング用入力ストリームです。 SQLInputImplオブジェクトは、UDTの属性に相当する値のストリームを格納する入力ストリームです。このクラスは、カスタム・マッピングを持つSQL構造型またはSQL個別型でgetObjectメソッドが呼び出されるとき、背後でドライバによって使用されます。プログラマが直接SQLInputImplメソッドを呼び出すことはありません。

SQLInputImplクラスは、ResultSet取得メソッドと類似した一連のリーダー・メソッド・セットを提供します。これらのメソッドには、SQLInputImplオブジェクト内の値の読取りを可能にする機能があります。最終値がSQL NULLであったかどうかの確認には、wasNullメソッドが使用されます。

Mapオブジェクトを取るコンストラクタまたは取得メソッドが呼び出されると、JDBCドライバはSQLData.getSQLTypeメソッドを呼び出して、カスタム・マップされるUDTのSQL型を確定します。ドライバは、SQLInputImplのインスタンスを作成し、UDTの属性を移植します。続いて、入力ストリームをSQLData.readSQLメソッドに渡します。すると、このメソッドは、SQLInputImplメソッドを呼び出して、入力ストリームから属性を読み取ります。

10.0 SQLOutputImpl

カスタム・マップされたユーザー定義型(UDT)の属性をデータベースに再度書き込むための出力ストリームです。ドライバはこのインタフェースを内部で使用します。このインタフェースのメソッドがアプリケーション・プログラマによって直接呼び出されることはありません。

アプリケーションがPreparedStatement.setObjectメソッドを呼び出すと、ドライバはカスタム・マッピングを利用して、書き込まれる値がUDT型であるかどうかを確認します。 UDT型であれば、このUDTのSQLDataを実装するクラスのClassオブジェクトを格納する型マップ内にエントリが存在します。書き込まれる値がSQLDataのインスタンスである場合、ドライバはSQLOutputImplのインスタンスを作成し、SQLData.writeSQLメソッドに渡します。すると、writeSQLメソッドによって適切なSQLOutputImplライター・メソッドが呼び出され、SQLDataオブジェクトからSQLOutputImpl出力ストリームに、SQLユーザー定義型の表現としてデータが書き込まれます。

カスタム・マッピング

JDBC APIは、SQL構造型またはDISTINCT型とJavaプログラミング言語とのマッピング・メカニズムを提供します。通常、構造型はクラス、その属性はクラス内のフィールドにマップされます。 (DISTINCT型は1つの属性を持つと考えることができます。) しかし、ほかにも様々な可能性があり、マッピングの数に制限はありません。

プログラマは、SQLDataインタフェースを実装することにより、マッピングを定義します。たとえば、NAME、TITLE、PUBLISHERの各属性を持つ、AUTHORSというSQL構造型があるとします。このSQL構造型は、Authorsという名前のJavaクラスにマップされます。 Authorsクラスには、AUTHORSの各属性に対応するフィールド、name、title、publisherを持たせることができます。この場合、SQLDataの実装は次のようになります。

    public class Authors implements SQLData {
        public String name;
        public String title;
        public String publisher;

        private String sql_type;
        public String getSQLTypeName() {
            return sql_type;
        }

        public void readSQL(SQLInput stream, String type)
                                   throws SQLException  {
            sql_type = type;
            name = stream.readString();
            title = stream.readString();
            publisher = stream.readString();
        }

        public void writeSQL(SQLOutput stream) throws SQLException {
            stream.writeString(name);
            stream.writeString(title);
            stream.writeString(publisher);
        }
    }

java.util.Mapオブジェクトは、SQL構造型とAuthorsクラスのマッピングの関連付けに使用されています。次のコードの抜粋では、Mapオブジェクトを作成し、AUTHORSとAuthorsを関連付けるエントリを指定します。

     java.util.Map map = new java.util.HashMap();
     map.put("SCHEMA_NAME.AUTHORS", Class.forName("Authors");

Mapオブジェクトmapに、SQL構造型の完全指定名とAuthorsクラスのClassオブジェクトから成るエントリが追加されます。このエントリがメソッドに渡されることにより、ドライバは、AUTHORSとAuthorsのマッピングの関係を把握できます。

未接続のRowSetオブジェクトの場合、カスタム・マッピングを行うコンストラクタまたはメソッドにMapオブジェクトが渡された場合にのみ、カスタム・マッピングが行われます。接続済みRowSetオブジェクトの場合、データ・ソースとの接続が確保されているので、状況は異なります。カスタム・マッピングを行うメソッドが未接続のRowSetオブジェクトによって呼び出されると、このメソッドは、使用されるConnectionオブジェクトに関連付けられたMapオブジェクトを使用します。つまり、マップを指定しない場合、デフォルトとして接続の型マップが使用されます。

クラスのサマリー
クラス	説明
SerialArray	`Array`オブジェクトの直列化バージョンであり、Javaプログラミング言語でのSQL `ARRAY`値のマッピングです。
SerialBlob	Javaプログラミング言語でのSQL `BLOB`値の直列化マッピングです。
SerialClob	Javaプログラミング言語でのSQL `CLOB`値の直列化マッピングです。
SerialDatalink	Javaプログラミング言語でのSQL `DATALINK`値の直列化マッピングです。
SerialJavaObject	Javaプログラミング言語でのSQL `JAVA_OBJECT`値の直列化可能なマッピングです。
SerialRef	`Ref`オブジェクトの直列化マッピングであり、Javaプログラミング言語でのSQL `REF`値のマッピングです。
SerialStruct	Javaプログラミング言語でのSQL構造型の直列化マッピングです。
SQLInputImpl	ユーザー定義型(UDT)のカスタム・マッピング用入力ストリームです。
SQLOutputImpl	カスタム・マップされたユーザー定義型(UDT)の属性をデータベースに再度書き込むための出力ストリームです。

例外のサマリー
Exception	説明
SerialException	`BLOB, CLOB, STRUCT or ARRAY`などのSQL型や`DATALINK and JAVAOBJECT`などのSQL型の、直列化または直列化復元時のエラーを示します。

パッケージ javax.sql.rowset.serial