SQLXML (Java 2 Platform SE 6)

概觀

軟體套件

類別

使用

階層樹

已過時

索引

說明

Java^TM 2 Platform
Standard Ed. 6

上一個類別 下一個類別

框架 無框架

摘要：巢狀 | 欄位 | 建構子 | 方法

詳細資訊：欄位 | 建構子 | 方法

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