compact2, compact3

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（）。 当这种情况发生时，实现也可能会将状态更改为不可读。

所有的方法SQLXML接口必须如果JDBC驱动程序支持的数据类型得到充分执行。

从以下版本开始：

1.6

另请参见：

javax.xml.parsers ， javax.xml.stream ， javax.xml.transform ， javax.xml.xpath

方法摘要

Modifier and Type	Method and Description
void	free() 此方法关闭此对象并释放其持有的资源。
InputStream	getBinaryStream() 检索此SQLXML实例指定的XML值作为流。
Reader	getCharacterStream() 将此SQLXML实例指定的XML值作为java.io.Reader对象检索。
<T extends Source> T	getSource(类<T> sourceClass) 返回一个用于读取此SQLXML实例指定的XML值的源。
String	getString() 返回此SQLXML实例指定的XML值的字符串表示形式。
OutputStream	setBinaryStream() 检索可用于编写此SQLXML实例所代表的XML值的流。
Writer	setCharacterStream() 检索用于写入此SQLXML实例所代表的XML值的流。
<T extends Result> T	setResult(类<T> resultClass) 返回一个用于设置此SQLXML实例指定的XML值的结果。
void	setString(String value) 将此SQLXML实例指定的XML值设置为给定的String表示形式。

方法详细信息

free

void free()
   throws SQLException

此方法关闭此对象并释放其持有的资源。 当调用此方法时，SQL XML对象变得无效，既不可读，也不可写。 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(类<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(类<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