javax.sql.rowset
介面 WebRowSet

所有父級介面：

CachedRowSet, Joinable, ResultSet, RowSet, Wrapper

所有已知子介面：

FilteredRowSet, JoinRowSet

public interface WebRowSet
extends CachedRowSet

所有 WebRowSet 的實作都必須實作的標準介面。

1.0 概觀

WebRowSetImpl 提供可在需要時擴展的標準參考實作。

標準的 WebRowSet XML 網要定義位於以下 URI 中：

 http://java.sun.com/xml/ns/jdbc/webrowset.xsd
 

它描述使用 XML 描述 RowSet 物件時所需的標準 XML 文檔格式，所有 WebRowSet 介面的標準實作必須使用該文檔格式以確保互操作性。此外，WebRowSet 網要使用特定的 SQL/XML 網要註釋，從而確保較高的跨平臺互操作性。目前 ISO 組織正在為此而努力。SQL/XML 定義可從以下 URI 中得到：

 http://standards.iso.org/iso/9075/2002/12/sqlxml
 

網要定義從以下三個不同方面描述 RowSet 物件的內部資料：

• 屬性
除了較為通用的 RowSet 屬性之外，這些屬性還描述標準同步提供者屬性。
• 元資料
此項描述與 WebRowSet 物件管理的表格結構關聯的元資料。描述的元資料與在底層 java.sql.ResultSet 介面中可存取的元資料是緊密聯繫在一起的。
• 資料
此項描述原始資料（自從 WebRowSet 物件的上一次填充或上一次同步以來的資料狀態）和當前資料。通過追蹤原始資料和當前資料之間的 delta，WebRowSet 維持其資料中的更改與原始資料源同步的能力。

2.0 WebRowSet 狀態

以下幾部分演示 WebRowSet 實作應該如何使用 XML 網要來描述更新、插入和刪除操作，以及描述 XML 中 WebRowSet 物件的狀態。

2.1 狀態 1 - 將 WebRowSet 物件輸出為 XML

在此範例中，創建一個 WebRowSet 物件，並使用取自資料源的一個簡單的 2 列、5 行表進行填充。具有 WebRowSet 物件中的 5 個行使以 XML 描述它們成為可能。描述在 RowSet 介面中定義的各種標準 JavaBeans 屬性和在 CachedRowSet^TM 介面中定義的標準屬性的元資料，提供描述 WebRowSet 屬性的主要細節。使用標準 writeXml 方法將 WebRowSet 物件輸出為 XML 將內部屬性描述如下：

<properties>
       <command>select co1, col2 from test_table</command>
        <concurrency>1</concurrency>
        <datasource/>
        <escape-processing>true</escape-processing>
        <fetch-direction>0</fetch-direction>
        <fetch-size>0</fetch-size>
        <isolation-level>1</isolation-level>
        <key-columns/>
        <map/>
        <max-field-size>0</max-field-size>
        <max-rows>0</max-rows>
        <query-timeout>0</query-timeout>
        <read-only>false</read-only>
        <rowset-type>TRANSACTION_READ_UNCOMMITED</rowset-type>
        <show-deleted>false</show-deleted>
        <table-name/>
        <url>jdbc:thin:oracle</url>
        <sync-provider>
                <sync-provider-name>.com.rowset.provider.RIOptimisticProvider</sync-provider-name>
                <sync-provider-vendor>Sun Microsystems</sync-provider-vendor>
                <sync-provider-version>1.0</sync-provider-name>
                <sync-provider-grade>LOW</sync-provider-grade>
              <data-source-lock>NONE</data-source-lock>
        </sync-provider>
</properties> 
 

描述 WebRowSet 的組成的元資料使用 XML 描述的細節如下所示。注意，兩個列都在 column-definition 標識之間描述。

