javax.sql.rowset
介面 CachedRowSet

所有父級介面：

Joinable, ResultSet, RowSet, Wrapper

所有已知子介面：

FilteredRowSet, JoinRowSet, WebRowSet

public interface CachedRowSet
extends RowSet, Joinable

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

Sun Microsystems 提供的 CachedRowSet 介面的參考實作是一個標準實作。開發人員可以按原樣使用此實作、可以擴展它，也可以選擇自己編寫此介面的實作。

CachedRowSet 物件是一個資料行的容器，可在記憶體中快取記憶體其各行，這使得進行操作時無需總是連接到資料源。此外，它還是一個 JavaBeans^TM 元件，是可滾動、可更新、可序列化的。CachedRowSet 物件通常包含結果集中的行，但它也可以包含任何具有表格式的檔案（如電子錶格）中的行。參考實作只支持從 ResultSet 物件中獲取資料，但是開發人員可以擴展 SyncProvider 實作，以提供對其他表格資料源的存取。

應用程序可以修改 CachedRowSet 物件中的資料，這些修改隨後可以被傳播回資料源。

CachedRowSet 物件是一個非連接 rowset，這意味著它只會短暫地連接其資料源。連接資料源發生在讀取資料以用各行填充自身，以及將更改傳播回其底層資料源時。其餘時間 CachedRowSet 物件是非連接的，包括修改它的資料時。非連接使 RowSet 物件更為簡潔，因此更容易傳遞給另一個元件。例如，非連接 RowSet 物件可以被序列化並通過導線傳遞到瘦客戶端 (thin client)，如個人數字助理（personal digital assistant，PDA）。

1.0 創建 CachedRowSet 物件

以下程式碼行使用參考實作 (RI) 中提供的預設 CachedRowSet 建構子來創建預設的 CachedRowSet 物件。

     CachedRowSetImpl crs = new CachedRowSetImpl();
 

這一新 CachedRowSet 物件的屬性設置為 BaseRowSet 物件的預設屬性，此外，它將 RIOptimisticProvider 物件作為其同步提供者。RIOptimisticProvider（RI 中包含的兩個 SyncProvider 實作之一）是在沒有指定同步提供者時，SyncFactory 單件 (singleton) 將提供的預設提供者。

SyncProvider 物件提供了帶有 reader 的（RowSetReader 物件）的 CachedRowSet 物件，用於從資料源讀取資料以便用該資料填充自身。可以實作 reader 從 ResultSet 物件或者表格式的檔案中讀取資料。SyncProvider 物件還提供了 writer（RowSetWriter 物件），用於同步在與底層資料源中的資料斷開連接時對 CachedRowSet 物件資料所做的任何更改。

可以實作 writer 以在檢查和避免衝突方面實施不同程度的關注。（如果使用某個值填充 rowset 後更改了資料源中的該值，則會發生衝突。）RIOptimisticProvider 實作假定衝突很少或沒有衝突，因此不設置鎖定。僅在沒有衝突時，它才使用取自 CachedRowSet 物件的值更新資料源。也可以實作其他 writer，使其始終可將修改後的資料寫入資料源，這可以通過不檢查衝突來實作，或者從另一個方面著手，即通過設置足夠的鎖定來防止對資料源中的資料進行更改。這兩種 writer 之間還可以有其他 writer 實作。

CachedRowSet 物件可以使用任何已向 SyncFactory 單件註冊的 SyncProvider 實作。通過調用以下程式碼行，應用程序可以找到已註冊的 SyncProvider 實作。

      java.util.Enumeration providers = SyncFactory.getRegisteredProviders();
 

CachedRowSet 物件可使用兩種方式來指定它將使用的 SyncProvider 物件。 向建構子提供實作名
以下程式碼行創建 CachedRowSet 物件 crs2，使用預設值初始化該物件，但其 SyncProvider 物件是指定的。

          CachedRowSetImpl crs2 = new CachedRowSetImpl(
                                 "com.fred.providers.HighAvailabilityProvider");
     

使用 CachedRowSet 方法 setSyncProvider 設置 SyncProvider
以下程式碼行為 crs 重置 SyncProvider 物件，該 CachedRowSet 物件是使用預設建構子創建的。

           crs.setSyncProvider("com.fred.providers.HighAvailabilityProvider");
      

SyncFactory 和 SyncProvider 的註釋。

2.0 從 CachedRowSet 物件獲取資料

從 CachedRowSet 物件獲取資料可使用繼承自 ResultSet 介面的獲取方法。以下範例（其中 crs 是一個 CachedRowSet 物件）演示了如何在各行中進行迭代，獲取每行中的列值。第一個範例使用以列號為參數的獲取方法；第二個範例使用以列名為參數的獲取方法。當 RowSet 物件的命令是 SELECT * FROM TABLENAME 形式時通常使用列號；當命令通過名稱指定列時則通常使用列名。

    while (crs.next()) {
        String name = crs.getString(1);
        int id = crs.getInt(2);
        Clob comment = crs.getClob(3);
        short dept = crs.getShort(4);
        System.out.println(name + "  " + id + "  " + comment + "  " + dept);
    }
 

    while (crs.next()) {
        String name = crs.getString("NAME");
        int id = crs.getInt("ID");
        Clob comment = crs.getClob("COM");
        short dept = crs.getShort("DEPT");
        System.out.println(name + "  " + id + "  " + comment + "  " + dept);
    }
 

2.1 獲取 RowSetMetaData

通過在 RowSetMetaData 物件上調用 ResultSetMetaData 和 RowSetMetaData 的方法，應用程序可以獲得有關 CachedRowSet 物件中各列的資訊。以下程式碼片斷（其中 crs 是一個 CachedRowSet 物件）展示了該過程。第一行使用關於 crs 中各列的資訊創建一個 RowSetMetaData 物件。繼承自 ResultSet 介面的方法 getMetaData 返回一個 ResultSetMetaData 物件，將該物件分派給變數 rsmd 前會將其強制轉換為 RowSetMetaData 物件。第二行查明 jrs 的列數，第三行獲得存儲在 jrs 第二列中 JDBC 型別的值。

     RowSetMetaData rsmd = (RowSetMetaData)crs.getMetaData();
     int count = rsmd.getColumnCount();
     int type = rsmd.getColumnType(2);
 

RowSetMetaData 介面與 ResultSetMetaData 介面有兩方面不同。

• 它包括設置方法：當使用取自不同 ResultSet 物件的資料填充 RowSet 物件時，該 RowSet 物件在內部使用這些方法。

• 它包含較少的獲取方法：某些 ResultSetMetaData 方法無法應用到 RowSet 物件。例如，不會應用那些獲取某個列值是可寫入的還是只讀的方法，因為 RowSet 物件的所有列要麼是可寫入的，要麼是只讀的，這取決於該 rowset 是否可更新。

註：要返回 RowSetMetaData 物件，實作必須覆寫 java.sql.ResultSet 中定義的 getMetaData() 方法返回 RowSetMetaData 物件。

3.0 更新 CachedRowSet 物件

更新 CachedRowSet 物件與更新 ResultSet 物件類似，但是因為更新 rowset 時它並未連接到其資料源，所以必須執行額外的步驟才能使更改在底層資料源中生效。調用方法 updateRow 或 insertRow 後，CachedRowSet 物件還必須調用方法 acceptChanges 使更新寫入資料源。以下範例（其中指針在 CachedRowSet 物件 crs 中的行上）顯示了更新當前行中兩個列值並同樣更新 RowSet 物件的底層資料源所需的程式碼。

     crs.updateShort(3, 58);
     crs.updateInt(4, 150000);
     crs.updateRow();
     crs.acceptChanges();
 

下一個範例演示了移至插入行、在插入行上建構新行、將新行插入 rowset，然後調用方法 acceptChanges 將新行添加到底層資料源。注意，與獲取方法一樣，更新方法可以採用列索引或列名來指定所操作的列。

     crs.moveToInsertRow();
     crs.updateString("Name", "Shakespeare");
     crs.updateInt("ID", 10098347);
     crs.updateShort("Age", 58);
     crs.updateInt("Sal", 150000);
     crs.insertRow();
     crs.moveToCurrentRow();
     crs.acceptChanges();
 

