©
This document uses PHP Chinese website manual Release
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
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
接口中的所有方法。
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 值。 |
|
|
getSource(Class<T> sourceClass)
返回读取此 SQLXML 实例指定的 XML 值的 Source。 |
|
String |
getString()
返回此 SQLXML 实例指定的 XML 值的字符串表示形式。 |
|
OutputStream |
setBinaryStream()
获取可用于写入此 SQLXML 实例表示的 XML 值的流。 |
|
Writer |
setCharacterStream()
获取用于写入此 SQLXML 实例表示的 XML 值的流。 |
|
|
setResult(Class<T> resultClass)
返回设置此 SQLXML 实例指定的 XML 值的 Result。 |
|
void |
setString(String value)
将此 SQLXML 实例指定的 XML 值设置为给定的 String 表示形式。 |
方法详细信息 |
---|
void free() throws SQLException
free
之后,尝试调用 free
之外的方法都将导致抛出 SQLException
。如果多次调用 free
,则后续对 free
的调用都被视为无操作 (no-op)。
SQLException
- 如果释放 XML 值时出现错误。
SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法InputStream getBinaryStream() throws SQLException
调用此方法时,SQL XML 对象将变为不可读,也可能变为不可写,具体取决于实现。
SQLException
- 如果处理 XML 值时出现错误。如果状态为不可读,也将抛出该异常。
SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法OutputStream setBinaryStream() throws SQLException
调用此方法时,SQL XML 对象将变为不可写,也可能变为不可读,具体取决于实现。
SQLException
- 如果处理 XML 值时出现错误。如果状态为不可写,也将抛出该异常。
SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法Reader getCharacterStream() throws SQLException
调用此方法时,SQL XML 对象将变为不可读,也可能变为不可写,具体取决于实现。
SQLException
- 如果处理 XML 值时出现错误。该异常的 getCause() 方法可以提供更详细的异常,例如,如果流不包含有效字符。如果状态为不可读,也将抛出该异常。
SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法Writer setCharacterStream() throws SQLException
调用此方法时,SQL XML 对象将变为不可写,也可能变为不可读,具体取决于实现。
SQLException
- 如果处理 XML 值时出现错误。该异常的 getCause() 方法可以提供更详细的异常,例如,如果流不包含有效字符。如果状态为不可写,也将抛出该异常。
SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法String getString() throws SQLException
调用此方法时,SQL XML 对象将变为不可读,也可能变为不可写,具体取决于实现。
SQLException
- 如果处理 XML 值时出现错误。该异常的 getCause() 方法可以提供更详细的异常,例如,如果流不包含有效字符。如果状态为不可读,也将抛出该异常。
SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法void setString(String value) throws SQLException
调用此方法时,SQL XML 对象将变为不可写,也可能变为不可读,具体取决于实现。
value
- XML 值
SQLException
- 如果处理 XML 值时出现错误。该异常的 getCause() 方法可以提供更详细的异常,例如,是否流不包含有效字符。如果状态为不可写,也将抛出该异常。
SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法<T extends Source> T getSource(Class<T> sourceClass) throws SQLException
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
SQLException
- 如果处理 XML 值时出现错误,或者此性能不受支持。该异常的 getCause() 方法可以提供更详细的异常,例如,是否发生 XML 解析器异常。如果状态为不可读,也将抛出该异常。
SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法<T extends Result> T setResult(Class<T> resultClass) throws SQLException
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
SQLException
- 如果处理 XML 值时出现错误,或者此性能不受支持。该异常的 getCause() 方法可以提供更详细的异常,例如,是否发生 XML 解析器异常。如果状态为不可写,也将抛出该异常。
SQLFeatureNotSupportedException
- 如果 JDBC 驱动程序不支持此方法
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
上一个类 下一个类 | 框架 无框架 | |||||||||
摘要: 嵌套 | 字段 | 构造方法 | 方法 | 详细信息: 字段 | 构造方法 | 方法 |
版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。