Interface CachedRowSet

The interface that all standard implementations of CachedRowSet must implement.

The reference implementation of the CachedRowSet interface provided by Oracle Corporation is a standard implementation. Developers may use this implementation just as it is, they may extend it, or they may choose to write their own implementations of this interface.

A CachedRowSet object is a container for rows of data that caches its rows in memory, which makes it possible to operate without always being connected to its data source. Further, it is a JavaBeans™ component and is scrollable, updatable, and serializable. A CachedRowSet object typically contains rows from a result set, but it can also contain rows from any file with a tabular format, such as a spread sheet. The reference implementation supports getting data only from a ResultSet object, but developers can extend the SyncProvider implementations to provide access to other tabular data sources.

An application can modify the data in a CachedRowSet object, and those modifications can then be propagated back to the source of the data.

A CachedRowSet object is a disconnected rowset, which means that it makes use of a connection to its data source only briefly. It connects to its data source while it is reading data to populate itself with rows and again while it is propagating changes back to its underlying data source. The rest of the time, a CachedRowSet object is disconnected, including while its data is being modified. Being disconnected makes a RowSet object much leaner and therefore much easier to pass to another component. For example, a disconnected RowSet object can be serialized and passed over the wire to a thin client such as a personal digital assistant (PDA).

1.0 Creating a CachedRowSet Object

CachedRowSetImpl crs = new CachedRowSetImpl();

A SyncProvider object provides a CachedRowSet object with a reader (a RowSetReader object) for reading data from a data source to populate itself with data. A reader can be implemented to read data from a ResultSet object or from a file with a tabular format. A SyncProvider object also provides a writer (a RowSetWriter object) for synchronizing any modifications to the CachedRowSet object's data made while it was disconnected with the data in the underlying data source.

A writer can be implemented to exercise various degrees of care in checking for conflicts and in avoiding them. (A conflict occurs when a value in the data source has been changed after the rowset populated itself with that value.) The RIOptimisticProvider implementation assumes there will be few or no conflicts and therefore sets no locks. It updates the data source with values from the CachedRowSet object only if there are no conflicts. Other writers can be implemented so that they always write modified data to the data source, which can be accomplished either by not checking for conflicts or, on the other end of the spectrum, by setting locks sufficient to prevent data in the data source from being changed. Still other writer implementations can be somewhere in between.

A CachedRowSet object may use any SyncProvider implementation that has been registered with the SyncFactory singleton. An application can find out which SyncProvider implementations have been registered by calling the following line of code.

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

There are two ways for a CachedRowSet object to specify which SyncProvider object it will use.

• Supplying the name of the implementation to the constructor
  The following line of code creates the CachedRowSet object crs2 that is initialized with default values except that its SyncProvider object is the one specified.

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

• Setting the SyncProvider using the CachedRowSet method setSyncProvider
  The following line of code resets the SyncProvider object for crs, the CachedRowSet object created with the default constructor.

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

2.0 Retrieving Data from a CachedRowSet Object

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 Retrieving RowSetMetaData

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

• It includes setter methods: A RowSet object uses these methods internally when it is populated with data from a different ResultSet object.
• It contains fewer getter methods: Some ResultSetMetaData methods to not apply to a RowSet object. For example, methods retrieving whether a column value is writable or read only do not apply because all of a RowSet object's columns will be writable or read only, depending on whether the rowset is updatable or not.

3.0 Updating a CachedRowSet Object

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

The next example demonstrates moving to the insert row, building a new row on the insert row, inserting it into the rowset, and then calling the method acceptChanges to add the new row to the underlying data source. Note that as with the getter methods, the updater methods may take either a column index or a column name to designate the column being acted upon.

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

NOTE: Where the insertRow() method inserts the contents of a CachedRowSet object's insert row is implementation-defined. The reference implementation for the CachedRowSet interface inserts a new row immediately following the current row, but it could be implemented to insert new rows in any number of other places.

Another thing to note about these examples is how they use the method acceptChanges. It is this method that propagates changes in a CachedRowSet object back to the underlying data source, calling on the RowSet object's writer internally to write changes to the data source. To do this, the writer has to incur the expense of establishing a connection with that data source. The preceding two code fragments call the method acceptChanges immediately after calling updateRow or insertRow. However, when there are multiple rows being changed, it is more efficient to call acceptChanges after all calls to updateRow and insertRow have been made. If acceptChanges is called only once, only one connection needs to be established.

