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.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 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