註：insertRow() 方法在何處插入 CachedRowSet 物件的插入行內容是由實作定義的。CachedRowSet 介面的參考實作緊隨當前行插入新行，但也可以實作為在任何其他位置插入新行。

有關這些範例的另一個注意點是它們使用方法 acceptChanges 的方式。通過內部調用 RowSet 物件的 writer 將這些更改寫入資料源，從而將 CachedRowSet 物件中的更改傳播回底層資料源的正是此方法。為此，writer 不得不承受建立到資料源的連接所帶來的開銷。上述兩個程式碼片斷在調用 updateRow 或 insertRow 後立即調用方法 acceptChanges。但是，如果更改了多個行，則更高效的做法是在調用所有 updateRow 和 insertRow 後再調用 acceptChanges。如果只調用 acceptChanges 一次，則只需要建立一個連接。

4.0 更新底層資料源

執行 acceptChanges 方法時，在後台調用 CachedRowSet 物件的 writer（一個 RowSetWriterImpl 物件），以便將對 rowset 所作的更改寫入底層資料源。實作該 writer 以建立到資料源的連接並寫入更新。

可通過 SyncProvider 介面的實作提供 writer，這已第 1 部分“創建 CachedRowSet 物件”中討論。預設的參考實作提供者 RIOptimisticProvider 會實作其 writer 使用樂觀共時控制 (optimistic concurrency control) 機制。也就是說，在 rowset 與資料庫斷開時它不對底層資料庫維持任何鎖定，在將資料寫入資料源之前它只是檢查是否有衝突。如果存在衝突，則不向資料源寫入任何內容。

SyncProvider 類別提供的 reader/writer 設施是可插入的，允許自定義資料的獲取和更新。如果需要其他的共時控制機制，可使用方法 setSyncProvider 插入其他 SyncProvider 實作。

要使用樂觀共時控制例程，RIOptismisticProvider 要同時維護其當前值及其原始值（剛好位於當前值之前的值）。注意，如果沒有對 RowSet 物件中的資料進行任何更改，則其當前值和原始值相同，都是最初填充 RowSet 物件時使用的值。但是，一旦更改了 RowSet 物件中的任何值，當前值和原始值就不同了，儘管此時原始值仍是最初的值。隨著後續對 RowSet 物件中的資料進行更改，其原始值和當前值仍保持不同，但是其原始值將是前一個當前值。

關注原始值允許 writer 對 RowSet 物件的原始值和資料庫中的值進行比較。如果資料庫中的值與 RowSet 物件的原始值不同，則意味著資料庫中的值已經更改，出現了衝突。writer 是否檢查衝突、檢查的程度如何，以及它如何處理衝突都取決於它的實作方式。

5.0 註冊和通知偵聽器

作為 JavaBeans 元件，參與 JavaBeans 事件模型的所有 rowset 都繼承了用來註冊偵聽器和用來通知這些偵聽器 BaseRowSet 類別中發生更改的各種方法。CachedRowSet 物件的偵聽器是一個元件，只要 rowset 中發生更改，它就應得到通知。例如，如果 CachedRowSet 物件包含查詢的結果，並且這些結果將以表格和條形圖之類別的形式顯示，則可以向 rowset 將該表格和條形圖註冊為偵聽器，這樣它們可以更新以反映各種更改。要成為偵聽器，表格和條形圖類別必須實作 RowSetListener 介面。然後可將它們添加到 CachedRowSet 物件的偵聽器列表，如以下程式碼行所示。

 
    crs.addRowSetListener(table);
    crs.addRowSetListener(barGraph);
 

每個移動指針或更改資料的 CachedRowSet 方法也將更改通知已註冊的偵聽器，所以當 crs 中發生更改時 table 和 barGraph 將得到通知。

6.0 向瘦客戶端傳遞資料

使用 CachedRowSet 物件的主要原因之一是要在應用程序的不同元件之間傳遞資料。因為 CachedRowSet 物件是可序列化的，所以可使用它（舉例來說）將運行於伺服器環境的企業 JavaBeans 元件執行查詢的結果通過網路發送到運行於 web 瀏覽器的客戶端。

由於 CachedRowSet 物件是非連接的，所以和具有相同資料的 ResultSet 物件相比更為簡潔。因此，它特別適於向瘦客戶端（如 PDA）發送資料，這種瘦客戶端由於資源限制或安全考慮而不適於使用 JDBC 驅動程序。所以 CachedRowSet 物件可提供一種“獲取各行”的方式而無需實作全部 JDBC API。

7.0 滾動和更新

CachedRowSet 物件的第二個主要用途是為那些本身不提供滾動和更新的 ResultSet 物件提供這些功能。換句話說，當 DBMS 不提供對滾動和更新的完全支持時，可使用 CachedRowSet 物件擴充啟用 JDBC 技術的驅動程序（以下稱為“JDBC 驅動程序”）的功能。要使不可滾動和只讀的 ResultSet 物件變得可滾動和可更新，開發人員只需創建一個使用該 ResultSet 物件的資料所填充的 CachedRowSet 物件即可。以下程式碼片斷演示了這一過程，其中 stmt 是一個 Statement 物件。

    ResultSet rs = stmt.executeQuery("SELECT * FROM EMPLOYEES");
    CachedRowSetImpl crs = new CachedRowSetImpl();
    crs.populate(rs);
 

現在物件 crs 與物件 rs 一樣，也包含了取自表 EMPLOYEES 的資料。不同的是 crs 的指針可以向前、向後移動，或者移動到特定行，即使 rs 的指針只能向前移動也是如此。此外，即使 rs 是不可更新的，crs 也將是可更新的，因為在預設情況下，CachedRowSet 物件是可滾動和可更新的。

總之，可將 CachedRowSet 物件簡單地看成是一個非連接的行集合，這些行將快取記憶體在資料源外部。由於它比較小並且是可序列化的，所以它可以輕鬆地通過導線發送，並且非常適合於向瘦客戶端發送資料。但是 CachedRowSet 物件也有局限性：它的大小限制在它一次可在記憶體中存儲的資料量範圍內。

8.0 獲得通用資料存取

CachedRowSet 類別的另一個優勢在於它能夠從關聯型資料庫以外各種資料源獲取並存儲資料。可以實作 rowset 的 reader 讀取任何表格資料源（包括電子錶格或平面檔案）的資料，並用該資料填充其 rowset。因為 CachedRowSet 物件及其元資料都可以從頭創建，所以充當 rowset 處理器的元件可以使用此功能來創建一個套件含非 SQL 資料源資料的 rowset。但是，大部分情況下，希望 CachedRowSet 物件包含使用 JDBC API 從 SQL 資料庫中獲取的資料。

9.0 設置屬性

所有 rowset 都維護一個屬性集，通常使用某種工具來設置這些屬性。rowset 具有的屬性的數量和種類別各不相同，這取決於 rowset 的用途及其獲得資料的方式。例如，從 ResultSet 物件獲得其資料的 rowset 需要設置那些建立資料庫連接所需的屬性。如果某個 rowset 使用 DriverManager 設施建立連接，則它需要設置一個標識合適驅動程序的 JDBC URL 屬性，還需要設置那些提供使用者名和密碼的屬性。另一方面，如果 rowset 使用 DataSource 物件建立連接（這是首選的方法），則它無需設置 JDBC URL 屬性。但是它需要設置用於資料源邏輯名、使用者名和密碼的屬性。

註：要使用 DataSource 物件建立連接，該 DataSource 物件必須已經向使用 Java Naming and Directory Interface^TM (JNDI) API 的命名服務註冊。通常由具有系統管理員資格的人員完成此註冊。

為了能夠使用資料庫的資料填充，rowset 需要設置 command 屬性。此屬性是一種 PreparedStatement 物件的查詢，該物件允許查詢具有在運行時（而不是設計時）設置的參數佔位符。要用各種值設置這些佔位符參數，rowset 要為設置每種資料型別的值提供設置方法，類似於 PreparedStatement 介面提供的設置方法。