4.0 Updating the Underlying Data Source

A writer is made available through an implementation of the SyncProvider interface, as discussed in section 1, "Creating a CachedRowSet Object." The default reference implementation provider, RIOptimisticProvider, has its writer implemented to use an optimistic concurrency control mechanism. That is, it maintains no locks in the underlying database while the rowset is disconnected from the database and simply checks to see if there are any conflicts before writing data to the data source. If there are any conflicts, it does not write anything to the data source.

The reader/writer facility provided by the SyncProvider class is pluggable, allowing for the customization of data retrieval and updating. If a different concurrency control mechanism is desired, a different implementation of SyncProvider can be plugged in using the method setSyncProvider.

In order to use the optimistic concurrency control routine, the RIOptismisticProvider maintains both its current value and its original value (the value it had immediately preceding the current value). Note that if no changes have been made to the data in a RowSet object, its current values and its original values are the same, both being the values with which the RowSet object was initially populated. However, once any values in the RowSet object have been changed, the current values and the original values will be different, though at this stage, the original values are still the initial values. With any subsequent changes to data in a RowSet object, its original values and current values will still differ, but its original values will be the values that were previously the current values.

Keeping track of original values allows the writer to compare the RowSet object's original value with the value in the database. If the values in the database differ from the RowSet object's original values, which means that the values in the database have been changed, there is a conflict. Whether a writer checks for conflicts, what degree of checking it does, and how it handles conflicts all depend on how it is implemented.

5.0 Registering and Notifying Listeners

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

6.0 Passing Data to Thin Clients

While a CachedRowSet object is disconnected, it can be much leaner than a ResultSet object with the same data. As a result, it can be especially suitable for sending data to a thin client such as a PDA, where it would be inappropriate to use a JDBC driver due to resource limitations or security considerations. Thus, a CachedRowSet object provides a means to "get rows in" without the need to implement the full JDBC API.

7.0 Scrolling and Updating

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

The object crs now contains the data from the table EMPLOYEES, just as the object rs does. The difference is that the cursor for crs can be moved forward, backward, or to a particular row even if the cursor for rs can move only forward. In addition, crs is updatable even if rs is not because by default, a CachedRowSet object is both scrollable and updatable.

In summary, a CachedRowSet object can be thought of as simply a disconnected set of rows that are being cached outside of a data source. Being thin and serializable, it can easily be sent across a wire, and it is well suited to sending data to a thin client. However, a CachedRowSet object does have a limitation: It is limited in size by the amount of data it can store in memory at one time.

8.0 Getting Universal Data Access

9.0 Setting Properties

NOTE: In order to use a DataSource object for making a connection, the DataSource object must have been registered with a naming service that uses the Java Naming and Directory Interface™ (JNDI) API. This registration is usually done by a person acting in the capacity of a system administrator.

In order to be able to populate itself with data from a database, a rowset needs to set a command property. This property is a query that is a PreparedStatement object, which allows the query to have parameter placeholders that are set at run time, as opposed to design time. To set these placeholder parameters with values, a rowset provides setter methods for setting values of each data type, similar to the setter methods provided by the PreparedStatement interface.

The following code fragment illustrates how the CachedRowSet object crs might have its command property set. Note that if a tool is used to set properties, this is the code that the tool would use.

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

The values that will be used to set the command's placeholder parameters are contained in the RowSet object's params field, which is a Vector object. The CachedRowSet class provides a set of setter methods for setting the elements in its params field. The following code fragment demonstrates setting the two parameters in the query from the previous example.

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

The params field now contains two elements, each of which is an array two elements long. The first element is the parameter number; the second is the value to be set. In this case, the first element of params is 1, 5000, and the second element is 2, "West". When an application calls the method execute, it will in turn call on this RowSet object's reader, which will in turn invoke its readData method. As part of its implementation, readData will get the values in params and use them to set the command's placeholder parameters. The following code fragment gives an idea of how the reader does this, after obtaining the Connection object con.

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]);
    //    }

