Java javax.sql.rowset 接口 CachedRowSet（JDK5）

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

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

2.0 从 CachedRowSet 对象检索数据

    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 rsmd = (RowSetMetaData)crs.getMetaData();
     int count = rsmd.getColumnCount();
     int type = rsmd.getColumnType(2);
 

• 它包括设置方法：当使用取自不同 ResultSet 对象的数据填充 RowSet 对象时，该 RowSet 对象在内部使用这些方法。

• 它包含较少的获取方法：某些 ResultSetMetaData 方法无法应用到 RowSet 对象。例如，不会应用那些检索某个列值是可写入的还是只读的方法，因为 RowSet 对象的所有列要么是可写入的，要么是只读的，这取决于该 rowset 是否可更新。

3.0 更新 CachedRowSet 对象

     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 更新底层数据源

可通过 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 注册和通知侦听器

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

6.0 向瘦客户端传递数据

由于 CachedRowSet 对象是非连接的，所以和具有相同数据的 ResultSet 对象相比更为简洁。因此，它特别适于向瘦客户端（如 PDA）发送数据，这种瘦客户端由于资源限制或安全考虑而不适于使用 JDBC 驱动程序。所以 CachedRowSet 对象可提供一种“获取各行”的方式而无需实现全部 JDBC API。

7.0 滚动和更新

    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 获得通用数据访问

9.0 设置属性

注：要使用 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 分页数据

设置各个属性后，必须使用方法 populate 或方法 execute 用数据填充 CachedRowSet 对象。以下代码行演示了如何使用方法 populate。注意，该方法的这种形式采用两个参数，ResultSet 句柄和 ResultSet 对象中的行，从该行开始检索各行。

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

下一个代码片断展示了如何使用方法 execute 填充 CachedRowSet 对象，该方法可以采用 Connection 对象作为一个参数，也可以不采用。此代码向 execute 传递 Connection 对象 conHandle。

注意，以下代码片断和上述代码片断有两处差别。首先，没有调用方法 setMaxRows，所以没有对 crs 可以包含的行数设置限制。（记住，对于 crs 在内存中可以存储的数据量，总是有一个最高限制。）第二个差别是不能向方法 execute 传递 ResultSet 对象中起始检索行的行号。此方法始终从第一行开始检索。

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

要访问下一页（数据块），应用程序可调用方法 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.next() {
     . . . // operate on first chunk of 100 rows in crs, row by row
     }

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

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
         }
     }
 

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()