モジュール java.sql
パッケージ 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.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