モジュール 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