java.sql

接口
类
异常

java.sql
接口 SQLXML

public interface SQLXML

SQL 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 Document Node： 

DOMSource domSource = sqlxml.getSource(DOMSource.class);
Document document = (Document) domSource.getNode();
或者，将值设置为 myNode 的 DOM Document Node： 
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.getXMLReader().getContentHandler();
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();
或者，使用输出到 resultFile 文件的 xsltFile 中的 XSLT 对 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);
根据 DOMSource 创建 DOMResult： 
DOMSource domSource = new DOMSource(domResult.getNode());

设置不完整或无效的 XML 值时可能导致 SQLException，该异常也可能在执行 execute() 时发生。执行 execute() 前必须关闭所有流，否则将抛出 SQLException。

从 SQLXML 对象读取和向 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

方法摘要
 void free()
          此方法关闭此对象并释放其持有的资源。
 InputStream getBinaryStream()
          以流的形式获取此 SQLXML 实例指定的 XML 值。
 Reader getCharacterStream()
          以 java.io.Reader 对象的形式获取此 SQLXML 实例指定的 XML 值。
<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 表示形式。
 

方法详细信息

free

void free()
          throws SQLException
此方法关闭此对象并释放其持有的资源。当调用此方法时，SQL XML 对象变为无效并不再可读或可写。 调用 free 之后，尝试调用 free 之外的方法都将导致抛出 SQLException。如果多次调用 free，则后续对 free 的调用都被视为无操作 (no-op)。

抛出：
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 的指定列的类型为 SQLXML java.sql.Types 类型时，此方法的行为与 ResultSet.updateBinaryStream() 相同。

调用此方法时，SQL XML 对象将变为不可写，也可能变为不可读，具体取决于实现。

返回：
可以写入数据的流。
抛出：
SQLException - 如果处理 XML 值时出现错误。如果状态为不可写，也将抛出该异常。
SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法
从以下版本开始：
1.6

getCharacterStream

Reader getCharacterStream()
                          throws SQLException
以 java.io.Reader 对象的形式获取此 SQLXML 实例指定的 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 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 值的字符串表示形式。此 String 的格式由 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 表示形式。此 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 值的 Source。Source 用作对 XML 解析器和 XSLT 转换器的输入。

XML 解析器的 Source 将以默认方式处理名称空间。Source 的 systemID 与实现有关。

调用此方法时，SQL XML 对象将变为不可读，也可能变为不可写，具体取决于实现。

注意，SAX 是一个回调架构，因此应使用通过解析接收 SAX 事件的内容处理程序设置返回的 SAXSource。内容处理程序将根据 XML 的内容接收回调。 

SAXSource saxSource = sqlxml.getSource(SAXSource.class);
XMLReader xmlReader = saxSource.getXMLReader();
xmlReader.setContentHandler(myHandler);
xmlReader.parse(saxSource.getInputSource());

参数：
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();
// set the XML elements and attributes into the result
contentHandler.endDocument();

参数：
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