SQLXML (Java Platform SE 7)

```
public interface SQLXML
```
SQL XML 型の JavaTM プログラミング言語でのマッピングです。XML は、XML 値をデータベーステーブルの行内に列の値として格納する組み込みの型です。デフォルトでは、ドライバは SQLXML オブジェクトをデータそのものではなく、XML データへの論理ポインタとして格納します。SQLXML オブジェクトは、それが生成されたトランザクションの期間中に有効です。
SQLXML インタフェースは、String、Reader または Writer、あるいは Stream として XML 値にアクセスするためのメソッドを提供します。XML 値は、Source からアクセスしたり、Result として設定したりすることができ、XML Parser API (DOM、SAX、StAX など)、XSLT 変換、および XPath 評価で使用できます。
ResultSet、CallableStatement、PreparedStatement の各インタフェースのメソッド (getSQLXML など) を使用すると、プログラマは XML 値にアクセスできます。さらにこのインタフェースは XML 値を更新するためのメソッドを備えています。
SQLXML インスタンスの XML 値は、次の式を使用して BinaryStream として取得できます。
```
   SQLXML sqlxml = resultSet.getSQLXML(column);
   InputStream binaryStream = sqlxml.getBinaryStream();
 
```
たとえば、DOM パーサーで XML 値を構文解析するには、次のようにします。
```
   DocumentBuilder parser = DocumentBuilderFactory.newInstance().newDocumentBuilder();
   Document result = parser.parse(binaryStream);
 
```
ハンドラに対する SAX パーサーで XML 値を構文解析するには、次のようにします。
```
   SAXParser parser = SAXParserFactory.newInstance().newSAXParser();
   parser.parse(binaryStream, myHandler);
 
```
StAX パーサーで XML 値を構文解析するには、次のようにします。
```
   XMLInputFactory factory = XMLInputFactory.newInstance();
   XMLStreamReader streamReader = factory.createXMLStreamReader(binaryStream);
 
```
データベースは XML の最適化表現を使用できるため、getSource() および setResult() を使用して値にアクセスすると、ストリーム表現への直列化や XML の構文解析を使用せずに、処理のパフォーマンスを向上させることができます。
たとえば DOM Document ノードを取得するには、次のようにします。
```
   DOMSource domSource = sqlxml.getSource(DOMSource.class);
   Document document = (Document) domSource.getNode();
 
```
DOM Document ノードの値を myNode に設定するには、次のようにします。
```
   DOMResult domResult = sqlxml.setResult(DOMResult.class);
   domResult.setNode(myNode);
 
```
SAX イベントをハンドラに送信するには、次のようにします。
```
   SAXSource saxSource = sqlxml.getSource(SAXSource.class);
   XMLReader xmlReader = saxSource.getXMLReader();
   xmlReader.setContentHandler(myHandler);
   xmlReader.parse(saxSource.getInputSource());
 
```
SAX イベントからの結果の値を設定するには、次のようにします。
```
   SAXResult saxResult = sqlxml.setResult(SAXResult.class);
   ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler();
   contentHandler.startDocument();
   // set the XML elements and attributes into the result
   contentHandler.endDocument();
 
```
StAX イベントを取得するには、次のようにします。
```
   StAXSource staxSource = sqlxml.getSource(StAXSource.class);
   XMLStreamReader streamReader = staxSource.getXMLStreamReader();
 
```
StAX イベントからの結果の値を設定するには、次のようにします。
```
   StAXResult staxResult = sqlxml.setResult(StAXResult.class);
   XMLStreamWriter streamWriter = staxResult.getXMLStreamWriter();
 
```
ファイル resultFile への xsltFile 出力で XSLT を使用して、XML 値の XSLT 変換を実行するには、次のようにします。
```
   File xsltFile = new File("a.xslt");
   File myFile = new File("result.xml");
   Transformer xslt = TransformerFactory.newInstance().newTransformer(new StreamSource(xsltFile));
   Source source = sqlxml.getSource(null);
   Result result = new StreamResult(myFile);
   xslt.transform(source, result);
 
```
XML 値の XPath 式を評価するには、次のようにします。
```
   XPath xpath = XPathFactory.newInstance().newXPath();
   DOMSource domSource = sqlxml.getSource(DOMSource.class);
   Document document = (Document) domSource.getNode();
   String expression = "/foo/@bar";
   String barValue = xpath.evaluate(expression, document);
 
```
XML 値を XSLT 変換の結果に設定するには、次のようにします。
```
   File sourceFile = new File("source.xml");
   Transformer xslt = TransformerFactory.newInstance().newTransformer(new StreamSource(xsltFile));
   Source streamSource = new StreamSource(sourceFile);
   Result result = sqlxml.setResult(null);
   xslt.transform(streamSource, result);
 
```
newTransformer() を呼び出すことで指定される恒等変換を使用して、任意の Source を Result に変換できます。
```
   Transformer identity = TransformerFactory.newInstance().newTransformer();
   Source source = sqlxml.getSource(null);
   File myFile = new File("result.xml");
   Result result = new StreamResult(myFile);
   identity.transform(source, result);
 
```
Source の内容を標準出力に書き込むには、次のようにします。
```
   Transformer identity = TransformerFactory.newInstance().newTransformer();
   Source source = sqlxml.getSource(null);
   Result result = new StreamResult(System.out);
   identity.transform(source, result);
 
```
DOMResult から DOMSource を作成するには、次のようにします。
```
    DOMSource domSource = new DOMSource(domResult.getNode());
 
```
不完全な XML 値や無効な XML 値が原因で、設定時に SQLException が発生したり、execute() の発生時にこの例外が発生したりすることがあります。すべてのストリームは、execute() の発生前にクローズする必要があります。そうでないと、SQLException がスローされます。
SQLXML オブジェクトに対する XML 値の読み書きは、多くても 1 回発生する可能性があります。読み込み可能および読み込み不可能の概念的状態により、いずれかの読み込み API で値を返すか例外をスローするかが判断されます。書き込み可能および書き込み不可能の概念的状態により、いずれかの書き込み API で値を設定するか例外をスローするかが判断されます。
free() または読み込み API (getBinaryStream()、getCharacterStream()、getSource()、getString()) が呼び出されると、状態は読み込み可能から読み込み不可能に移ります。実装によっては、このときに状態を書き込み不可能に変更することもできます。
free() または書き込み API (setBinaryStream()、setCharacterStream()、setResult()、setString()) が呼び出されると、状態は書き込み可能から書き込み不可能に移ります。実装によっては、このときに状態を読み込み不可能に変更することもできます。

