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

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

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

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

1.0 SerialArray

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

SerialArrayクラスは、配列オブジェクトから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オブジェクトからインスタンスを作成するためのコンストラクタを提供します。 SerialClobオブジェクトが構築される前に、Clobオブジェクトによって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メンバー以外のすべてのメンバーを直列化しようとします。静的または一時フィールドは直列化できず、直列化を試行すると、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オブジェクト内の値の読取りを可能にする機能があります。メソッドwasNullは、最後に読み取られた値がSQL NULLであったかどうかを判断するために使用されます。

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

10.0 SQLOutputImpl

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

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

カスタム・マッピング

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オブジェクトを使用します。つまり、マップを指定しない場合、デフォルトとして接続の型マップが使用されます。

関連パッケージ

パッケージ

説明

javax.sql.rowset

JDBC RowSet実装用の標準インタフェースと基底クラスです。

javax.sql.rowset.spi

サード・パーティ・ベンダーが同期プロバイダの実装で使用する必要がある標準クラスおよびインタフェースです。
クラス

説明

SerialArray

Arrayオブジェクトの直列化バージョンであり、Javaプログラミング言語でのSQL ARRAY値のマッピングです。

SerialBlob

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

SerialClob

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

SerialDatalink

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

SerialException

BLOB, CLOB, STRUCT or ARRAYなどのSQL型やDATALINK and JAVAOBJECTなどのSQL型の、直列化または直列化復元時のエラーを示します。

SerialJavaObject

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

SerialRef

Refオブジェクトの直列化マッピングであり、Javaプログラミング言語でのSQL REF値のマッピングです。

SerialStruct

Javaプログラミング言語でのSQL構造型の直列化マッピングです。

SQLInputImpl

ユーザー定義型(UDT)のカスタム・マッピング用入力ストリームです。

SQLOutputImpl

カスタム・マップされたユーザー定義型(UDT)の属性をデータベースに再度書き込むための出力ストリームです。