模块  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.parsersjavax.xml.streamjavax.xml.transformjavax.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