At this point, the command for crs is the query "SELECT FIRST_NAME, LAST_NAME, ADDRESS FROM CUSTOMERS WHERE CREDIT_LIMIT > 5000 AND REGION = "West". After the readData method executes this command with the following line of code, it will have the data from rs with which to populate crs.

ResultSet rs = pstmt.executeQuery();

The preceding code fragments give an idea of what goes on behind the scenes; they would not appear in an application, which would not invoke methods like readData and decodeParams. In contrast, the following code fragment shows what an application might do. It sets the rowset's command, sets the command's parameters, and executes the command. Simply by calling the execute method, crs populates itself with the requested data from the table CUSTOMERS.

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 Paging Data

After properties have been set, the CachedRowSet object must be populated with data using either the method populate or the method execute. The following lines of code demonstrate using the method populate. Note that this version of the method takes two parameters, a ResultSet handle and the row in the ResultSet object from which to start retrieving rows.

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

The next code fragment shows populating a CachedRowSet object using the method execute, which may or may not take a Connection object as a parameter. This code passes execute the Connection object conHandle.

Note that there are two differences between the following code fragment and the previous one. First, the method setMaxRows is not called, so there is no limit set for the number of rows that crs may contain. (Remember that crs always has the overriding limit of how much data it can store in memory.) The second difference is that the you cannot pass the method execute the number of the row in the ResultSet object from which to start retrieving rows. This method always starts with the first row.

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

To access the next page (chunk of data), an application calls the method nextPage. This method creates a new CachedRowSet object and fills it with the next page of data. For example, assume that the CachedRowSet object's command returns a ResultSet object rs with 1000 rows of data. If the page size has been set to 100, the first call to the method nextPage will create a CachedRowSet object containing the first 100 rows of rs. After doing what it needs to do with the data in these first 100 rows, the application can again call the method nextPage to create another CachedRowSet object with the second 100 rows from rs. The data from the first CachedRowSet object will no longer be in memory because it is replaced with the data from the second CachedRowSet object. After the tenth call to the method nextPage, the tenth CachedRowSet object will contain the last 100 rows of data from rs, which are stored in memory. At any given time, the data from only one CachedRowSet object is stored in memory.

The method nextPage returns true as long as the current page is not the last page of rows and false when there are no more pages. It can therefore be used in a while loop to retrieve all of the pages, as is demonstrated in the following lines of code.

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

The CachedRowSet interface also defines the method previousPage. Just as the method nextPage is analogous to the ResultSet method next, the method previousPage is analogous to the ResultSet method previous. Similar to the method nextPage, previousPage creates a CachedRowSet object containing the number of rows set as the page size. So, for instance, the method previousPage could be used in a while loop at the end of the preceding code fragment to navigate back through the pages from the last page to the first page. The method previousPage is also similar to nextPage in that it can be used in a while loop, except that it returns true as long as there is another page preceding it and false when there are no more pages ahead of it.

By positioning the cursor after the last row for each page, as is done in the following code fragment, the method previous navigates from the last row to the first row in each page. The code could also have left the cursor before the first row on each page and then used the method next in a while loop to navigate each page from the first row to the last row.

The following code fragment assumes a continuation from the previous code fragment, meaning that the cursor for the tenth CachedRowSet object is on the last row. The code moves the cursor to after the last row so that the first call to the method previous will put the cursor back on the last row. After going through all of the rows in the last page (the CachedRowSet object crs), the code then enters the while loop to get to the ninth page, go through the rows backwards, go to the eighth page, go through the rows backwards, and so on to the first row of the first page.

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

Fields

COMMIT_ON_ACCEPT_CHANGES

@Deprecated
static final boolean COMMIT_ON_ACCEPT_CHANGES

Deprecated. Because this field is final (it is part of an interface), its value cannot be changed.

Causes the CachedRowSet object's SyncProvider to commit the changes when acceptChanges() is called. If set to false, the changes will not be committed until one of the CachedRowSet interface transaction methods is called.

See Also:

commit(), rollback(), Constant Field Values

Methods

populate

void populate(ResultSet data)
       throws SQLException

Parameters:

data - the ResultSet object containing the data to be read into this CachedRowSet object

Throws:

SQLException - if a null ResultSet object is supplied or this CachedRowSet object cannot retrieve the associated ResultSetMetaData object

See Also:

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

execute

void execute(Connection conn)
      throws SQLException