<metadata>
        <column-count>2</column-count>
        <column-definition>
                <column-index>1</column-index>
                <auto-increment>false</auto-increment>
                <case-sensitive>true</case-sensitive>
                <currency>false</currency>
                <nullable>1</nullable>
                <signed>false</signed>
                <searchable>true</searchable>
                <column-display-size>10</column-display-size>   
                <column-label>COL1</column-label>
                <column-name>COL1</column-name>
                <schema-name/>
                <column-precision>10</column-precision>
                <column-scale>0</column-scale>
                <table-name/>
                <catalog-name/>
                <column-type>1</column-type>
                <column-type-name>CHAR</column-type-name>
        </column-definition>
        <column-definition>
                <column-index>2</column-index>
                <auto-increment>false</auto-increment>
                <case-sensitive>false</case-sensitive>
                <currency>false</currency>
                <nullable>1</nullable>
                <signed>true</signed>
                <searchable>true</searchable>
                <column-display-size>39</column-display-size>
                <column-label>COL2</column-label>
                <column-name>COL2</column-name>
                <schema-name/>
                <column-precision>38</column-precision>
                <column-scale>0</column-scale>
                <table-name/>
                <catalog-name/>
                <column-type>3</column-type>
                <column-type-name>NUMBER</column-type-name>
        </column-definition>
</metadata>
 

詳細說明如何描述屬性和元資料之後，以下詳細說明如何使用 XML 描述 WebRowSet 物件的內容。注意，它描述的是自從實例化以來沒有經過任何修改的 WebRowSet 物件。currentRow 標記將被映射到 WebRowSet 物件所提供的表結構的每一個行。columnValue 標記可能包含 stringData 或 binaryData 標記，這取決於將 XML 值映射回的 SQL 型別。binaryData 標記包含 Base64 編碼的資料，通常用於 BLOB 和 CLOB 型別資料。

 <data>
        <currentRow>
                <columnValue>
                        firstrow
                </columnValue>
                <columnValue>
                        1
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        secondrow
                </columnValue>
                <columnValue>
                        2
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        thirdrow
                </columnValue>
                <columnValue>
                        3
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        fourthrow
                </columnValue>
                <columnValue>
                        4
                </columnValue>
        </currentRow>
 </data>
 

2.2 狀態 2 - 刪除行

在 WebRowSet 物件中刪除行首先簡單地移動到要刪除的行，然後調用 deleteRow 方法，如任何其他 RowSet 物件一樣。以下兩個程式碼行（其中 wrs 為 WebRowSet 物件）將刪除第三行。

     wrs.absolute(3);
     wrs.deleteRow();
 

XML 描述顯示第三行被標記為 deleteRow，這將在 WebRowSet 物件中刪去第三行。

 <data>
        <currentRow>
                <columnValue>
                        firstrow
                </columnValue>
                <columnValue>
                        1
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        secondrow
                </columnValue>
                <columnValue>
                        2
                </columnValue>
        </currentRow>
        <deleteRow>
                <columnValue>
                        thirdrow
                </columnValue>
                <columnValue>
                        3
                </columnValue>
        </deleteRow>
        <currentRow>
                <columnValue>
                        fourthrow
                </columnValue>
                <columnValue>
                        4
                </columnValue>
        </currentRow>
 </data>
 

2.3 狀態 3 - 插入行

WebRowSet 物件插入新行的方式是，移動到插入行，為該行中的每一列調用適當的更新方法，然後調用 insertRow 方法。

 wrs.moveToInsertRow();
 wrs.updateString(1, "fifththrow");
 wrs.updateString(2, "5");
 wrs.insertRow();
 

以下程式碼片段更改剛插入的行中第二列的值。注意，此程式碼在將新行直接插入到當前行的後面時應用，這就是 next 方法將指針移動到正確行的原因。調用方法 acceptChanges 將更改寫入資料源。

 wrs.moveToCurrentRow();
 wrs.next();
 wrs.updateString(2, "V");
 wrs.acceptChanges();
 :
 

