SQLXML (Java Platform SE 8)

```
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.getHandler();
   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());
 
```
    型パラメータ:
    
    T - このClassオブジェクトでモデル化されるクラスの型
    
    パラメータ:
    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();
 
```
    型パラメータ:
    
    T - このClassオブジェクトでモデル化されるクラスの型
    
    パラメータ:
    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, 2014, Oracle and/or its affiliates. All rights reserved.

インタフェースSQLXML

メソッドのサマリー

メソッドの詳細

free

getBinaryStream

setBinaryStream

getCharacterStream

setCharacterStream

getString

setString

getSource

setResult