以下程式碼片斷展示了如何設置 CachedRowSet 物件 crs 的 command 屬性。注意，如果使用某種工具設置屬性，則這就是該工具應使用的程式碼。

    crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS " +
                   "WHERE CREDIT_LIMIT > ? AND REGION = ?");
 

用於設置該命令佔位符參數的值被包含在 RowSet 物件的 params 欄位中，該欄位是一個 Vector 物件。CachedRowSet 類別為設置其 params 欄位中的元素提供了一組設置方法。以下程式碼片斷演示了如何設置前一個範例查詢中的兩個參數。

    crs.setInt(1, 5000);
    crs.setString(2, "West");
 

params 欄位現在包含兩個元素，每個元素都是一個兩元素長的陣列。第一個元素是參數號；第二個元素是要設置的值。在這種情況下，params 的第一個元素是 1，5000，第二個元素是 2，"West"。當應用程序調用方法 execute 時，它會依次調用此 RowSet 物件的 reader，該 reader 會依次調用其 readData 方法。作為實作的一部分，readData 將獲得 params 中的值並使用這些值設置命令的佔位符參數。以下程式碼片斷說明了在獲得 Connection 物件 con 後 reader 如何執行此操作。

    PreparedStatement pstmt = con.prepareStatement(crs.getCommand());
    reader.decodeParams();
    // decodeParams figures out which setter methods to use and does something
    // like the following:
    //    for (i = 0; i < params.length; i++) {
    //        pstmt.setObject(i + 1, params[i]);
    //    }
 

這裡用於 crs 的命令是查詢 "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS WHERE CREDIT_LIMIT > 5000 AND REGION = "West"。readData 方法使用以下程式碼行執行此命令後，它會獲得 rs 的資料，該資料用於填充 crs。

     ResultSet rs = pstmt.executeQuery();
 

上述程式碼片斷說明了在後台進行的操作；這些操作不會出現在應用程序中，因為應用程序不會調用 readData 和 decodeParams 之類別的方法。相反，以下程式碼片斷展示了應用程序可能執行的操作。它設置 rowset 的命令、設置 command 屬性並執行該命令。只需調用 execute 方法，就可使用從表 CUSTOMERS 請求的資料產生 crs。

    crs.setCommand("SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS" +
                   "WHERE CREDIT_LIMIT > ? AND REGION = ?");
    crs.setInt(1, 5000);
    crs.setString(2, "West");
    crs.execute();
 

10.0 分頁資料

因為 CachedRowSet 物件在記憶體中存儲資料，所以它在任一時間可以包含的資料量是由可用的記憶體量決定的。要避開此限制，CachedRowSet 物件可以資料塊（稱為頁）的形式從 ResultSet 物件中獲取資料。要利用此機制，應用程序應使用方法 setPageSize 設置一頁中要包括的行數。換句話說，如果頁大小設置為 5，則一次從資料源中獲取一個 5 行的資料塊。應用程序也可選擇設置一次可獲取的最大行數。如果最大行數設置為 0，或者未設置最大行數，則對一次獲取的行數沒有限制。

設置各個屬性後，必須使用方法 populate 或方法 execute 用資料填充 CachedRowSet 物件。以下程式碼行演示了如何使用方法 populate。注意，該方法的這種形式採用兩個參數，ResultSet 句柄和 ResultSet 物件中的行，從該行開始獲取各行。

     CachedRowSet crs = new CachedRowSetImpl();
     crs.setMaxRows(20);
     crs.setPageSize(4);
     crs.populate(rsHandle, 10);
 

運行此程式碼時，將使用 rsHandle 中從第 10 行開始的 4 行資料填充 crs。

下一個程式碼片斷展示了如何使用方法 execute 填充 CachedRowSet 物件，該方法可以採用 Connection 物件作為一個參數，也可以不採用。此程式碼向 execute 傳遞 Connection 物件 conHandle。

注意，以下程式碼片斷和上述程式碼片斷有兩處差別。首先，沒有調用方法 setMaxRows，所以沒有對 crs 可以包含的行數設置限制。（記住，對於 crs 在記憶體中可以存儲的資料量，總是有一個最高限制。）第二個差別是不能向方法 execute 傳遞 ResultSet 物件中起始獲取行的行號。此方法始終從第一行開始獲取。

     CachedRowSet crs = new CachedRowSetImpl();
     crs.setPageSize(5);
     crs.execute(conHandle);
 

運行此程式碼後，crs 將包含由 crs 的命令所產生的 ResultSet 物件中的 5 行資料。crs 的 writer 將使用 conHandle 連接資料源並執行 crs 的命令。然後應用程序就能夠在 crs 中的資料上進行操作，方式與在任何其他 CachedRowSet 物件的資料上進行操作的方式相同。

要存取下一頁（資料塊），應用程序可調用方法 nextPage。此方法創建新的 CachedRowSet 物件並用下一頁的資料填充。例如，假定 CachedRowSet 物件的命令返回一個具有 1000 行資料的 ResultSet 物件 rs。如果頁大小設置為 100，則首次調用方法 nextPage 將創建一個套件含 rs 前 100 行的 CachedRowSet 物件。在使用這前 100 行的資料執行完所需的操作後，應用程序可以再次調用方法 nextPage 創建另一個帶有 rs 第二個 100 行資料的 CachedRowSet 物件。第一個 CachedRowSet 物件中的資料不再存在於記憶體中，因為它已被第二個 CachedRowSet 物件的資料替換了。調用方法 nextPage 10 次後，第十個 CachedRowSet 物件將包含 rs 最後 100 行存儲在記憶體中的資料。在任意給定時間，記憶體中僅存儲一個 CachedRowSet 物件的資料。

只要當前頁不是各行的最後一頁，方法 nextPage 就返回 true，沒有其他頁時，則返回 false。因此，可在 while 循環中使用它來獲取所有頁，正如在以下程式碼行中所演示的。

     CachedRowSet crs = CachedRowSetImpl();
     crs.setPageSize(100);
     crs.execute(conHandle);

     while(crs.nextPage()) {
         while(crs.next()) {
             . . . // operate on chunks (of 100 rows each) in crs, 
                   // row by row
         }
     }
 

運行此程式碼片斷後，應用程序會遍歷所有 1000 行，但是每次記憶體中的資料只有 100 行。

CachedRowSet 介面還定義了方法 previousPage。正如方法 nextPage 類似於 ResultSet 方法 next，方法 previousPage 也類似於 ResultSet 方法 previous。與方法 nextPage 類似，previousPage 創建一個 CachedRowSet 物件，包含作為頁大小設置的行數。因此，（舉例來說）方法 previousPage 可用在上述程式碼片斷末尾的 while 循環中，以從最後一頁開始逆向遍歷到第一頁。方法 previousPage 也與 nextPage 類似，因為它也可以用在 while 循環中，不同之處在於它是在前面還有頁時返回 true，前面沒有頁時返回 false。

通過將指針定位於每頁最後一行的後面（如以下程式碼片斷所執行的），方法 previous 就可以在每頁中從最後一行遍歷到第一行。程式碼也可將指針置於每頁第一行的前面，然後在 while 循環中使用 next 方法，以在每頁中從最第一行遍歷到最後一行。