Parameters:

conn - a standard JDBC Connection object with valid properties

Throws:

SQLException - if an invalid Connection object is supplied or an error occurs in establishing the connection to the data source

See Also:

populate(java.sql.ResultSet), Connection

acceptChanges

void acceptChanges()
            throws SyncProviderException

Throws:

SyncProviderException - if the underlying synchronization provider's writer fails to write the updates back to the data source

See Also:

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

acceptChanges

void acceptChanges(Connection con)
            throws SyncProviderException

Parameters:

con - a standard JDBC Connection object

Throws:

SyncProviderException - if the underlying synchronization provider's writer fails to write the updates back to the data source

See Also:

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

restoreOriginal

void restoreOriginal()
              throws SQLException

Throws:

SQLException - if an error occurs rolling back the current value of this CachedRowSet object to its previous value

See Also:

RowSetListener.rowSetChanged(javax.sql.RowSetEvent)

release

void release()
      throws SQLException

Throws:

SQLException - if an error occurs flushing the contents of this CachedRowSet object

See Also:

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

undoDelete

void undoDelete()
         throws SQLException

Throws:

SQLException - if (1) the current row has not been deleted or (2) the cursor is on the insert row, before the first row, or after the last row

See Also:

undoInsert(), ResultSet.cancelRowUpdates()

undoInsert

void undoInsert()
         throws SQLException

Throws:

SQLException - if (1) the current row has not been inserted or (2) the cursor is before the first row, after the last row, or on the insert row

See Also:

undoDelete(), ResultSet.cancelRowUpdates()

undoUpdate

void undoUpdate()
         throws SQLException

Throws:

SQLException - if the cursor is before the first row or after the last row in in this CachedRowSet object

See Also:

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

columnUpdated

boolean columnUpdated(int idx)
               throws SQLException

Indicates whether the designated column in the current row of this CachedRowSet object has been updated.

Parameters:

idx - an int identifying the column to be checked for updates

Returns:

true if the designated column has been visibly updated; false otherwise

Throws:

SQLException - if the cursor is on the insert row, before the first row, or after the last row

See Also:

DatabaseMetaData.updatesAreDetected(int)

columnUpdated

boolean columnUpdated(String columnName)
               throws SQLException

Indicates whether the designated column in the current row of this CachedRowSet object has been updated.

Parameters:

columnName - a String object giving the name of the column to be checked for updates

Returns:

true if the column has been visibly updated; false otherwise

Throws:

SQLException - if the cursor is on the insert row, before the first row, or after the last row

See Also:

DatabaseMetaData.updatesAreDetected(int)

toCollection

Collection<?> toCollection()
                    throws SQLException

Returns:

a Collection object that contains the values in each row in this CachedRowSet object

Throws:

SQLException - if an error occurs generating the collection

See Also:

toCollection(int), toCollection(String)

toCollection

Collection<?> toCollection(int column)
                    throws SQLException

Parameters:

column - an int indicating the column whose values are to be represented in a Collection object

Returns:

a Collection object that contains the values stored in the specified column of this CachedRowSet object

Throws:

SQLException - if an error occurs generating the collection or an invalid column id is provided

See Also:

toCollection(), toCollection(String)

toCollection

Collection<?> toCollection(String column)
                    throws SQLException

Parameters:

column - a String object giving the name of the column whose values are to be represented in a collection

Returns:

a Collection object that contains the values stored in the specified column of this CachedRowSet object

Throws:

SQLException - if an error occurs generating the collection or an invalid column id is provided

See Also:

toCollection(), toCollection(int)

getSyncProvider

SyncProvider getSyncProvider()
                      throws SQLException

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

rowsetReader.readData((RowSetInternal)this);

Returns:

the SyncProvider object that was set when the rowset was instantiated, or if none was was set, the default provider

Throws:

SQLException - if an error occurs while returning the SyncProvider object

See Also:

setSyncProvider(java.lang.String)

setSyncProvider

void setSyncProvider(String provider)
              throws SQLException

Parameters:

provider - a String object giving the fully qualified class name of a SyncProvider implementation

Throws:

SQLException - if an error occurs while attempting to reset the SyncProvider implementation

See Also:

getSyncProvider()

size

int size()

Returns the number of rows in this CachedRowSet object.

