SQLXML でのプログラミング
このセクションでは、Microsoft SQL Server JDBC Driver Version 2.0 API のメソッドを使用し、SQLXML オブジェクトを介して、リレーショナル データベースに XML ドキュメントを格納したり、リレーショナル データベースから XML ドキュメントを取得したりする方法について説明します。
SQLXML オブジェクトの型についての情報や、SQLXML オブジェクトを使用するうえでの重要なガイドラインおよび制限事項の一覧も掲載されています。
SQLXML オブジェクトを使用した XML データの読み取りと書き込み
Microsoft SQL Server JDBC Driver Version 2.0 API のメソッドと SQLXML オブジェクトを使用して、XML データの読み取りと書き込みを行う方法は次のとおりです。
SQLXML オブジェクトを作成するには、SQLServerConnection クラスの createSQLXML メソッドを使用します。このメソッドで作成される SQLXML オブジェクトにはデータが一切含まれていないことに注意してください。xml データを SQLXML オブジェクトに追加するには、SQLXML インターフェイスに指定されているいずれかのメソッドを呼び出します (setResult、setCharacterStream、setBinaryStream、または setString)。
SQLXML オブジェクトそのものを取得するには、SQLServerResultSet クラスまたは SQLServerCallableStatement クラスの getSQLXML メソッドを使用します。
SQLXML オブジェクトから xml データを取得するには、SQLXML インターフェイスに指定されているいずれかのメソッドを呼び出します (getSource、getCharacterStream、getBinaryStream、または getString)。
SQLXML オブジェクト内の xml データを更新するには、SQLServerResultSet クラスの updateSQLXML メソッドを使用します。
SQLXML オブジェクトをデータベース テーブルの xml 型の列に格納するには、SQLServerPreparedStatement クラスまたは SQLServerCallableStatement クラスの setSQLXML メソッドを使用します。
以上に挙げた基本的な API タスクの使用例については、「SQLXML データ型のサンプル」のコード例を参照してください。
読み取り/書き込み可能な SQLXML オブジェクト
次の表は、JDBC API の setter、getter、および updater メソッドによってサポートされる SQLXML オブジェクトの種類を一覧にしたものです。この表の各列の意味は次のとおりです。
「メソッド名」列は、JDBC API でサポートされている getter、setter、および updater メソッドの一覧です。
「getter SQLXML オブジェクト」列は、SQLServerCallableStatement クラスの getSQLXML メソッドまたは SQLServerResultSet クラスの getSQLXML メソッドによって作成される SQLXML オブジェクトを表します。
「setter SQLXML オブジェクト」列は、SQLServerConnection クラスの createSQLXML メソッドによって作成される SQLXML オブジェクトを表します。以下の setter メソッドは、createSQLXML メソッドによって作成された SQLXML オブジェクトしか受け付けない点に注意してください。
| メソッド名 | getter SQLXML オブジェクト (読み取り可能) | setter SQLXML オブジェクト (書き込み可能) |
|---|---|---|
CallableStatement.setSQLXML() |
サポート対象外 |
サポート対象 |
CallableStatement.setObject() |
サポート対象外 |
サポート対象 |
PreparedStatement.setSQLXML() |
サポート対象外 |
サポート対象 |
PreparedStatement.setObject() |
サポート対象外 |
サポート対象 |
ResultSet.updateSQLXML() |
サポート対象外 |
サポート対象 |
ResultSet.updateObject() |
サポート対象外 |
サポート対象 |
ResultSet.getSQLXML() |
サポート対象 |
サポート対象外 |
CallableStatement.getSQLXML() |
サポート対象 |
サポート対象外 |
この表を見るとわかるように、setter SQLXML メソッドは、読み取り可能な SQLXML オブジェクトでは使用できません。同様に、getter メソッドを書き込み可能な SQLXML オブジェクトで使用することもできません。
アプリケーションから setObject メソッドを呼び出すときに、SQLXML オブジェクトとの組み合わせで、scale パラメータまたは length パラメータを指定した場合、これらのパラメータは無視されます。
SQLXML オブジェクトを使用する場合のガイドラインと制限
アプリケーションは SQLXML オブジェクトを使用して、データベースとの間で XML データの読み取りと書き込みを行うことができます。以下に、SQLXML オブジェクトを使用するうえでの特定の制限と指針を箇条書きでまとめました。
SQLXML オブジェクトの有効期間は、そのオブジェクトが作成されたトランザクションの期間内に限られます。
getter メソッドから受け取った SQLXML オブジェクトは、データの読み取りにしか使用できません。
接続オブジェクトによって作成された SQLXML オブジェクトは、データの書き込みにしか使用できません。
アプリケーションは、読み取り可能な SQLXML オブジェクトの getter メソッドを 1 つだけ呼び出してデータを読み取ることができます。getter メソッドを呼び出した後で、同じ SQLXML オブジェクトの他の getter メソッドまたは setter メソッドを呼び出そうとするとエラーになります。
アプリケーションは SQLXML オブジェクトの読み取りまたは書き込みが完了した後、その SQLXML オブジェクトに対して free メソッドのみを呼び出すことができます。ただし、基になる列またはパラメータが有効である限り、返されたストリームまたはソースを処理することは可能です。基になる列またはパラメータが無効になった場合、SQLXML オブジェクトに関連付けられていたストリームやソースは閉じられます。基になる列またはパラメータが無効になった時点で、ストリーム、SAX (Simple API for XML)、および StAX (Streaming API for XML) の getter の基となっているデータが利用できなくなります。
アプリケーションは、書き込み可能な SQLXML オブジェクトの setter メソッドを 1 つだけ呼び出すことができます。setter メソッドを呼び出した後で、同じ SQLXML オブジェクトの他の setter メソッドまたは getter メソッドを呼び出そうとするとエラーになります。
SQLXML オブジェクトに対してデータを設定するには、返されたオブジェクトの適切な setter メソッドや関数を使用する必要があります。
基になる列が null の場合、SQLServerCallableStatement クラスおよび SQLServerResultSet クラスの getSQLXML メソッドは、null データを返します。
setter オブジェクトは、そのオブジェクトが作成された接続の間、有効です。
アプリケーションから、SQLXML インターフェイスに定義されている setter メソッドを使用して null 値を設定することはできません。アプリケーションから、SQLXML インターフェイスに定義されている setter メソッドを使用して空の文字列 ("") を設定することはできます。null 値を設定するには、次のいずれかを呼び出す必要があります。
SQLServerCallableStatement クラスおよび SQLServerPreparedStatement クラスの setNull メソッド。
SQLServerCallableStatement クラスおよび SQLServerPreparedStatement クラスの setObject メソッド。
SQLServerCallableStatement クラスおよび SQLServerPreparedStatement クラスの setSQLXML メソッド (パラメータ値として null を指定)。
XML ドキュメントを扱う場合は、パフォーマンス上の理由から、Document Object Model (DOM) パーサーではなく、Simple API for XML (SAX) および Streaming API for XML (StAX) パーサーの使用をお勧めします。
XML パーサーは空の値を処理できません。ただし、SQL Server が介在することで、アプリケーションが、XML データ型のデータベース列から空の値を取得したり、空の値を格納したりできるようになっています。つまり、XML データを解析する際、基になる値が空である場合は、パーサーによって例外がスローされます。DOM 出力の場合、JDBC ドライバがその例外をキャッチして、エラーをスローします。SAX および Stax 出力の場合、エラーは直接パーサーから送られます。
アダプティブ バッファリングと SQLXML サポート
SQLXML オブジェクトから返されたバイナリ ストリームと文字ストリームは、アダプティブ バッファリング モードまたはフル バッファリング モードに従います。一方、XML パーサーがストリームではない場合、アダプティブとフルのいずれの設定にも従いません。アダプティブ バッファリングの詳細については、「アダプティブ バッファリングの使用」を参照してください。