Module  java.sql
软件包  java.sql

Interface SQLXML


  • public interface SQLXML
    用于SQL XML类型的JavaTM编程语言中的映射。 XML是一种内置类型，它将XML值作为列值存储在数据库表的一行中。 默认情况下，驱动程序实现SQLXML对象作为XML数据的逻辑指针，而不是数据本身。 SQLXML对象在创建事务的持续时间内是有效的。

    SQLXML接口提供了以String，Reader或Writer或Stream的形式访问XML值的方法。 XML值也可以通过源访问或设置为结果，它们与XML解析器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文档节点到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将XML值执行XSLT转换为文件resultFile： 
      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（）指定的标识变换将任何源转换为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值最多可以发生一次。 可读和不可读的概念状态确定读取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 1.0规范的第2节和附录B，流中的字符表示XML的unicode代码点。 虽然可能存在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 1.0规范的第2节和附录B，流中的字符表示XML的unicode代码点。 虽然可能存在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值的字符串表示形式。 此字符串的格式由org.xml.sax.InputSource定义，根据XML 1.0规范的第2节和附录B，流中的字符表示XML的unicode代码点。 虽然可能存在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表示形式。 此字符串的格式由org.xml.sax.InputSource定义，根据XML 1.0规范的第2节和附录B，流中的字符表示XML的unicode代码点。 虽然可能存在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​(Class<T> sourceClass)
                        throws SQLException
        返回一个用于读取此SQLXML实例指定的XML值的源。 来源用作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​(Class<T> resultClass)
                        throws SQLException
        返回一个用于设置此SQLXML实例指定的XML值的结果。

        结果的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值的结果。
        异常
        SQLException - 如果处理XML值时出错，或者不支持此功能。 异常的getCause（）方法可能会提供更详细的异常，例如，如果发生XML解析器异常。 如果状态不可写，则抛出异常。
        SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
        从以下版本开始：
        1.6