Returns:

number of rows in the rowset

setMetaData

void setMetaData(RowSetMetaData md)
          throws SQLException

Sets the metadata for this CachedRowSet object with the given RowSetMetaData object. When a RowSetReader object is reading the contents of a rowset, it creates a RowSetMetaData object and initializes it using the methods in the RowSetMetaData implementation. The reference implementation uses the RowSetMetaDataImpl class. When the reader has completed reading the rowset contents, this method is called internally to pass the RowSetMetaData object to the rowset.

Parameters:

md - a RowSetMetaData object containing metadata about the columns in this CachedRowSet object

Throws:

SQLException - if invalid metadata is supplied to the rowset

getOriginal

ResultSet getOriginal()
               throws SQLException

Returns:

a ResultSet object that contains the original value for this CachedRowSet object

Throws:

SQLException - if an error occurs producing the ResultSet object

getOriginalRow

ResultSet getOriginalRow()
                  throws SQLException

Returns:

the original result set of the row

Throws:

SQLException - if there is no current row

See Also:

setOriginalRow()

setOriginalRow

void setOriginalRow()
             throws SQLException

Throws:

SQLException - if there is no current row or an error is encountered resetting the contents of the original row

See Also:

getOriginalRow()

getTableName

String getTableName()
             throws SQLException

Returns an identifier for the object (table) that was used to create this CachedRowSet object. This name may be set on multiple occasions, and the specification imposes no limits on how many times this may occur or whether standard implementations should keep track of previous table names.

Returns:

a String object giving the name of the table that is the source of data for this CachedRowSet object or null if no name has been set for the table

Throws:

SQLException - if an error is encountered returning the table name

See Also:

ResultSetMetaData.getTableName(int)

setTableName

void setTableName(String tabName)
           throws SQLException

Parameters:

tabName - a String object identifying the table from which this CachedRowSet object was derived; cannot be null but may be an empty string

Throws:

SQLException - if an error is encountered naming the table or tabName is null

See Also:

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

getKeyColumns

int[] getKeyColumns()
             throws SQLException

Returns an array containing one or more column numbers indicating the columns that form a key that uniquely identifies a row in this CachedRowSet object.

Returns:

an array containing the column number or numbers that indicate which columns constitute a primary key for a row in this CachedRowSet object. This array should be empty if no columns are representative of a primary key.

Throws:

SQLException - if this CachedRowSet object is empty

See Also:

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

setKeyColumns

void setKeyColumns(int[] keys)
            throws SQLException

Parameters:

keys - an array of int indicating the columns that form a primary key for this CachedRowSet object; every element in the array must be greater than 0 and less than or equal to the number of columns in this rowset

Throws:

SQLException - if any of the numbers in the given array are not valid for this rowset

See Also:

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

createShared

RowSet createShared()
             throws SQLException

Returns:

a new shared RowSet object that has the same properties as this CachedRowSet object and that has a cursor over the same data

Throws:

SQLException - if an error occurs or cloning is not supported in the underlying platform

See Also:

RowSetEvent, RowSetListener

createCopy

CachedRowSet createCopy()
                 throws SQLException

Creates a RowSet object that is a deep copy of the data in this CachedRowSet object. In contrast to the RowSet object generated from a createShared call, updates made to the copy of the original RowSet object must not be visible to the original RowSet object. Also, any event listeners that are registered with the original RowSet must not have scope over the new RowSet copies. In addition, any constraint restrictions established must be maintained.

Returns:

a new RowSet object that is a deep copy of this CachedRowSet object and is completely independent of this CachedRowSet object

Throws:

SQLException - if an error occurs in generating the copy of the of this CachedRowSet object

See Also:

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

createCopySchema

CachedRowSet createCopySchema()
                       throws SQLException

Returns:

An empty copy of this CachedRowSet object

Throws:

SQLException - if an error occurs in cloning the structure of this CachedRowSet object

See Also:

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

createCopyNoConstraints

CachedRowSet createCopyNoConstraints()
                              throws SQLException

Creates a CachedRowSet object that is a deep copy of this CachedRowSet object's data but is independent of it. In contrast to the RowSet object generated from a createShared method call, updates made to a copy of this CachedRowSet object must not be visible to it. Also, any event listeners that are registered with this CachedRowSet object must not have scope over the new RowSet object. In addition, any constraint restrictions established for this CachedRowSet object must not be maintained in the copy.

