public interface SQLXML

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

SQLXML接口提供了访问XML值的方法，可以作为String、Reader或Writer，或作为Stream。XML值也可以通过Source访问或设置为Result，这些与XML解析器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();

或者将值设置为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();
   // 将XML元素和属性设置到结果中
   contentHandler.endDocument();

或者获取StAX事件：

   StAXSource staxSource = sqlxml.getSource(StAXSource.class);
   XMLStreamReader streamReader = staxSource.getXMLStreamReader();

或者从StAX事件设置结果值：

   StAXResult staxResult = sqlxml.setResult(StAXResult.class);
   XMLStreamWriter streamWriter = staxResult.getXMLStreamWriter();

或者使用XSLT在xsltFile中对XML值执行转换并输出到文件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()指定的恒等变换，任何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。在执行之前必须关闭所有流，否则将抛出SQLException。

将XML值从或写入SQLXML对象最多只能发生一次。可读和不可读的概念状态确定读取API之一是否会返回值或抛出异常。可写和不可写的概念状态确定写入API之一是否会设置值或抛出异常。

当调用free()或任何读取API时，状态从可读变为不可读：getBinaryStream()、getCharacterStream()、getSource()和getString()。实现也可能在此时将状态更改为不可写。

当调用free()或任何写入API时，状态从可写变为不可写：setBinaryStream()、setCharacterStream()、setResult()和setString()。实现也可能在此时将状态更改为不可读。

如果JDBC驱动程序支持数据类型，则必须完全实现SQLXML接口的所有方法。

自从:

1.6

参见:

Method Summary

Modifier and Type

Method

Description

void

free()

此方法关闭此对象并释放其持有的资源。

InputStream

getBinaryStream()

检索由此SQLXML实例指定的XML值作为流。

Reader

getCharacterStream()

检索由此SQLXML实例指定的XML值作为java.io.Reader对象。

<T extends Source> T

getSource(Class<T> sourceClass)

返回用于读取由此SQLXML实例指定的XML值的Source。

String

getString()

返回由此SQLXML实例指定的XML值的字符串表示。

OutputStream

setBinaryStream()

检索可用于写入此SQLXML实例表示的XML值的流。

Writer

setCharacterStream()

检索可用于写入此SQLXML实例表示的XML值的流。

<T extends Result> T

setResult(Class<T> resultClass)

返回用于设置由此SQLXML实例指定的XML值的Result。

void

setString(String value)

将由此SQLXML实例指定的XML值设置为给定的String表示。

Method Details
- free
  
  void free() throws SQLException
  
  此方法关闭此对象并释放其持有的资源。调用此方法后，SQL XML对象将变为无效，并且在调用此方法时既不可读也不可写。调用free后，任何尝试调用除free之外的方法都将导致抛出SQLException。如果多次调用free，则后续调用将被视为无操作。
  
  抛出:
  
  SQLException - 如果释放XML值时出现错误。
  
  SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
  
  自从:
  
  1.6
- getBinaryStream
  
  InputStream getBinaryStream() throws SQLException
  
  检索由此SQLXML实例指定的XML值作为流。输入流的字节根据XML 1.0规范附录F进行解释。当ResultSet的指定列具有java.sql.Types为SQLXML的类型时，此方法的行为与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.Types为SQLXML的类型时，此方法的行为与ResultSet.updateBinaryStream()相同。
  调用此方法后，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的指定列具有java.sql.Types为SQLXML的类型时，此方法的行为与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值的字符串表示形式。该字符串的格式由org.xml.sax.InputSource定义，其中流中的字符表示XML的Unicode代码点，根据XML 1.0规范的第2节和附录B。虽然可能存在除Unicode之外的编码声明，但字符串的编码是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值设置为给定的字符串表示形式。该字符串的格式由org.xml.sax.InputSource定义，其中流中的字符表示XML的Unicode代码点，根据XML 1.0规范的第2节和附录B。虽然可能存在除Unicode之外的编码声明，但字符串的编码是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值的Source。Sources用作XML解析器和XSLT转换器的输入。
  XML解析器的Sources默认启用命名空间处理。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 - 返回DOMSource javax.xml.transform.sax.SAXSource - 返回SAXSource javax.xml.transform.stax.StAXSource - 返回StAXSource javax.xml.transform.stream.StreamSource - 返回StreamSource
  
  返回:
  
  用于读取XML值的Source。
  
  抛出:
  
  SQLException - 如果处理XML值时出现错误或不支持此功能。异常的getCause()方法可能提供更详细的异常信息，例如，如果发生XML解析器异常。如果状态不可读，则会抛出异常。
  
  SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
  
  自从:
  
  1.6
- setResult
  
  <T extends Result> T setResult(Class<T> resultClass) throws SQLException
  返回用于设置此SQLXML实例指定的XML值的Result。
  Result的systemID取决于实现。
  
  调用此方法后，SQL XML对象变为不可写，并且根据实现方式，可能也变为不可读。
  
  请注意，SAX是一种回调架构，返回的SAXResult具有分配的内容处理程序，该处理程序将根据XML的内容接收SAX事件。调用内容处理程序并将XML文档的内容分配给值。
  
  SAXResult saxResult = sqlxml.setResult(SAXResult.class); ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler(); contentHandler.startDocument(); // 将XML元素和属性设置到结果中 contentHandler.endDocument();
  类型参数:
  
  T - 由此Class对象建模的类的类型
  
  参数:
  
  resultClass - 结果的类，或null。如果resultClass为null，则将返回供应商特定的Result实现。至少支持以下类：
  javax.xml.transform.dom.DOMResult - 返回DOMResult javax.xml.transform.sax.SAXResult - 返回SAXResult javax.xml.transform.stax.StAXResult - 返回StAXResult javax.xml.transform.stream.StreamResult - 返回StreamResult
  
  返回:
  
  用于设置XML值的Result。
  
  抛出:
  
  SQLException - 如果处理XML值时出现错误或不支持此功能。异常的getCause()方法可能提供更详细的异常信息，例如，如果发生XML解析器异常。如果状态不可写，则会抛出异常。
  
  SQLFeatureNotSupportedException - 如果JDBC驱动程序不支持此方法
  
  自从:
  
  1.6

Interface SQLXML

Method Summary

Method Details

free

getBinaryStream

setBinaryStream

getCharacterStream

setCharacterStream

getString

setString

getSource

setResult