使用 XML 描述此操作演示了在新行中插入 Java 程式碼的位置，然後在個別欄位上的新插入行上執行更新。

 
 <data>
        <currentRow>
                <columnValue>
                        firstrow
                </columnValue>
                <columnValue>
                        1
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        secondrow
                </columnValue>
                <columnValue>
                        2
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        newthirdrow
                </columnValue>
                <columnValue>
                        III
                </columnValue>
        </currentRow>
        <insertRow>
                <columnValue>
                        fifthrow
                </columnValue>
                <columnValue>
                        5
                </columnValue>
                <updateValue>
                        V
                </updateValue>
        </insertRow>
        <currentRow>
                <columnValue>
                        fourthrow
                </columnValue>
                <columnValue>
                        4
                </columnValue>
        </currentRow>
</date>
 

2.4 狀態 4 - 修改行

修改行產生特定的 XML，該 XML 記錄新值和被替換的值。被替換的值變成原始值，而新值變成當前值。以下程式碼將指針移動到特定行，執行一些修改，並在完成時更新行。

 wrs.absolute(5);
 wrs.updateString(1, "new4thRow");
 wrs.updateString(2, "IV");
 wrs.updateRow();
 

在 XML 中，此操作用 modifyRow 標記描述。出於原始行追蹤目的，原始值和新值都包含在該標記中。

 <data>
        <currentRow>
                <columnValue>
                        firstrow
                </columnValue>
                <columnValue>
                        1
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        secondrow
                </columnValue>
                <columnValue>
                        2
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        newthirdrow
                </columnValue>
                <columnValue>
                        III
                </columnValue>
        </currentRow>
        <currentRow>
                <columnValue>
                        fifthrow
                </columnValue>
                <columnValue>
                        5
                </columnValue>
        </currentRow>
        <modifyRow>
                <columnValue>
                        fourthrow
                </columnValue>
                <updateValue>
                        new4thRow
                </updateValue>
                <columnValue>
                        4
                </columnValue>
                <updateValue>
                        IV
                </updateValue>
        </modifyRow>
 </data>
 

另請參見：

JdbcRowSet, CachedRowSet, FilteredRowSet, JoinRowSet

欄位摘要

static String	PUBLIC_XML_SCHEMA 為 WebRowSet 實作定義 XML 標記及其有效值的 XML 網要定義的公共標識符。
static String	SCHEMA_SYSTEM_ID 為 WebRowSet 實作定義 XML 標記及其有效值的 XML 網要定義的 URL。

從介面 javax.sql.rowset.CachedRowSet 繼承的欄位

COMMIT_ON_ACCEPT_CHANGES

從介面 java.sql.ResultSet 繼承的欄位

CLOSE_CURSORS_AT_COMMIT, CONCUR_READ_ONLY, CONCUR_UPDATABLE, FETCH_FORWARD, FETCH_REVERSE, FETCH_UNKNOWN, HOLD_CURSORS_OVER_COMMIT, TYPE_FORWARD_ONLY, TYPE_SCROLL_INSENSITIVE, TYPE_SCROLL_SENSITIVE

方法摘要

void	readXml(InputStream iStream) 讀取基於串流的 XML 輸入，以填充此 WebRowSet 物件。
void	readXml(Reader reader) 從給定的 Reader 物件以其 XML 格式讀取 WebRowSet 物件。
void	writeXml(OutputStream oStream) 以 XML 格式將此 WebRowSet 物件的資料、屬性和元資料寫入給定的 OutputStream 物件。
void	writeXml(ResultSet rs, OutputStream oStream) 使用給定 ResultSet 物件的內容填充此 WebRowSet 物件，並以 XML 格式將其資料、屬性和元資料寫入給定的 OutputStream 物件。
void	writeXml(ResultSet rs, Writer writer) 使用給定 ResultSet 物件的內容填充此 WebRowSet 物件，並以 XML 格式將其資料、屬性和元資料寫入給定的 Writer 物件。
void	writeXml(Writer writer) 以 XML 格式將此 WebRowSet 物件的資料、屬性和元資料寫入給定的 Writer 物件。