Returns:

a new CachedRowSet object that is a deep copy of this CachedRowSet object and is completely independent of this CachedRowSet object

Throws:

SQLException - if an error occurs in generating the copy of the of this CachedRowSet object

See Also:

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

getRowSetWarnings

RowSetWarning getRowSetWarnings()
                         throws SQLException

Retrieves the first warning reported by calls on this RowSet object. Subsequent warnings on this RowSet object will be chained to the RowSetWarning object that this method returns. The warning chain is automatically cleared each time a new row is read. This method may not be called on a RowSet object that has been closed; doing so will cause a SQLException to be thrown.

Returns:

RowSetWarning the first RowSetWarning object reported or null if there are none

Throws:

SQLException - if this method is called on a closed RowSet

See Also:

RowSetWarning

getShowDeleted

boolean getShowDeleted()
                throws SQLException

Returns:

true if deleted rows are visible; false otherwise

Throws:

SQLException - if a rowset implementation is unable to to determine whether rows marked for deletion are visible

See Also:

setShowDeleted(boolean)

setShowDeleted

void setShowDeleted(boolean b)
             throws SQLException

Parameters:

b - true if deleted rows should be shown; false otherwise

Throws:

SQLException - if a rowset implementation is unable to to reset whether deleted rows should be visible

See Also:

getShowDeleted()

commit

void commit()
     throws SQLException

Throws:

SQLException - if a database access error occurs or this Connection object within this CachedRowSet is in auto-commit mode

See Also:

Connection.setAutoCommit(boolean)

rollback

void rollback()
       throws SQLException

Throws:

SQLException - if a database access error occurs or this Connection object within this CachedRowSet is in auto-commit mode.

rollback

void rollback(Savepoint s)
       throws SQLException

Parameters:

s - A Savepoint transaction marker

Throws:

SQLException - if a database access error occurs or this Connection object within this CachedRowSet is in auto-commit mode.

rowSetPopulated

void rowSetPopulated(RowSetEvent event,
                     int numRows)
              throws SQLException

Parameters:

event - a RowSetEvent object that contains the RowSet object that is the source of the events

numRows - when populating, the number of rows interval on which the CachedRowSet populated should fire; the default value is zero; cannot be less than fetchSize or zero

Throws:

SQLException - numRows < 0 or numRows < getFetchSize()

populate

void populate(ResultSet rs,
              int startRow)
       throws SQLException

Parameters:

startRow - the position in the ResultSet from where to start populating the records in this CachedRowSet

rs - the ResultSet object containing the data to be read into this CachedRowSet object

Throws:

SQLException - if a null ResultSet object is supplied or this CachedRowSet object cannot retrieve the associated ResultSetMetaData object

See Also:

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

setPageSize

void setPageSize(int size)
          throws SQLException

Sets the CachedRowSet object's page-size. A CachedRowSet may be configured to populate itself in page-size sized batches of rows. When either populate() or execute() are called, the CachedRowSet fetches an additional page according to the original SQL query used to populate the RowSet.

Parameters:

size - the page-size of the CachedRowSet

Throws:

SQLException - if an error occurs setting the CachedRowSet page size or if the page size is less than 0.

getPageSize

int getPageSize()

Returns the page-size for the CachedRowSet object

Returns:

an int page size

nextPage

boolean nextPage()
          throws SQLException

Increments the current page of the CachedRowSet. This causes the CachedRowSet implementation to fetch the next page-size rows and populate the RowSet, if remaining rows remain within scope of the original SQL query used to populated the RowSet.

Returns:

true if more pages exist; false if this is the last page

Throws:

SQLException - if an error occurs fetching the next page, or if this method is called prematurely before populate or execute.

previousPage

boolean previousPage()
              throws SQLException

Decrements the current page of the CachedRowSet. This causes the CachedRowSet implementation to fetch the previous page-size rows and populate the RowSet. The amount of rows returned in the previous page must always remain within scope of the original SQL query used to populate the RowSet.

Returns:

true if the previous page is successfully retrieved; false if this is the first page.

Throws:

SQLException - if an error occurs fetching the previous page, or if this method is called prematurely before populate or execute.