JDBC ドライバがそのデータ型をサポートする場合は、SQLXML インタフェースのすべてのメソッドが完全に実装される必要があります。
導入されたバージョン:

1.6

関連項目:
javax.xml.parsers, javax.xml.stream, javax.xml.transform, javax.xml.xpath

メソッドのサマリー

メソッド
修飾子と型	メソッドと説明
`void`	`free()` このメソッドはこのオブジェクトをクローズして、このオブジェクトが保持していたリソースを解放します。
`InputStream`	`getBinaryStream()` この SQLXML インスタンスによって指定された XML 値をストリームとして取り出します。
`Reader`	`getCharacterStream()` この SQLXML インスタンスによって指定された XML 値を java.io.Reader オブジェクトとして取得します。
`<T extends Source> T`	`getSource(Class<T> sourceClass)` この SQLXML インスタンスによって指定された XML 値を読み込むための Source を返します。
`String`	`getString()` この SQLXML インスタンスによって指定された XML 値の文字列表現を返します。
`OutputStream`	`setBinaryStream()` この SQLXML インスタンスが表す XML 値への書き込みに使用するストリームを取得します。
`Writer`	`setCharacterStream()` この SQLXML インスタンスが表す XML 値への書き込みに使用するストリームを取得します。
`<T extends Result> T`	`setResult(Class<T> resultClass)` この SQLXML インスタンスによって指定された XML 値を設定するための Result を返します。
`void`	`setString(String value)` この SQLXML インスタンスによって指定された XML 値を指定された String 表現に設定します。

- メソッドの詳細
  - free
```
void free()
          throws SQLException
```
    このメソッドはこのオブジェクトをクローズして、このオブジェクトが保持していたリソースを解放します。このメソッドが呼び出されると、SQL XML オブジェクトは無効になり、読み込み可能にも書き込み可能にもなりません。 free が呼び出されると、free 以外のメソッドを呼び出そうとしても、SQLException がスローされます。free を複数回呼び出した場合、2 回目以降の free 呼び出しは何も行わないものとして扱われます。
    
    例外:
    
    SQLException - XML 値を解放するときにエラーが発生した場合。
    
    SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
    導入されたバージョン:
    
    1.6
  - getBinaryStream
```
InputStream getBinaryStream()
                            throws SQLException
```
    この SQLXML インスタンスによって指定された XML 値をストリームとして取り出します。入力ストリームのバイトは、XML 1.0 仕様の付録 F に従って解釈されます。ResultSet の指定された列が java.sql.Types 型の SQLXML である場合、このメソッドの動作は ResultSet.getBinaryStream() と同じになります。
    このメソッドが呼び出されると、SQL XML オブジェクトは読み込み不可能になり、実装によっては書き込み不可能になることもあります。
    
    戻り値:
    XML データを格納するストリーム
    
    例外:
    
    SQLException - XML 値を処理するときにエラーが発生した場合。状態が読み込み不可能である場合は、例外がスローされる
    
    SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
    導入されたバージョン:
    
    1.6
  - setBinaryStream
