模块  java.sql
软件包  java.sql

Interface SQLXML

  • public interface SQLXML
    Java 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值的方法。

    可以使用BinaryStream获取SQLXML实例的XML值 

      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文档节点： 

      DOMSource domSource = sqlxml.getSource(DOMSource.class);   Document document = (Document) domSource.getNode();
    或者将DOM Document 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();
    或者，使用xsltFile输出中的XSLT对文件resultFile执行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值可能会导致SQLException，或者发生execute（）时可能会发生异常。 必须在执行execute（）之前关闭所有流，否则将抛出SQLException。

    从SQLXML对象读取XML值或从中读取XML值最多只能发生一次。 可读和不可读的概念状态确定其中一个读取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

    • 方法详细信息

      • free

        void free()   throws SQLException
        此方法关闭此对象并释放它所拥有的资源。 调用此方法时，SQL XML对象变为无效且无法读取或写入。 在free之后，任何调用free以外的方法的尝试free将导致抛出SQLException 。 如果free被多次调用，在后续调用free被视为无操作。
        异常
        SQLException - 如果释放XML值时出错。
        SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
        从以下版本开始：
        1.6

      • getBinaryStream

        InputStream getBinaryStream()                     throws SQLException
        以流的形式检索此SQLXML实例指定的XML值。 根据XML 1.0规范的附录F解释输入流的字节。 当ResultSet的指定列具有SQLXML类型java.sql.Types时，此方法的行为与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时，此方法的行为与ResultSet.updateBinaryStream（）的行为相同.SQLXML的类型。

        调用此方法时，SQL XML对象变为不可写，并且根据实现可能也变得不可读。

        结果
        可以写入数据的流。
        异常
        SQLException - 如果处理XML值时出错。 如果状态不可写，则抛出异常。
        SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
        从以下版本开始：
        1.6

      • getCharacterStream

        Reader getCharacterStream()                   throws SQLException
        将此SQLXML实例指定的XML值检索为java.io.Reader对象。 此流的格式由org.xml.sax.InputSource定义，其中流中的字符表示XML的unicode代码点，符合XML 1.0规范的第2节和附录B. 尽管可能存在除unicode之外的编码声明，但是流的编码是unicode。 当ResultSet的指定列具有SQLXML类型java.sql.Types时，此方法的行为与ResultSet.getCharacterStream（）相同。

        调用此方法时，SQL XML对象变得不可读，并且根据实现可能也变得不可写。

        结果
        包含XML数据的流。
        异常
        SQLException - 如果处理XML值时出错。 异常的getCause（）方法可能会提供更详细的异常，例如，如果流不包含有效字符。 如果状态不可读，则抛出异常。
        SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
        从以下版本开始：
        1.6

      • setCharacterStream

        Writer setCharacterStream()                   throws SQLException
        检索用于写入此SQLXML实例表示的XML值的流。 此流的格式由org.xml.sax.InputSource定义，其中流中的字符表示XML的unicode代码点，符合XML 1.0规范的第2节和附录B. 尽管可能存在除unicode之外的编码声明，但是流的编码是unicode。 当ResultSet的指定列具有SQLXML类型java.sql.Types时，此方法的行为与ResultSet.updateCharacterStream（）相同。

        调用此方法时，SQL XML对象变为不可写，并且根据实现可能也变得不可读。

        结果
        可以写入数据的流。
        异常
        SQLException - 如果处理XML值时出错。 异常的getCause（）方法可能会提供更详细的异常，例如，如果流不包含有效字符。 如果状态不可写，则抛出异常。
        SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
        从以下版本开始：
        1.6

      • getString

        String getString()          throws SQLException
        返回此SQLXML实例指定的XML值的字符串表示形式。 此String的格式由org.xml.sax.InputSource定义，其中流中的字符表示XML的unicode代码点，符合XML 1.0规范的第2节和附录B. 尽管可能存在除unicode之外的编码声明，但String的编码是unicode。 当ResultSet的指定列具有SQLXML类型java.sql.Types时，此方法的行为与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的unicode代码点，符合XML 1.0规范的第2节和附录B. 尽管可能存在除unicode之外的编码声明，但String的编码是unicode。 当ResultSet的指定列具有SQLXML类型java.sql.Types时，此方法的行为与ResultSet.updateString（）相同。

        调用此方法时，SQL XML对象变为不可写，并且根据实现可能也变得不可读。

        参数
        value - XML值
        异常
        SQLException - 如果处理XML值时出错。 异常的getCause（）方法可能会提供更详细的异常，例如，如果流不包含有效字符。 如果状态不可写，则抛出异常。
        SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
        从以下版本开始：
        1.6

      • getSource

        <T extends Source> T getSource​(类<T> sourceClass)                        throws SQLException
        返回用于读取此SQLXML实例指定的XML值的Source。 源用作XML解析器和XSLT转换器的输入。

        默认情况下，XML解析器的源将启用命名空间处理。 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​(类<T> resultClass)                        throws SQLException
        返回用于设置此SQLXML实例指定的XML值的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