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返回用于读取此 SQLXML 实例指定的 XML 值的源。返回此 SQLXML 实例指定的 XML 值的字符串表示形式。检索可用于写入此 SQLXML 实例表示的 XML 值的流。检索要用于写入此 SQLXML 实例表示的 XML 值的流。<T extends Result>
T返回用于设置此 SQLXML 实例指定的 XML 值的结果。void
将此 SQLXML 实例指定的 XML 值设置为给定的 String 表示形式。
-
方法详情
-
free
此方法关闭此对象并释放它持有的资源。调用此方法时,SQL XML 对象变为无效且不可读或不可写。在调用free
之后,任何调用free
以外的方法的尝试都将导致抛出SQLException
。如果多次调用free
,则对free
的后续调用将被视为空操作。- 抛出:
SQLException
- 如果释放 XML 值时出错。SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法- 自从:
- 1.6
-
getBinaryStream
检索此 SQLXML 实例指定的 XML 值作为流。输入流的字节根据 XML 1.0 规范的附录 F 进行解释。当 ResultSet 的指定列具有 SQLXML 的 java.sql.Types 类型时,此方法的行为与 ResultSet.getBinaryStream() 相同。调用此方法时,SQL XML 对象变得不可读,并且也可能变得不可写,具体取决于实现。
- 返回:
- 包含 XML 数据的流。
- 抛出:
SQLException
- 如果处理 XML 值时出错。如果状态不可读,则会抛出异常。SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法- 自从:
- 1.6
-
setBinaryStream
检索可用于写入此 SQLXML 实例表示的 XML 值的流。流从位置 0 开始。流的字节根据 XML 1.0 规范的附录 F 进行解释当 ResultSet 的指定列的类型为 java.sql 时,此方法的行为与 ResultSet.updateBinaryStream() 相同.SQLXML 的类型。调用此方法时,SQL XML 对象变得不可写,并且也可能变得不可读,具体取决于实现。
- 返回:
- 可以写入数据的流。
- 抛出:
SQLException
- 如果处理 XML 值时出错。如果状态不可写,则抛出异常。SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法- 自从:
- 1.6
-
getCharacterStream
检索由此 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
检索要用于写入此 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
返回此 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
将此 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
返回用于读取此 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
返回用于设置此 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
-