從介面 javax.sql.rowset.CachedRowSet 繼承的方法

acceptChanges, acceptChanges, columnUpdated, columnUpdated, commit, createCopy, createCopyNoConstraints, createCopySchema, createShared, execute, getKeyColumns, getOriginal, getOriginalRow, getPageSize, getRowSetWarnings, getShowDeleted, getSyncProvider, getTableName, nextPage, populate, populate, previousPage, release, restoreOriginal, rollback, rollback, rowSetPopulated, setKeyColumns, setMetaData, setOriginalRow, setPageSize, setShowDeleted, setSyncProvider, setTableName, size, toCollection, toCollection, toCollection, undoDelete, undoInsert, undoUpdate

從介面 javax.sql.RowSet 繼承的方法

addRowSetListener, clearParameters, execute, getCommand, getDataSourceName, getEscapeProcessing, getMaxFieldSize, getMaxRows, getPassword, getQueryTimeout, getTransactionIsolation, getTypeMap, getUrl, getUsername, isReadOnly, removeRowSetListener, setArray, setAsciiStream, setAsciiStream, setAsciiStream, setAsciiStream, setBigDecimal, setBigDecimal, setBinaryStream, setBinaryStream, setBinaryStream, setBinaryStream, setBlob, setBlob, setBlob, setBlob, setBlob, setBlob, setBoolean, setBoolean, setByte, setByte, setBytes, setBytes, setCharacterStream, setCharacterStream, setCharacterStream, setCharacterStream, setClob, setClob, setClob, setClob, setClob, setClob, setCommand, setConcurrency, setDataSourceName, setDate, setDate, setDate, setDate, setDouble, setDouble, setEscapeProcessing, setFloat, setFloat, setInt, setInt, setLong, setLong, setMaxFieldSize, setMaxRows, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNCharacterStream, setNClob, setNClob, setNClob, setNClob, setNClob, setNClob, setNString, setNString, setNull, setNull, setNull, setNull, setObject, setObject, setObject, setObject, setObject, setObject, setPassword, setQueryTimeout, setReadOnly, setRef, setRowId, setRowId, setShort, setShort, setSQLXML, setSQLXML, setString, setString, setTime, setTime, setTime, setTime, setTimestamp, setTimestamp, setTimestamp, setTimestamp, setTransactionIsolation, setType, setTypeMap, setURL, setUrl, setUsername

從介面 java.sql.ResultSet 繼承的方法

absolute, afterLast, beforeFirst, cancelRowUpdates, clearWarnings, close, deleteRow, findColumn, first, getArray, getArray, getAsciiStream, getAsciiStream, getBigDecimal, getBigDecimal, getBigDecimal, getBigDecimal, getBinaryStream, getBinaryStream, getBlob, getBlob, getBoolean, getBoolean, getByte, getByte, getBytes, getBytes, getCharacterStream, getCharacterStream, getClob, getClob, getConcurrency, getCursorName, getDate, getDate, getDate, getDate, getDouble, getDouble, getFetchDirection, getFetchSize, getFloat, getFloat, getHoldability, getInt, getInt, getLong, getLong, getMetaData, getNCharacterStream, getNCharacterStream, getNClob, getNClob, getNString, getNString, getObject, getObject, getObject, getObject, getRef, getRef, getRow, getRowId, getRowId, getShort, getShort, getSQLXML, getSQLXML, getStatement, getString, getString, getTime, getTime, getTime, getTime, getTimestamp, getTimestamp, getTimestamp, getTimestamp, getType, getUnicodeStream, getUnicodeStream, getURL, getURL, getWarnings, insertRow, isAfterLast, isBeforeFirst, isClosed, isFirst, isLast, last, moveToCurrentRow, moveToInsertRow, next, previous, refreshRow, relative, rowDeleted, rowInserted, rowUpdated, setFetchDirection, setFetchSize, updateArray, updateArray, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateAsciiStream, updateBigDecimal, updateBigDecimal, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBinaryStream, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBlob, updateBoolean, updateBoolean, updateByte, updateByte, updateBytes, updateBytes, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateCharacterStream, updateClob, updateClob, updateClob, updateClob, updateClob, updateClob, updateDate, updateDate, updateDouble, updateDouble, updateFloat, updateFloat, updateInt, updateInt, updateLong, updateLong, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNCharacterStream, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNClob, updateNString, updateNString, updateNull, updateNull, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull

從介面 java.sql.Wrapper 繼承的方法

isWrapperFor, unwrap

從介面 javax.sql.rowset.Joinable 繼承的方法

getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn

欄位詳細資訊

PUBLIC_XML_SCHEMA

static final String PUBLIC_XML_SCHEMA

為 WebRowSet 實作定義 XML 標記及其有效值的 XML 網要定義的公共標識符。

另請參見：

常數欄位值

SCHEMA_SYSTEM_ID

static final String SCHEMA_SYSTEM_ID

為 WebRowSet 實作定義 XML 標記及其有效值的 XML 網要定義的 URL。

另請參見：

常數欄位值

方法詳細資訊

readXml

void readXml(Reader reader)
             throws SQLException

從給定的 Reader 物件以其 XML 格式讀取 WebRowSet 物件。

參數：

reader - 用於填充此 WebRowSet 物件的 java.io.Reader 串流。

拋出：

SQLException - 如果發生資料庫存取錯誤

readXml

void readXml(InputStream iStream)
             throws SQLException,
                    IOException

讀取基於串流的 XML 輸入，以填充此 WebRowSet 物件。

參數：

iStream - 用來填充此 WebRowSet 物件的 java.io.InputStream

拋出：

SQLException - 如果發生資料源存取錯誤

IOException - 如果發生 IO 異常

writeXml

void writeXml(ResultSet rs,
              Writer writer)
              throws SQLException

使用給定 ResultSet 物件的內容填充此 WebRowSet 物件，並以 XML 格式將其資料、屬性和元資料寫入給定的 Writer 物件。

註：可以移動 WebRowSet 指針將內容寫出到 XML 資料源中。如果以這種方式實作，則在調用 writeXml() 之前指針必須先返回其位置。

參數：

rs - 用於填充此 WebRowSet 物件的 ResultSet 物件

writer - 要寫入的 java.io.Writer 物件。

拋出：

SQLException - 如果在以 XML 格式寫出 rowset 內容時發生錯誤

writeXml

void writeXml(ResultSet rs,
              OutputStream oStream)
              throws SQLException,
                     IOException

使用給定 ResultSet 物件的內容填充此 WebRowSet 物件，並以 XML 格式將其資料、屬性和元資料寫入給定的 OutputStream 物件。

註：可以移動 WebRowSet 指針將內容寫出到 XML 資料源中。如果以這種方式實作，則在調用 writeXml() 之前必須先將指針返回其位置。

參數：

rs - 用於填充此 WebRowSet 物件的 ResultSet 物件

oStream - 要寫入的 java.io.OutputStream

拋出：

SQLException - 如果發生資料源存取錯誤

IOException - 如果發生 IO 異常

writeXml

void writeXml(Writer writer)
              throws SQLException

以 XML 格式將此 WebRowSet 物件的資料、屬性和元資料寫入給定的 Writer 物件。

參數：

writer - 要寫入的 java.io.Writer 串流

拋出：

SQLException - 如果在將 rowset 內容寫出到 XML 時出錯

writeXml

void writeXml(OutputStream oStream)
              throws SQLException,
                     IOException

以 XML 格式將此 WebRowSet 物件的資料、屬性和元資料寫入給定的 OutputStream 物件。

參數：

oStream - 要寫入的 java.io.OutputStream 串流

拋出：

SQLException - 如果發生資料源存取錯誤

IOException - 如果發生 IO 異常