以下程式碼片斷假定是前一個程式碼片斷的繼續，這意味著第十個 CachedRowSet 物件的指針位於最後一行。程式碼將指針移到最後一行的後面，這樣第一次調用方法 previous 會將指針放回到最後一行上。遍歷最後一頁（CachedRowSet 物件 crs）的所有行後，程式碼接著會進入 while 循環以獲得第九頁、向後遍歷各行、轉至第八頁、向後遍歷各行，依此類別推，直到第一頁的第一行為止。

     crs.afterLast();
     while(crs.previous())  {
         . . . // navigate through the rows, last to first
     {
     while(crs.previousPage())  {
         crs.afterLast();
         while(crs.previous())  {
             . . . // go from the last row to the first row of each page
         }
     }
 

欄位摘要

static boolean

COMMIT_ON_ACCEPT_CHANGES 導致在調用 acceptChanges() 時，CachedRowSet 物件的 SyncProvider 提交更改。

從介面 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	acceptChanges() 將對此 CachedRowSet 物件所做的行更新、插入以及刪除更改傳播到底層資料源。
void	acceptChanges(Connection con) 將所有行更新、插入以及刪除更改傳播到支持此 CachedRowSet 物件的資料源，使用指定的 Connection 物件建立到資料源的連接。
boolean	columnUpdated(int idx) 指示此 CachedRowSet 物件當前行中的指定列是否已更新。
boolean	columnUpdated(String columnName) 指示此 CachedRowSet 物件當前行中的指定列是否已更新。
void	commit() 每個 CachedRowSet 物件的 SyncProvider 都包含一個取自 ResultSet 的 Connection 物件或傳遞到其建構子的 JDBC 屬性。
CachedRowSet	createCopy() 創建一個 RowSet 物件，它是此 CachedRowSet 物件中資料的深層副本。
CachedRowSet	createCopyNoConstraints() 創建一個 CachedRowSet 物件，它是此 CachedRowSet 物件資料的深層副本，但是獨立於此 CachedRowSet 物件。
CachedRowSet	createCopySchema() 創建一個 CachedRowSet 物件，它是此 CachedRowSet 物件的空副本。
RowSet	createShared() 返回一個新的 RowSet 物件，支持該物件的資料與此 CachedRowSet 物件的相同。
void	execute(Connection conn) 用資料填充此 CachedRowSet 物件，使用給定的連接來產生從中讀取資料的結果集。
int[]	getKeyColumns() 返回一個套件含一個或多個列號的陣列，這些列號指示了形成某個鍵的列，該鍵唯一地標識了此 CachedRowSet 物件中的某個行。
ResultSet	getOriginal() 返回一個套件含此 CachedRowSet 物件原始值的 ResultSet 物件。
ResultSet	getOriginalRow() 返回一個只包含此 CachedRowSet 物件當前行原始值的 ResultSet 物件。
int	getPageSize() 返回 CachedRowSet 物件的頁大小。
RowSetWarning	getRowSetWarnings() 獲取此 RowSet 物件上的調用報告的第一個警告。
boolean	getShowDeleted() 獲取一個 boolean 值，該值指示標記為刪除的行是否會出現在當前行集合中。
SyncProvider	getSyncProvider() 獲取此 CachedRowSet 物件的 SyncProvider 實作。
String	getTableName() 返回創建此 CachedRowSet 物件時所用物件（表）的標識符。
boolean	nextPage() 逐個增加 CachedRowSet 的當前頁。
void	populate(ResultSet data) 使用取自給定 ResultSet 物件的資料填充此 CachedRowSet 物件。
void	populate(ResultSet rs, int startRow) 使用取自給定 ResultSet 物件的資料填充此 CachedRowSet 物件。
boolean	previousPage() 逐個減少 CachedRowSet 的當前頁。
void	release() 釋放此 CachedRowSet 物件的當前內容並將 rowSetChanged 事件發送到所有已註冊偵聽器。
void	restoreOriginal() 將此 CachedRowSet 物件還原成其原始值，即執行上一組更改前的值。
void	rollback() 每個 CachedRowSet 物件的 SyncProvider 都包含一個取自原始 ResultSet 的 Connection 物件或傳遞給它的 JDBC 屬性。
void	rollback(Savepoint s) 每個 CachedRowSet 物件的 SyncProvider 都包含一個取自原始 ResultSet 的 Connection 物件或傳遞給它的 JDBC 屬性。
void	rowSetPopulated(RowSetEvent event, int numRows) 通知已註冊偵聽器給定 RowSetEvent 物件中的某個 RowSet 物件已經填充了多個附加行。
void	setKeyColumns(int[] keys) 使用給定的列號陣列設置此 CachedRowSet 物件的 keyCols 欄位，它形成了唯一標識此 CachedRowSet 物件中某個行的鍵。
void	setMetaData(RowSetMetaData md) 使用給定的 RowSetMetaData 物件設置此 CachedRowSet 物件的元資料。
void	setOriginalRow() 將此 CachedRowSet 物件中的當前行設置為原始行。
void	setPageSize(int size) 設置 CachedRowSet 物件的頁大小。
void	setShowDeleted(boolean b) 將屬性 showDeleted 設置為給定的 boolean 值，它確定標記為刪除的行是否會出現在當前行集合中。
void	setSyncProvider(String provider) 將此 CachedRowSet 物件的 SyncProvider 物件設置為指定的提供者。
void	setTableName(String tabName) 將派生此 CachedRowSet 物件的表的標識符設置為給定的表名。
int	size() 返回此 CachedRowSet 物件中的行數。
Collection<?>	toCollection() 將此 CachedRowSet 物件轉換成一個 Collection 物件，它包含此 CachedRowSet 物件的所有資料。
Collection<?>	toCollection(int column) 將此 CachedRowSet 物件中的指定列轉換成一個 Collection 物件。
Collection<?>	toCollection(String column) 將此 CachedRowSet 物件中的指定列轉換成一個 Collection 物件。
void	undoDelete() 取消刪除當前行並通知偵聽器已更改了某個行。
void	undoInsert() 如果已經插入了當前行，則立即將它從此 CachedRowSet 物件移除，同樣要通知偵聽器已更改了某個行。
void	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

欄位詳細資訊

COMMIT_ON_ACCEPT_CHANGES

static final boolean COMMIT_ON_ACCEPT_CHANGES

導致在調用 acceptChanges() 時，CachedRowSet 物件的 SyncProvider 提交更改。如果設置為 false，則在調用 CachedRowSet 介面的某個事務方法之前，不提交更改。

另請參見：

commit(), rollback(), 常數欄位值

方法詳細資訊

populate

void populate(ResultSet data)
              throws SQLException

使用取自給定 ResultSet 物件的資料填充此 CachedRowSet 物件。

當應用程序具有到開放 ResultSet 物件的連接時，此方法可作為 execute 方法的替代方法。使用方法 populate 比使用無參數的 execute 方法要更為高效，因為它不用打開新的連接和重新執行此 CachedRowSet 物件的命令。與採用 ResultSet 物件的 execute 相比，使用 populate 方法要更為便捷。

參數：

data - 一個 ResultSet 物件，它包含要讀入到此 CachedRowSet 物件中的資料

拋出：

SQLException - 如果提供的 ResultSet 物件為 null 或者此 CachedRowSet 物件無法獲取關聯的 ResultSetMetaData 物件

另請參見：

execute(java.sql.Connection), ResultSet, ResultSetMetaData

execute

void execute(Connection conn)
             throws SQLException

用資料填充此 CachedRowSet 物件，使用給定的連接來產生從中讀取資料的結果集。此方法應該關閉它所創建的所有資料庫連接，以確保此 CachedRowSet 物件是斷開連接的，它從其資料源讀取資料或向其資料源寫入資料時除外。

此 CachedRowSet 物件的 reader 將使用 conn 來建立到資料源的連接，以便能夠執行 rowset 的命令，並將資料從得到的 ResultSet 物件讀入此 CachedRowSet 物件中。此方法在填充此 CachedRowSet 物件後同樣會關閉 conn。

如果調用此方法時已經填充了實作，則設置（重置）內容和元資料。同樣，如果在調用方法 acceptChanges 來提交顯式的更新之前調用此方法，則這些更新會丟失。

參數：

conn - 帶有有效屬性的標準 JDBC Connection 物件

拋出：

SQLException - 如果提供了無效的 Connection 物件或在建立到資料源的連接過程中發生錯誤

另請參見：

populate(java.sql.ResultSet), Connection

acceptChanges

void acceptChanges()
                   throws SyncProviderException

將對此 CachedRowSet 物件所做的行更新、插入以及刪除更改傳播到底層資料源。

此方法調用此 CachedRowSet 物件的 writer 在後台完成工作。標準的 CachedRowSet 實作應該使用 SyncFactory 單件來獲得 SyncProvider 實例，以提供一個 RowSetWriter 物件 (writer)。該 writer 會嘗試將在此 CachedRowSet 物件中所做的更改傳播回資料源。

方法 acceptChanges 成功執行後，除了將更改寫入資料源外，它還使當前行中的值成為原始行中的值。

根據所用 SyncProvider 實作的同步級別，writer 將原始值與資料源中的值進行比較，以檢查是否有衝突。如果有衝突，則 RIOptimisticProvider 實作可能會拋出 SyncProviderException 並且不向資料源中寫入任何內容。

應用程序可以選擇捕獲 SyncProviderException 物件並獲取它所包含的 SyncResolver 物件。SyncResolver 物件逐行列出衝突，並在資料源上設置鎖定，以避免在解決當前衝突的同時出現更多衝突。此外，對於每個衝突，它還提供了各種方法來檢查該衝突和設置在資料源中應該保持不變的值。解決所有衝突後，應用程序必須再次調用 acceptChanges 方法，將已解決衝突的值寫入資料源。如果資料源中的所有值都已經是保持不變的值，則方法 acceptChanges 不執行任何操作。

某些提供者實作可以使用鎖定來確保沒有衝突。在這種情況下，可以保證在調用方法 acceptChanges 時，writer 能成功地將更改寫入資料源。調用方法 updateRow、insertRow 或 deleteRow 後可立即調用此方法，但是在完成所有更改後只調用此方法一次要更為高效，這樣只需要建立一個連接。

註：acceptChanges() 方法將確定 COMMIT_ON_ACCEPT_CHANGES 是否設置為 true。如果設置為 true，則將同步中的所有更新都提交給資料源。否則應用程序必須顯式地調用恰當的 commit() 或 rollback() 方法。

拋出：

SQLException - 如果指針位於插入行上

SyncProviderException - 如果底層同步提供者的 writer 無法將更新寫回資料源

另請參見：

acceptChanges(java.sql.Connection), RowSetWriter, SyncFactory, SyncProvider, SyncProviderException, SyncResolver

acceptChanges

void acceptChanges(Connection con)
                   throws SyncProviderException

將所有行更新、插入以及刪除更改傳播到支持此 CachedRowSet 物件的資料源，使用指定的 Connection 物件建立到資料源的連接。

另一種形式的 acceptChanges 方法不傳遞連接，因為它使用已經定義在 RowSet 物件內的 Connection 物件，該物件是最初用來填充 RowSet 的連接。

acceptChanges 方法的這一形式與無參數形式類似；但與其他形式不同的是，此形式只能在底層資料源是一個 JDBC 資料源時使用。SyncProvider 必須使用已更新的 Connection 屬性來重置 RowSetWriter 配置，以確保 CachedRowSet 物件的內容是正確同步的。

方法 acceptChanges 成功執行後，除了將更改寫入資料源外，它還使當前行中的值與原始行中的值相同。

根據所用 SyncProvider 實作的同步級別，writer 將原始值與資料源中的值進行比較，以檢查是否有衝突。如果有衝突，則 RIOptimisticProvider 實作可能會拋出 SyncProviderException 並且不向資料源中寫入任何內容。

應用程序可以選擇捕獲 SyncProviderException 物件並獲取它所包含的 SyncResolver 物件。SyncResolver 物件逐行列出衝突，並在資料源上設置鎖定，以避免在解決當前衝突的同時出現更多衝突。此外，對於每個衝突，它還提供了各種方法來檢查該衝突和設置在資料源中應該保持不變的值。解決所有衝突後，應用程序必須再次調用 acceptChanges 方法，將已解決衝突的值寫入資料源。如果資料源中的所有值都已經是保持不變的值，則方法 acceptChanges 不執行任何操作。

某些提供者實作可以使用鎖定來確保沒有衝突。在這種情況下，可以保證在調用方法 acceptChanges 時，writer 能成功地將更改寫入資料源。調用方法 updateRow、insertRow 或 deleteRow 後可立即調用此方法，但是在完成所有更改後只調用此方法一次要更為高效，這樣只需要建立一個連接。

註：acceptChanges() 方法將確定 COMMIT_ON_ACCEPT_CHANGES 是否設置為 true。如果設置為 true，則將同步中的所有更新都提交給資料源。否則應用程序必須顯式地調用相應的 commit 或 rollback 方法。

參數：

con - 標準的 JDBC Connection 物件

拋出：

SQLException - 如果指針位於插入行上

SyncProviderException - 如果底層同步提供者的 writer 無法將更新寫回資料源

另請參見：

acceptChanges(), RowSetWriter, SyncFactory, SyncProvider, SyncProviderException, SyncResolver

restoreOriginal

void restoreOriginal()
                     throws SQLException

將此 CachedRowSet 物件還原成其原始值，即執行上一組更改前的值。如果未對 rowset 進行任何更改或者只有一組更改，則原始值是填充此 CachedRowSet 物件時使用的值；否則原始值是正好在其當前值之前的值。

調用此方法時，CachedRowSet 實作必須確保對當前 rowset 實例所做的所有更新、插入和刪除都已由之前的值取代。此外，應該將指針重置到第一行，並且應該觸發一個 rowSetChanged 事件，以通知所有已註冊偵聽器。

拋出：

SQLException - 如果將此 CachedRowSet 物件的當前值回滾到其之前的值時發生錯誤

另請參見：

RowSetListener.rowSetChanged(javax.sql.RowSetEvent)

release

void release()
             throws SQLException

釋放此 CachedRowSet 物件的當前內容並將 rowSetChanged 事件發送到所有已註冊偵聽器。丟棄所有顯式更新，調用此方法後 rowset 不包含任何行。不與底層資料源進行任何交互，並且所有 rowset 內容、元資料和內容更新都應該是不可恢復的。

完全清除此 CachedRowSet 物件的內容和關聯的更新之前，此物件應該保持鎖定，從而防止其他持有對此 RowSet 物件參考的元件進行“髒”讀。此外，在所有讀取此 CachedRowSet 物件的元件完成其讀取之前，不能釋放物件的內容。觸發 rowSetChanged 事件後，此 CachedRowSet 物件應該返回到正常行為。

保留元資料（包括 JDBC 屬性和 Synchronization SPI 屬性）以備後用。各種屬性（如 command 屬性）與原始資料源（此 CachedRowSet 物件最初根據該資料源創建）相關是很重要的。

此方法清空 rowset，這與 close 方法不同，後者將整個 rowset 標記為可恢復以允許垃圾回收器回收 rowset 的 Java VM 資源。

拋出：

SQLException - 如果清空此 CachedRowSet 物件的內容時發生錯誤

另請參見：

RowSetListener.rowSetChanged(javax.sql.RowSetEvent), ResultSet.close()

undoDelete

void undoDelete()
                throws SQLException

取消刪除當前行並通知偵聽器已更改了某個行。調用此方法後，不再將當前行標記為刪除。在 rowset 生命週期中的任何時候都可調用此方法。

此外，可以通過調整指針的位置取消多個行刪除，調整指針位置可使用任何指針位置控制方法，比如：

• CachedRowSet.absolute
• CachedRowSet.first
• CachedRowSet.last

拋出：

SQLException - 如果 (1) 尚未刪除當前行或 (2) 指針在插入行上、在第一行的前面或在最後一行的後面

另請參見：

undoInsert(), ResultSet.cancelRowUpdates()

undoInsert

void undoInsert()
                throws SQLException

如果已經插入了當前行，則立即將它從此 CachedRowSet 物件移除，同樣要通知偵聽器已更改了某個行。在 rowset 生命週期中的任何時候都可調用此方法，如果當前行在異常限制範圍內（見下文），則它將取消當前行的行插入。

此外，可以通過調整指針的位置取消多個行插入，調整指針位置可使用任何指針位置控制方法，比如：

• CachedRowSet.absolute
• CachedRowSet.first
• CachedRowSet.last

拋出：

SQLException - 如果 (1) 尚未插入當前行或者 (2) 指針在第一行的前面、最後一行的後面或在插入行上

另請參見：

undoDelete(), ResultSet.cancelRowUpdates()

undoUpdate

void undoUpdate()
                throws SQLException

如果已經修改了行，則立即逆轉上一次更新操作。可調用此方法逆轉所有列上的更新，直到行中的所有更新都已回滾到其上一次同步 (acceptChanges) 或填充之前的狀態。執行對插入行的更新時也可以調用此方法。

undoUpdate 可以在 rowset 生命週期中的任何時間調用；但是，在發生同步之後，此方法在發生對 rowset 資料的更多修改之前將無效。

拋出：

SQLException - 如果此 CachedRowSet 物件中指針在第一行的前面或最後一行的後面。

另請參見：

undoDelete(), undoInsert(), ResultSet.cancelRowUpdates()

columnUpdated

boolean columnUpdated(int idx)
                      throws SQLException

指示此 CachedRowSet 物件當前行中的指定列是否已更新。

參數：

idx - 一個 int 值，標識要檢查更新的列

返回：

如果已對指定列進行可見更新，則返回 true；否則返回 false

拋出：

SQLException - 如果指針在插入行上、在第一行的前面或者在最後一行的後面

另請參見：

DatabaseMetaData.updatesAreDetected(int)

columnUpdated

boolean columnUpdated(String columnName)
                      throws SQLException

指示此 CachedRowSet 物件當前行中的指定列是否已更新。

參數：

columnName - 一個 String 物件，提供要檢查更新的列名

返回：

如果已對該列進行可見更新，則返回 true；否則返回 false

拋出：

SQLException - 如果指針在插入行上、在第一行的前面或者在最後一行的後面

另請參見：

DatabaseMetaData.updatesAreDetected(int)

toCollection

Collection<?> toCollection()
                           throws SQLException

將此 CachedRowSet 物件轉換成一個 Collection 物件，它包含此 CachedRowSet 物件的所有資料。實作在如何表示此 Collection 物件上有一定的自由度，這是由於 Collection 框架的抽象本質所造成的。必須用通用 Collection 實作或專用的 Collection 實作（如 TreeMap 物件或 Vector 物件）來完全表示每一行。SQL NULL 列值必須表示為 Java 程式語言中的 null。

CachedRowSet 介面的標準參考實作對 rowset 使用 TreeMap 物件，每行中的值都包含在 Vector 物件中。預期多數實作都是如此。

TreeMap 型別的 collection 可保證按照鍵升序，並根據鍵類別的自然順序存儲映射。每個鍵參考一個與 RowSet 物件的一行相對應的 Vector 物件。因此，每個 Vector 物件的大小必須與 RowSet 物件中的列數完全相等。TreeMap collection 使用的鍵由實作決定，實作可以選擇利用內部 RowSet 表結構內可用的已設置鍵，這些鍵已經設置在 RowSet 物件本身或底層 SQL 資料上。

返回：

一個 Collection 物件，它包含此 CachedRowSet 物件中每一行的值

拋出：

SQLException - 如果產生該 collection 時發生錯誤

另請參見：

toCollection(int), toCollection(String)

toCollection

Collection<?> toCollection(int column)
                           throws SQLException

將此 CachedRowSet 物件中的指定列轉換成一個 Collection 物件。實作在如何表示此 Collection 物件上有一定的自由度，這是由於 Collection 框架的抽象本質所造成的。應該用通用 Collection 實作或專用的 Collection 實作（如 Vector 物件）來完全表示每個列值。SQL NULL 列值必須表示為 Java 程式語言中的 null。

標準的參考實作使用 Vector 物件包含列值，預期多數實作都是如此。如果使用 Vector 物件，則其大小必須與此 CachedRowSet 物件中的行數完全相等。

參數：

column - 一個 int 值，指示值要用 Collection 物件來表示的列

返回：

一個 Collection 物件，它包含存儲在此 CachedRowSet 物件指定列中的值

拋出：

SQLException - 如果產生 collection 時發生錯誤，或者提供了無效的列 id

另請參見：

toCollection(), toCollection(String)

toCollection

Collection<?> toCollection(String column)
                           throws SQLException

將此 CachedRowSet 物件中的指定列轉換成一個 Collection 物件。實作在如何表示此 Collection 物件上有一定的自由度，這是由於 Collection 框架的抽象本質所造成的。應該用通用 Collection 實作或專用的 Collection 實作（如 Vector 物件）來完全表示每個列值。SQL NULL 列值必須表示為 Java 程式語言中的 null。

標準的參考實作使用 Vector 物件包含列值，預期多數實作都是如此。如果使用 Vector 物件，則其大小必須與此 CachedRowSet 物件中的行數完全相等。

參數：

column - 一個 String 物件，提供值要用 Collection 來表示的列的名稱

返回：

一個 Collection 物件，它包含存儲在此 CachedRowSet 物件指定列中的值

拋出：

SQLException - 如果產生該 collection 時發生錯誤，或者提供了無效的列 id

另請參見：

toCollection(), toCollection(int)

getSyncProvider

SyncProvider getSyncProvider()
                             throws SQLException

獲取此 CachedRowSet 物件的 SyncProvider 實作。在內部，rowset 使用此方法來觸發 rowset 和資料源之間的讀取或寫入動作。例如，rowset 可能需要從 SyncProvider 獲得 rowset reader（RowSetReader 物件）上的句柄，以允許填充 rowset。

     RowSetReader rowsetReader = null;
     SyncProvider provider = 
         SyncFactory.getInstance("javax.sql.rowset.provider.RIOptimisticProvider");
         if (provider instanceof RIOptimisticProvider) {
             rowsetReader = provider.getRowSetReader();
         }
 

假定 rowsetReader 是 rowset 實作內的一個私有的、可存取的欄位，當應用程序調用 execute 方法時，它會依次調用 reader 的 readData 方法來填充該 RowSet 物件。

    
     rowsetReader.readData((RowSetInternal)this);
 

此外，應用程序可以使用此方法返回的 SyncProvider 物件來調用可返回有關 SyncProvider 物件資訊的方法，這些資訊包括有關供應商、版本、提供者標識、同步級別和當前已設置的鎖定等。

返回：

實例化 rowset 時所設置的 SyncProvider 物件，如果沒有設置，則返回預設的提供者

拋出：

SQLException - 如果在返回 SyncProvider 物件時發生錯誤

另請參見：

setSyncProvider(java.lang.String)

setSyncProvider

void setSyncProvider(String provider)
                     throws SQLException

將此 CachedRowSet 物件的 SyncProvider 物件設置為指定的提供者。此方法允許重置 SyncProvider 物件。

應該始終使用可用的 SyncProvider 機制來實例化 CachedRowSet 實作，但在某些情況下重置 SyncProvider 物件更合乎需要或者是必需的。例如，應用程序可能希望暫時使用預設的 SyncProvider 物件，然後選擇使用最近可用並能更好地滿足其需求的提供者。

重置 SyncProvider 物件會導致 RowSet 物件從 SyncFactory 請求新的 SyncProvider 實作。這能夠重置所有以前與原始資料源的連接和關係，並可能徹底更改非連接 rowset 的同步行為。

參數：

provider - 一個 String 物件，提供了 SyncProvider 實作的完全限定類別名

拋出：

SQLException - 如果試圖重置 SyncProvider 實作時發生錯誤

另請參見：

getSyncProvider()

size

int size()

返回此 CachedRowSet 物件中的行數。

返回：

rowset 中的行數

setMetaData

void setMetaData(RowSetMetaData md)
                 throws SQLException

使用給定的 RowSetMetaData 物件設置此 CachedRowSet 物件的元資料。當 RowSetReader 物件讀取 rowset 內容時，它創建一個 RowSetMetaData 物件並使用 RowSetMetaData 實作中的方法進行初始化。參考實作則使用 RowSetMetaDataImpl 類別。當 reader 完成 rowset 內容的讀取後，在內部調用此方法，以便將 RowSetMetaData 物件傳遞到 rowset。

參數：

md - 一個 RowSetMetaData 物件，包含關於此 CachedRowSet 物件中各列的元資料

拋出：

SQLException - 如果向 rowset 提供了無效的元資料

getOriginal

ResultSet getOriginal()
                      throws SQLException

返回一個套件含此 CachedRowSet 物件原始值的 ResultSet 物件。

ResultSet 物件的指針應該位於第一行的前面。此外，返回的 ResultSet 物件應該具有以下屬性：

• ResultSet.TYPE_SCROLL_INSENSITIVE
• ResultSet.CONCUR_UPDATABLE

RowSet 物件的原始值是上一次與底層資料源同步之前所具有的值。如果沒有進行同步，則原始值就是填充該 RowSet 物件時所使用的值。當應用程序調用方法 acceptChanges 並且已實作了 SyncProvider 物件來檢查衝突時，在內部調用此方法。如果正是這種情況，則 writer 比較原始值與資料源中當前的值，檢查是否存在衝突。

返回：

包含此 CachedRowSet 物件原始值的 ResultSet 物件

拋出：

SQLException - 如果產生該 ResultSet 物件時發生錯誤

getOriginalRow

ResultSet getOriginalRow()
                         throws SQLException

返回一個只包含此 CachedRowSet 物件當前行原始值的 ResultSet 物件。

ResultSet 物件的指針應該位於第一行的前面。此外，返回的 ResultSet 物件應該具有以下屬性：

• ResultSet.TYPE_SCROLL_INSENSITIVE
• ResultSet.CONCUR_UPDATABLE

返回：

原始行結果集

拋出：

SQLException - 如果沒有當前行

另請參見：

setOriginalRow()

setOriginalRow

void setOriginalRow()
                    throws SQLException

將此 CachedRowSet 物件中的當前行設置為原始行。

將當前行中所有已修改的值與資料源同步後，在內部調用此方法。當前行必須被標記為無法再插入、刪除或更新。

調用 setOriginalRow 是不可逆的。

拋出：

SQLException - 如果沒有當前行或重置原始行的內容時遇到錯誤

另請參見：

getOriginalRow()

getTableName

String getTableName()
                    throws SQLException

返回創建此 CachedRowSet 物件時所用物件（表）的標識符。可在多種場合下設置此名稱，並且規範並未對設置次數或標準實作是否應該追蹤以前的表名強加任何限制。

返回：

一個 String 物件，提供了作為此 CachedRowSet 物件的資料源的表名，如果沒有為表設置名稱，則返回 null

拋出：

SQLException - 如果返回表名時遇到錯誤

另請參見：

ResultSetMetaData.getTableName(int)

setTableName

void setTableName(String tabName)
                  throws SQLException

將派生此 CachedRowSet 物件的表的標識符設置為給定的表名。嘗試進行同步期間，在比較資料源中的值與 CachedRowSet 物件的值時，writer 使用此名稱來確定要使用的表。表標識符還指示應該將取自此 CachedRowSet 物件的修改值寫入何處。

此 CachedRowSet 物件的實作可以從 RowSetMetaDataImpl 物件內部獲得該名稱。

參數：

tabName - 一個 String 物件，標識派生此 CachedRowSet 物件的表，不能為 null，但是可以為空字元串

拋出：

SQLException - 如果命名該表時遇到錯誤，或者 tabName 為 null

另請參見：

RowSetMetaData.setTableName(int, java.lang.String), RowSetWriter, SyncProvider

getKeyColumns

int[] getKeyColumns()
                    throws SQLException

返回一個套件含一個或多個列號的陣列，這些列號指示了形成某個鍵的列，該鍵唯一地標識了此 CachedRowSet 物件中的某個行。

返回：

包含列號的陣列，該列號指示哪些列組成此 CachedRowSet 物件中行的主鍵。如果沒有列表示主鍵，則此陣列應該為空。

拋出：

SQLException - 如果此 CachedRowSet 物件為空

另請參見：

setKeyColumns(int[]), Joinable.getMatchColumnIndexes(), Joinable.getMatchColumnNames()

setKeyColumns

void setKeyColumns(int[] keys)
                   throws SQLException

使用給定的列號陣列設置此 CachedRowSet 物件的 keyCols 欄位，它形成了唯一標識此 CachedRowSet 物件中某個行的鍵。

如果 CachedRowSet 物件成為 JoinRowSet 物件的一部分，那麼在指定為鍵列的列也成為比對列的情況下，會保留此方法所定義的鍵和得到的約束條件。

參數：

keys - 一個 int 陣列，指示形成此 CachedRowSet 物件的主鍵的列；陣列中的每個元素都必須大於 0 並小於等於此 rowset 中的列數

拋出：

SQLException - 如果給定陣列中的任意元素對此 rowset 無效

另請參見：

getKeyColumns(), Joinable.setMatchColumn(String), Joinable.setMatchColumn(int)

createShared

RowSet createShared()
                    throws SQLException

返回一個新的 RowSet 物件，支持該物件的資料與此 CachedRowSet 物件的相同。實際上，兩個 CachedRowSet 物件在相同的資料上具有指針。因此，某個副本所做的任何更改對原始物件和所有其他副本而言都是可見的，就像原始物件所做的更改對其所有副本而言都是可見的一樣。如果某個副本調用方法更改底層資料，則它所調用的方法會通知所有已註冊偵聽器，就像原始 CachedRowSet 物件調用該方法時一樣。

此外，此方法創建的所有 RowSet 物件具有與此 CachedRowSet 物件相同的屬性。例如，如果此 CachedRowSet 物件是只讀的，則其所有副本也是只讀的。如果將 CachedRowSet 物件更改為可更新的，則所有副本也成為可更新的。

註：如果多個執行緒存取通過 createShared() 方法創建的 RowSet 物件，則指定以下行為來保持共享資料的完整性：應該在每個物件和單個底層表結構之間連續進行所有共享 RowSet 物件的讀取和寫入。

返回：

新的共享 RowSet 物件，具有與此 CachedRowSet 物件相同的屬性並且在相同的資料上具有指針

拋出：

SQLException - 如果發生錯誤或者底層平臺中不支持複製

另請參見：

RowSetEvent, RowSetListener

createCopy

CachedRowSet createCopy()
                        throws SQLException

創建一個 RowSet 物件，它是此 CachedRowSet 物件中資料的深層副本。與通過調用 createShared 所創建的 RowSet 物件相反，對原始 RowSet 物件副本所做的更新對於原始 RowSet 物件而言不得是可見的。同樣，向原始 RowSet 註冊的所有事件偵聽器不得偵聽新 RowSet 副本的事件。此外，必須維持已建立的所有約束限制。

返回：

新的 RowSet 物件，它是此 CachedRowSet 物件的深層副本並且完全獨立於此 CachedRowSet 物件

拋出：

SQLException - 如果產生此 CachedRowSet 物件的副本時發生錯誤

另請參見：

createShared(), createCopySchema(), createCopyNoConstraints(), RowSetEvent, RowSetListener

createCopySchema

CachedRowSet createCopySchema()
                              throws SQLException

創建一個 CachedRowSet 物件，它是此 CachedRowSet 物件的空副本。該副本不得包含任何內容，而只能表示原始 CachedRowSet 物件的表結構。此外，在原始 CachedRowSet 物件中設置的主鍵和外鍵約束必須在新的空 CachedRowSet 物件中等效執行。與通過調用 createShared 方法所產生的 RowSet 物件相反，對使用 createCopySchema 方法創建的此 CachedRowSet 物件副本所做的更新對於此 CachedRowSet 物件而言不得是可見的。

應用程序可以根據此方法返回的 CachedRowSet 物件來形成 WebRowSet，從而可將 RowSet 網要定義導出為 XML 以備後用。

拋出：

SQLException - 如果複製此 CachedRowSet 物件的結構時發送錯誤

另請參見：

createShared(), createCopySchema(), createCopyNoConstraints(), RowSetEvent, RowSetListener

createCopyNoConstraints

CachedRowSet createCopyNoConstraints()
                                     throws SQLException

創建一個 CachedRowSet 物件，它是此 CachedRowSet 物件資料的深層副本，但是獨立於此 CachedRowSet 物件。與通過調用 createShared 方法所產生的 RowSet 物件相反，對此 CachedRowSet 物件副本所做的更新對於此 CachedRowSet 物件而言不得是可見的。同樣，向此 CachedRowSet 物件註冊的所有事件偵聽器不得偵聽新 RowSet 物件的事件。此外，不得在副本中維持為此 CachedRowSet 物件所建立的任何約束限制。

返回：

新的 CachedRowSet 物件，它是此 CachedRowSet 物件的深層副本並且完全獨立於此 CachedRowSet 物件

拋出：

SQLException - 如果產生此 CachedRowSet 物件的副本時發生錯誤

另請參見：

createCopy(), createShared(), createCopySchema(), RowSetEvent, RowSetListener

getRowSetWarnings

RowSetWarning getRowSetWarnings()
                                throws SQLException

獲取此 RowSet 物件上的調用報告的第一個警告。此 RowSet 物件上的後續警告會被連接到此方法返回的 RowSetWarning 物件。 每次讀取新行時，都會自動清除警告鏈。不可以在已經關閉的 RowSet 物件上調用此方法；這樣做將導致拋出 SQLException。

返回：

報告的第一個 RowSetWarning 物件，如果沒有，則返回 null

拋出：

SQLException - 如果在已關閉的 RowSet 上調用此方法

另請參見：

RowSetWarning

getShowDeleted

boolean getShowDeleted()
                       throws SQLException

獲取一個 boolean 值，該值指示標記為刪除的行是否會出現在當前行集合中。如果返回 true，則已刪除行與當前行一起可見。如果返回 false，則已刪除行與當前行集合一起不可見。預設值為 false。

出於安全考慮或為了更好地適合某些部署情況，標準的 rowset 實作可以選擇限制此行為。這是由實作定義的，並不表示標準行為。

註：允許保持已刪除行可見會使某些標準 JDBC RowSet 實作方法的行為變得複雜。但是，多數 rowset 使用者可以簡單地忽略此額外細節，因為只有極其特殊的應用程序才會利用此功能。

返回：

如果已刪除行是可見的，則返回 true；否則返回 false

拋出：

SQLException - 如果 rowset 實作無法確定標記為刪除的行是否可見

另請參見：

setShowDeleted(boolean)

setShowDeleted

void setShowDeleted(boolean b)
                    throws SQLException

將屬性 showDeleted 設置為給定的 boolean 值，它確定標記為刪除的行是否會出現在當前行集合中。如果將值設置為 true，則已刪除行與當前行集合一起立即可見。如果將值設置為 false，則已刪除行與當前行集合一起被設置為不可見。

出於安全考慮或為了更好地適合某些部署情況，標準的 rowset 實作可以選擇限制此行為。這是由實作定義的，並不表示標準行為。

參數：

b - 如果應該顯示已刪除行，則為 true；否則為 false

拋出：

SQLException - 如果 rowset 實作無法重置已刪除行是否應該可見

另請參見：

getShowDeleted()

commit

void commit()
            throws SQLException

每個 CachedRowSet 物件的 SyncProvider 都包含一個取自 ResultSet 的 Connection 物件或傳遞到其建構子的 JDBC 屬性。此方法包裹 Connection 提交方法，以允許靈活的自動提交或非自動提交事務控制支持。

使自從上一次提交/回滾以來 acceptChanges() 方法進行的所有更改成為持久更改。此方法應該只在已禁用自動提交網要時使用。

拋出：

SQLException - 如果發生資料庫存取錯誤或者此 CachedRowSet 內的 Connection 物件處於自動提交網要下

另請參見：

Connection.setAutoCommit(boolean)

rollback

void rollback()
              throws SQLException

每個 CachedRowSet 物件的 SyncProvider 都包含一個取自原始 ResultSet 的 Connection 物件或傳遞給它的 JDBC 屬性。

撤消當前事務中所做的所有更改。此方法應該只在已禁用自動提交網要時使用。

拋出：

SQLException - 如果發生資料庫存取錯誤或者此 CachedRowSet 內的 Connection 物件處於自動提交網要下。

rollback

void rollback(Savepoint s)
              throws SQLException

每個 CachedRowSet 物件的 SyncProvider 都包含一個取自原始 ResultSet 的 Connection 物件或傳遞給它的 JDBC 屬性。

撤消當前事務中所做的所有更改，回到上一次 Savepoint 事務標記。此方法應該只在已禁用自動提交網要時使用。

參數：

s - Savepoint 事務標記

拋出：

SQLException - 如果發生資料庫存取錯誤或者此 CachedRowSet 內的 Connection 物件處於自動提交網要下。

rowSetPopulated

void rowSetPopulated(RowSetEvent event,
                     int numRows)
                     throws SQLException

通知已註冊偵聽器給定 RowSetEvent 物件中的某個 RowSet 物件已經填充了多個附加行。numRows 參數確保只在每隔 numRow 行時才觸發此事件。

可使用方法 event.getSource 獲取事件源。

參數：

event - 一個 RowSetEvent 物件，包含作為事件源的 RowSet 物件

numRows - 填入此值時，指示產生的 CachedRowSet 應該觸發事件的行間隔數；預設值是 0；不能小於 fetchSize 或 0

拋出：

SQLException

populate

void populate(ResultSet rs,
              int startRow)
              throws SQLException

使用取自給定 ResultSet 物件的資料填充此 CachedRowSet 物件。雖然與 populate(ResultSet) 方法十分類似，但此方法提供了一個額外的參數，允許指定 ResultSet 內開始使用資料填充 CachedRowSet 實例的位置。

當應用程序具有到開放 ResultSet 物件的連接時，此方法可作為 execute 方法的替代方法。使用方法 populate 比使用無參數的 execute 方法要更為高效，因為它不用打開新的連接和重新執行此 CachedRowSet 物件的命令。與採用 ResultSet 物件的 execute 相比，使用 populate 方法要更為便捷。

參數：

startRow - ResultSet 中的位置，從其處開始填充此 CachedRowSet 的記錄

rs - 一個 ResultSet 物件，包含要讀入到此 CachedRowSet 物件的資料

拋出：

SQLException - 如果提供的 ResultSet 物件為 null 或者此 CachedRowSet 物件無法獲取關聯的 ResultSetMetaData 物件

另請參見：

execute(java.sql.Connection), populate(ResultSet), ResultSet, ResultSetMetaData

setPageSize

void setPageSize(int size)
                 throws SQLException

設置 CachedRowSet 物件的頁大小。可以配置 CachedRowSet 以頁大小的行數來填充 CachedRowSet。調用 populate() 或 execute() 時，CachedRowSet 都根據用於填充 RowSet 的原始 SQL 查詢來獲取附加頁。

參數：

size - CachedRowSet 的頁大小

拋出：

SQLException - 如果設置 CachedRowSet 頁大小時發生錯誤或者頁大小小於 0。

getPageSize

int getPageSize()

返回 CachedRowSet 物件的頁大小。

返回：

int 值的頁大小

nextPage

boolean nextPage()
                 throws SQLException

逐個增加 CachedRowSet 的當前頁。如果剩餘行仍在用於填充 RowSet 的原始 SQL 查詢範圍內，則此方法導致 CachedRowSet 實作獲取下一個頁面大小的行並填充 RowSet。

返回：

如果還有其他頁，則返回 true；如果這是最後一頁，則返回 false

拋出：

SQLException - 如果獲取下一頁時發生錯誤，或者在調用 populate 或 execute 之前過早地調用了此方法。

previousPage

boolean previousPage()
                     throws SQLException

逐個減少 CachedRowSet 的當前頁。這導致 CachedRowSet 實作獲取前一個頁面大小的行並填充 RowSet。前一頁中返回的行數必須始終在用於填充 RowSet 的原始 SQL 查詢範圍內。

返回：

如果成功地獲取了前一頁，則返回 true；如果這是第一頁，則返回 false。

拋出：

SQLException - 如果獲取前一頁時發生錯誤，或者在調用 populate 或 execute 之前過早地調用了此方法。