模块 java.sql
 java.sql

接口 SQLXML


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

SQLXML 接口提供了将 XML 值作为 String、Reader 或 Writer 或作为 Stream 进行访问的方法。 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 文档节点:

  DOMSource domSource = sqlxml.getSource(DOMSource.class);
  Document document = (Document) domSource.getNode();
 
或将值设置为 myNode 的 DOM 文档节点:
  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() 指定的身份转换将任何源转换为结果:
  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);
 
将源的内容写入标准输出:
  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
参见:
  • 方法总结

    修饰符和类型
    方法
    描述
    void
    free()
    此方法关闭此对象并释放它持有的资源。
    检索此 SQLXML 实例指定的 XML 值作为流。
    检索由此 SQLXML 实例指定为 java.io.Reader 对象的 XML 值。
    <T extends Source>
    T
    getSource(Class<T> sourceClass)
    返回用于读取此 SQLXML 实例指定的 XML 值的源。
    返回此 SQLXML 实例指定的 XML 值的字符串表示形式。
    检索可用于写入此 SQLXML 实例表示的 XML 值的流。
    检索要用于写入此 SQLXML 实例表示的 XML 值的流。
    <T extends Result>
    T
    setResult(Class<T> resultClass)
    返回用于设置此 SQLXML 实例指定的 XML 值的结果。
    void
    setString(String value)
    将此 SQLXML 实例指定的 XML 值设置为给定的 String 表示形式。
  • 方法详情

    • free

      void free() throws SQL异常
      此方法关闭此对象并释放它持有的资源。调用此方法时,SQL XML 对象变为无效且不可读或不可写。在调用 free 之后,任何调用 free 以外的方法的尝试都将导致抛出 SQLException。如果多次调用 free,则对 free 的后续调用将被视为空操作。
      抛出:
      SQLException - 如果释放 XML 值时出错。
      SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法
      自从:
      1.6
    • getBinaryStream

      InputStream  getBinaryStream() throws SQL异常
      检索此 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 SQL异常
      检索可用于写入此 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 SQL异常
      检索由此 SQLXML 实例指定为 java.io.Reader 对象的 XML 值。此流的格式由 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 SQL异常
      检索要用于写入此 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 SQL异常
      返回此 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 SQL异常
      将此 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 SQL异常
      返回用于读取此 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 SQL异常
      返回用于设置此 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 为空,将返回供应商特定的结果实现。至少支持以下类:
        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