-
public interface SQLXML
Java 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文档节点:
DOMSource domSource = sqlxml.getSource(DOMSource.class); Document document = (Document) domSource.getNode();
或者将DOM Document Document的值设置为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对文件resultFile执行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);
从DOMResult创建DOMSource:DOMSource domSource = new DOMSource(domResult.getNode());
设置不完整或无效的XML值可能会导致SQLException,或者发生execute()时可能会发生异常。 必须在执行execute()之前关闭所有流,否则将抛出SQLException。
从SQLXML对象读取XML值或从中读取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()
将此SQLXML实例指定的XML值检索为java.io.Reader对象。<T extends Source>
TgetSource(类<T> sourceClass)
返回用于读取此SQLXML实例指定的XML值的Source。String
getString()
返回此SQLXML实例指定的XML值的字符串表示形式。OutputStream
setBinaryStream()
检索可用于编写此SQLXML实例表示的XML值的流。Writer
setCharacterStream()
检索用于写入此SQLXML实例表示的XML值的流。<T extends Result>
TsetResult(类<T> resultClass)
返回用于设置此SQLXML实例指定的XML值的Result。void
setString(String value)
将此SQLXML实例指定的XML值设置为给定的String表示形式。
-
-
-
方法详细信息
-
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的unicode代码点,符合XML 1.0规范的第2节和附录B. 尽管可能存在除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的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值的字符串表示形式。 此String的格式由org.xml.sax.InputSource定义,其中流中的字符表示XML的unicode代码点,符合XML 1.0规范的第2节和附录B. 尽管可能存在除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的unicode代码点,符合XML 1.0规范的第2节和附录B. 尽管可能存在除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值的Source。 源用作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值的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();
- 参数类型
-
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值的Result。
- 异常
-
SQLException
- 如果处理XML值时出错,或者不支持此功能。 异常的getCause()方法可能会提供更详细的异常,例如,如果发生XML解析器异常。 如果状态不可写,则抛出异常。 -
SQLFeatureNotSupportedException
- 如果JDBC驱动程序不支持此方法 - 从以下版本开始:
- 1.6
-
-