```
OutputStream setBinaryStream()
                             throws SQLException
```
    この SQLXML インスタンスが表す XML 値への書き込みに使用するストリームを取得します。ストリームは位置 0 から始まります。ストリームのバイトは、XML 1.0 仕様の付録 F にしたがって解釈されます。ResultSet の指定された列が java.sql.Types 型の SQLXML である場合、このメソッドの動作は ResultSet.updateBinaryStream() と同じになります。
    このメソッドが呼び出されると、SQL XML オブジェクトは書き込み不可能になり、実装によっては読み込み不可能になることもあります。
    
    戻り値:
    データが書き込まれるストリーム
    
    例外:
    
    SQLException - XML 値を処理するときにエラーが発生した場合。状態が書き込み不可能である場合は、例外がスローされる
    
    SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
    導入されたバージョン:
    
    1.6
  - getCharacterStream
```
Reader getCharacterStream()
                          throws SQLException
```
    この SQLXML インスタンスによって指定された XML 値を java.io.Reader オブジェクトとして取得します。このストリームの形式は、org.xml.sax.InputSource で定義されます。ストリームの文字は、XML 1.0 仕様のセクション 2 と付録 B に従って、XML の Unicode コードポイントを表します。Unicode 以外のエンコーディング宣言が存在する可能性はありますが、ストリームのエンコーディングは Unicode です。ResultSet の指定された列が java.sql.Types 型の SQLXML である場合、このメソッドの動作は ResultSet.getCharacterStream() と同じになります。
    このメソッドが呼び出されると、SQL XML オブジェクトは読み込み不可能になり、実装によっては書き込み不可能になることもあります。
    
    戻り値:
    XML データを格納するストリーム
    
    例外:
    
    SQLException - XML 値を処理するときにエラーが発生した場合。この例外の getCause() メソッドにより、より詳細な例外が提供されることがある (たとえばストリームに有効な文字が含まれていない場合)。状態が読み込み不可能である場合は、例外がスローされる
    
    SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
    導入されたバージョン:
    
    1.6
  - setCharacterStream
```
Writer setCharacterStream()
                          throws SQLException
```
    この SQLXML インスタンスが表す XML 値への書き込みに使用するストリームを取得します。このストリームの形式は、org.xml.sax.InputSource で定義されます。ストリームの文字は、XML 1.0 仕様のセクション 2 と付録 B に従って、XML の Unicode コードポイントを表します。Unicode 以外のエンコーディング宣言が存在する可能性はありますが、ストリームのエンコーディングは Unicode です。ResultSet の指定された列が java.sql.Types 型の SQLXML である場合、このメソッドの動作は ResultSet.updateCharacterStream() と同じになります。
    このメソッドが呼び出されると、SQL XML オブジェクトは書き込み不可能になり、実装によっては読み込み不可能になることもあります。
    
    戻り値:
    データが書き込まれるストリーム
    
    例外:
    
    SQLException - XML 値を処理するときにエラーが発生した場合。この例外の getCause() メソッドにより、より詳細な例外が提供されることがある (たとえばストリームに有効な文字が含まれていない場合)。状態が書き込み不可能である場合は、例外がスローされる
    
    SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
    導入されたバージョン:
    
    1.6
  - getString
```
String getString()
                 throws SQLException
```
    この SQLXML インスタンスによって指定された XML 値の文字列表現を返します。この String の形式は、org.xml.sax.InputSource で定義されます。ストリームの文字は、XML 1.0 仕様のセクション 2 と付録 B に従って、XML の Unicode コードポイントを表します。Unicode 以外のエンコーディング宣言が存在する可能性はありますが、String のエンコーディングは Unicode です。ResultSet の指定された列が java.sql.Types 型の SQLXML である場合、このメソッドの動作は ResultSet.getString() と同じになります。
    このメソッドが呼び出されると、SQL XML オブジェクトは読み込み不可能になり、実装によっては書き込み不可能になることもあります。
    
    戻り値:
    この SQLXML インスタンスによって指定された XML 値の文字列表現
    
    例外:
    
    SQLException - XML 値を処理するときにエラーが発生した場合。この例外の getCause() メソッドにより、より詳細な例外が提供されることがある (たとえばストリームに有効な文字が含まれていない場合)。状態が読み込み不可能である場合は、例外がスローされる
    
    SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
    導入されたバージョン:
    
    1.6
  - setString
