JavaTM Platform
Standard Ed. 6

javax.sql.rowset
接口 CachedRowSet

所有超级接口:
Joinable, ResultSet, RowSet, Wrapper
所有已知子接口:
FilteredRowSet, JoinRowSet, WebRowSet

public interface CachedRowSet
     
extends RowSet, Joinable

所有标准 CachedRowSet 实现都必须实现的接口。

Sun Microsystems 提供的 CachedRowSet 接口的参考实现是一个标准实现。开发人员可以按原样使用此实现、可以扩展它,也可以选择自己编写此接口的实现。

CachedRowSet 对象是一个数据行的容器,可在内存中缓存其各行,这使得进行操作时无需总是连接到数据源。此外,它还是一个 JavaBeansTM 组件,是可滚动、可更新、可序列化的。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 对象上调用 ResultSetMetaDataRowSetMetaData 的方法,应用程序可以获得有关 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 接口有两方面不同。 注:要返回 RowSetMetaData 对象,实现必须重写 java.sql.ResultSet 中定义的 getMetaData() 方法返回 RowSetMetaData 对象。

    3.0 更新 CachedRowSet 对象

    更新 CachedRowSet 对象与更新 ResultSet 对象类似,但是因为更新 rowset 时它并未连接到其数据源,所以必须执行额外的步骤才能使更改在底层数据源中生效。调用方法 updateRowinsertRow 后,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 不得不承受建立到数据源的连接所带来的开销。上述两个代码片断在调用 updateRowinsertRow 后立即调用方法 acceptChanges。但是,如果更改了多个行,则更高效的做法是在调用所有 updateRowinsertRow 后再调用 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 中发生更改时 tablebarGraph 将得到通知。

    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 InterfaceTM (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 的第一个元素是 15000,第二个元素是 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();
     

    上述代码片断说明了在后台进行的操作;这些操作不会出现在应用程序中,因为应用程序不会调用 readDatadecodeParams 之类的方法。相反,以下代码片断展示了应用程序可能执行的操作。它设置 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 都包含一个取自 ResultSetConnection 对象或传递到其构造方法的 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 都包含一个取自原始 ResultSetConnection 对象或传递给它的 JDBC 属性。
     void rollback(Savepoint s)
              每个 CachedRowSet 对象的 SyncProvider 都包含一个取自原始 ResultSetConnection 对象或传递给它的 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 能成功地将更改写入数据源。调用方法 updateRowinsertRowdeleteRow 后可立即调用此方法,但是在完成所有更改后只调用此方法一次要更为高效,这样只需要建立一个连接。

    注: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 能成功地将更改写入数据源。调用方法 updateRowinsertRowdeleteRow 后可立即调用此方法,但是在完成所有更改后只调用此方法一次要更为高效,这样只需要建立一个连接。

    注:acceptChanges() 方法将确定 COMMIT_ON_ACCEPT_CHANGES 是否设置为 true。如果设置为 true,则将同步中的所有更新都提交给数据源。否则应用程序必须显式地调用相应的 commitrollback 方法。

    参数:
    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 - 如果命名该表时遇到错误,或者 tabNamenull
    另请参见:
    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 都包含一个取自 ResultSetConnection 对象或传递到其构造方法的 JDBC 属性。此方法包装 Connection 提交方法,以允许灵活的自动提交或非自动提交事务控制支持。

    使自从上一次提交/回滚以来 acceptChanges() 方法进行的所有更改成为持久更改。此方法应该只在已禁用自动提交模式时使用。

    抛出:
    SQLException - 如果发生数据库访问错误或者此 CachedRowSet 内的 Connection 对象处于自动提交模式下
    另请参见:
    Connection.setAutoCommit(boolean)

    rollback

    void rollback()
                  throws SQLException
    每个 CachedRowSet 对象的 SyncProvider 都包含一个取自原始 ResultSetConnection 对象或传递给它的 JDBC 属性。

    撤消当前事务中所做的所有更改。此方法应该只在已禁用自动提交模式时使用。

    抛出:
    SQLException - 如果发生数据库访问错误或者此 CachedRowSet 内的 Connection 对象处于自动提交模式下。

    rollback

    void rollback(Savepoint s)
                  throws SQLException
    每个 CachedRowSet 对象的 SyncProvider 都包含一个取自原始 ResultSetConnection 对象或传递给它的 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 之前过早地调用了此方法。

    JavaTM Platform
    Standard Ed. 6

    提交错误或意见
    有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

    版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策