JavaTM Platform
Standard Ed. 6

java.sql
インタフェース SQLXML


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 - DOMSource を返す
   javax.xml.transform.sax.SAXSource - SAXSource を返す
   javax.xml.transform.stax.StAXSource - StAXSource を返す
   javax.xml.transform.stream.StreamSource - 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 - DOMResult を返す
   javax.xml.transform.sax.SAXResult - SAXResult を返す
   javax.xml.transform.stax.StAXResult - StAXResult を返す
   javax.xml.transform.stream.StreamResult - StreamResult を返す
 
戻り値:
XML 値の設定に使用する Result を返す
例外:
SQLException - XML 値を処理するときにエラーが発生した場合、またはこの機能がサポートされていない場合。 この例外の getCause() メソッドにより、より詳細な例外が提供されることがある (たとえば XML パーサー例外が発生した場合)。 状態が書き込み不可能である場合は、例外がスローされる
SQLFeatureNotSupportedException - JDBC ドライバがこのメソッドをサポートしない場合
導入されたバージョン:
1.6

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。