```
void setString(String value)
               throws SQLException
```
    この SQLXML インスタンスによって指定された XML 値を指定された String 表現に設定します。この String の形式は、org.xml.sax.InputSource で定義されます。ストリームの文字は、XML 1.0 仕様のセクション 2 と付録 B に従って、XML の Unicode コードポイントを表します。Unicode 以外のエンコーディング宣言が存在する可能性はありますが、String のエンコーディングは Unicode です。ResultSet の指定された列が java.sql.Types 型の SQLXML である場合、このメソッドの動作は ResultSet.updateString() と同じになります。
    このメソッドが呼び出されると、SQL XML オブジェクトは書き込み不可能になり、実装によっては読み込み不可能になることもあります。
    
    パラメータ:
    value - XML 値
    
    例外:
    
    SQLException - XML 値を処理するときにエラーが発生した場合。この例外の getCause() メソッドにより、より詳細な例外が提供されることがある (たとえばストリームに有効な文字が含まれていない場合)。状態が書き込み不可能である場合は、例外がスローされる
    
    SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
    導入されたバージョン:
    
    1.6
  - getSource
```
<T extends Source> T getSource(Class<T> sourceClass)
                           throws SQLException
```
    この SQLXML インスタンスによって指定された XML 値を読み込むための Source を返します。Source は、XML パーサーおよび XSLT トランスフォーマへの入力として使用されます。
    XML パーサーの Source では、デフォルトで名前空間処理があります。Source の systemID は実装で決定されます。
    このメソッドが呼び出されると、SQL XML オブジェクトは読み込み不可能になり、実装によっては書き込み不可能になることもあります。
    SAX はコールバックアーキテクチャーであるため、返される SAXSource は、解析からの SAX イベントを受信するコンテンツハンドラで設定されなければいけません。コンテンツハンドラは、XML の内容に基づいてコールバックを受信します。
```
   SAXSource saxSource = sqlxml.getSource(SAXSource.class);
   XMLReader xmlReader = saxSource.getXMLReader();
   xmlReader.setContentHandler(myHandler);
   xmlReader.parse(saxSource.getInputSource());
 
```
    パラメータ:
    sourceClass - ソースのクラス、または null。クラスが null の場合、ベンダー固有の Source 実装が返される。少なくとも次のクラスがサポートされる
    javax.xml.transform.dom.DOMSource - returns a DOMSource javax.xml.transform.sax.SAXSource - returns a SAXSource javax.xml.transform.stax.StAXSource - returns a StAXSource javax.xml.transform.stream.StreamSource - returns a StreamSource
    戻り値:
    XML 値の読み込みに使用するソース
    
    例外:
    
    SQLException - XML 値を処理するときにエラーが発生した場合、またはこの機能がサポートされていない場合。この例外の getCause() メソッドにより、より詳細な例外が提供されることがある (たとえば XML パーサー例外が発生した場合)。状態が読み込み不可能である場合は、例外がスローされる
    
    SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
    導入されたバージョン:
    
    1.6
  - setResult
```
<T extends Result> T setResult(Class<T> resultClass)
                           throws SQLException
```
    この SQLXML インスタンスによって指定された XML 値を設定するための Result を返します。
    Result の systemID は実装で決定されます。
    このメソッドが呼び出されると、SQL XML オブジェクトは書き込み不可能になり、実装によっては読み込み不可能になることもあります。
    SAX はコールバックアーキテクチャーであるため、返される SAXResult には、XML の内容に基づいて SAX イベントを受信するコンテンツハンドラが割り当てられます。値を割り当てるには、XML ドキュメントの内容を使用してコンテンツハンドラを呼び出してください。
```
   SAXResult saxResult = sqlxml.setResult(SAXResult.class);
   ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler();
   contentHandler.startDocument();
   // set the XML elements and attributes into the result
   contentHandler.endDocument();
 
```
    パラメータ:
    resultClass - 結果のクラス、または null。resultClass が null の場合、ベンダー固有の Result 実装が返される。少なくとも次のクラスがサポートされる
    javax.xml.transform.dom.DOMResult - returns a DOMResult javax.xml.transform.sax.SAXResult - returns a SAXResult javax.xml.transform.stax.StAXResult - returns a StAXResult javax.xml.transform.stream.StreamResult - returns a StreamResult
    戻り値:
    XML 値の設定に使用する Result を返す
    
    例外:
    
    SQLException - XML 値を処理するときにエラーが発生した場合、またはこの機能がサポートされていない場合。この例外の getCause() メソッドにより、より詳細な例外が提供されることがある (たとえば XML パーサー例外が発生した場合)。状態が書き込み不可能である場合は、例外がスローされる
    
    SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
    導入されたバージョン:
    
    1.6

バグまたは機能を送信
詳細な API リファレンスおよび開発者ドキュメントについては、Java SE のドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.

インタフェース SQLXML

メソッドのサマリー

メソッドの詳細

free

getBinaryStream

setBinaryStream

getCharacterStream

setCharacterStream

getString

setString

getSource

setResult