public interface 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>
TgetSource(クラス<T> sourceClass)
このSQLXMLインスタンスによって指定されたXML値を読み込むためのSourceを返します。String
getString()
このSQLXMLインスタンスによって指定されたXML値の文字列表現を返します。OutputStream
setBinaryStream()
このSQLXMLインスタンスが表すXML値への書込みに使用するストリームを取得します。Writer
setCharacterStream()
このSQLXMLインスタンスが表すXML値への書込みに使用するストリームを取得します。<T extends Result>
TsetResult(クラス<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
-