javax.sql
Class CachedRowSet


java.lang.Object

  |

  +--javax.sql.CachedRowSet
public class CachedRowSet
extends java.lang.Object
implements RowSet, java.io.Serializable, java.lang.Cloneable

A CachedRowSet is a disconnected, serializable, scrollable container for tabular data. A primary purpose of the CachedRowSet class is to provide a representation of a JDBC ResultSet that can be passed between different components of a remote application. For example, a CachedResultSet can be used to send the result of a query executed by an Enterprise JavaBeans component running in a server environment over a network to a client running in a web browser. A second use for CachedRowSets is to provide scrolling and updating for ResultSets that don't provide these capabilities themselves. A CachedRowSet can be used to augment the capabilities of a JDBC driver that doesn't have full support for scrolling and updating. Finally, a CachedRowSet can be used to provide Java applications with access to tabular data in an environment such as a thin client or PDA, where it would be inappropriate to use a JDBC driver due to resource limitations or security considerations. The CachedRowSet class provides a means to "get rows in" and "get changed rows out" without the need to implement the full JDBC API.

A CachedRowSet object can contain data retrieved via a JDBC driver or data from some other source, such as a spreadsheet. Both a CachedRowSet object and its metadata can be created from scratch. A component that acts as a factory for rowsets can use this capability to create a rowset containing data from non-JDBC data sources. We expect that rowset objects will contain data that was fetched from an SQL database using JDBC most of the time.

The term 'disconnected' implies that a CachedRowSet only makes use of a JDBC connection briefly while data is being read from the database and used to populate it with rows, and again while updated rows are being propagated back to the underlying database. During the remainder of its lifetime, a CachedRowSet object isn't associated with an underlying database connection. A CachedRowSet object can simply be thought of as a disconnected set of rows that are being cached outside of a data source. Since all data is cached in memory, CachedRowSets are not appropriate for extremely large data sets.

The contents of a CachedRowSet may be updated and the updates can be propagated to an underlying data source. CachedRowSets support an optimistic concurrency control mechanism---no locks are maintained in the underlying database during disconnected use of the rowset. The CachedRowSet class provides an extensible reader/writer facility that allows for customization of data retrieval and updating. Both the original value and current value of the CachedRowSet are maintained for use by the optimistic CC routines.

See Also:
Serialized Form

Constructor Summary
CachedRowSet()
          Create a CachedRowSet object.
 
Method Summary
 void acceptChanges()
          Propagate all row update, insert, and delete changes to a data source.
 void acceptChanges(java.sql.Connection con)
          Like acceptChanges() above, but takes a Connection argument.
 void cancelRowDelete()
          Cancels deletion of the current row.
 void cancelRowInsert()
          Cancels insertion of the current row.
 java.lang.Object clone()
          Returns an identical rowset object backed by a deep copy of this rowset's data.
 RowSet createCopy()
          Same as clone() above().
 RowSet createShared()
          Returns a new rowset object backed by the same data.
 void execute(java.sql.Connection connection)
          Populates the rowset with data.
 RowSetReader getReader()
          Get the rowset's reader.
 boolean getShowDeleted()
          This property determines whether or not rows marked for deletion appear in the set of current rows.
 RowSetWriter getWriter()
          Get the rowset's writer.
 void populate(java.sql.ResultSet data)
          Populate the CachedRowSet object with data from a ResultSet.
 void release()
          Releases the current contents of the rowset.
 void restoreOriginal()
          Restores the rowset to its original state, i.e.
 void setReader(RowSetReader reader)
          Set the rowset's reader.
 void setShowDeleted(boolean value)
          Set the show deleted property.
 void setWriter(RowSetWriter writer)
          Set the rowset's writer.
 java.util.Collection toCollection()
          Convert the rowset to a collection of tables.
 java.util.Collection toCollection(int column)
          Return a column of the rowset as a collection.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CachedRowSet


public CachedRowSet()

             throws java.sql.SQLException
Create a CachedRowSet object. The object has no metadata.
Throws:
java.sql.SQLException - if a database-access error occurs.
Method Detail

getShowDeleted


public boolean getShowDeleted()

                       throws java.sql.SQLException
This property determines whether or not rows marked for deletion appear in the set of current rows. The default value is false. Note: Allowing deleted rows to remain visible complicates the behavior of some of the methods. However, most users of CachedRowSets can simply ignore this extra detail, since only sophisticated applications will likely want to take advantage of this feature.
Returns:
true if deleted rows are visible, false otherwise
Throws:
java.sql.SQLException - if a database-access error occurs.

setShowDeleted


public void setShowDeleted(boolean value)

                    throws java.sql.SQLException
Set the show deleted property.
Parameters:
value - true if deleted rows should be shown, false otherwise
Throws:
java.sql.SQLException - if a database-access error occurs.

populate


public void populate(java.sql.ResultSet data)

              throws java.sql.SQLException
Populate the CachedRowSet object with data from a ResultSet. This method is an alternative to execute() for filling the rowset with data. Populate() doesn't require that the properties needed by execute(), such as the command property, be set. A RowSetChangedEvent is sent to all registered listeners prior to returning.
Parameters:
data - the data to be read
Throws:
java.sql.SQLException - if a database-access error occurs.

execute


public void execute(java.sql.Connection connection)
Populates the rowset with data. The first form uses the properties: url/data source name, user, and password to create a database connection. If these properties haven't been set, an exception is thrown. The second form uses an existing JDBC connection object instead. The values of the url/data source name, user, and password properties are ignored when the second form is used. Execute() closes any database connections that it creates. The command specified by the command property is executed to retrieve the data. The current contents of the rowset are discarded and the rowset's metadata is also (re)set. If there are outstanding updates, they are also ignored.

acceptChanges


public void acceptChanges()

                   throws java.sql.SQLException
Propagate all row update, insert, and delete changes to a data source. An SQLException is thrown if any of the updates cannot be propagated. If acceptUpdates() fails then the caller can assume that none of the updates are reflected in the data source. The current row is set to the first "updated" row that resulted in an exception, in the case that an exception is thrown. With one exception, if the row that caused the exception is a "deleted" row, then in the usual case, when deleted rows are not shown, the current row isn't affected. When successful, calling acceptUpdates() replaces the original value of the rowset with the current value. Note: Both the original and current value of the rowset are maintained. The original state is the value of the rowset following its creation (i.e. empty), or following the last call to acceptChanges(), execute(), populate(), release(), or restoreOriginal(). If no writer is set, i.e. updates aren't being propagated to an underlying datasource, acceptUpdates() just updates the original value. Internally, a RowSetWriter component is envoked to write the data for each row.
Throws:
java.sql.SQLException - if a database-access error occurs.

acceptChanges


public void acceptChanges(java.sql.Connection con)

                   throws java.sql.SQLException
Like acceptChanges() above, but takes a Connection argument. The Connection is used internally when doing the updates. This form isn't used unless the underlying data source is a JDBC data source.
Parameters:
con - a database connection
Throws:
java.sql.SQLException - if a database-access error occurs.

restoreOriginal


public void restoreOriginal()

                     throws java.sql.SQLException
Restores the rowset to its original state, i.e. the original value of the rowset becomes the current value. All updates, inserts, and deletes made to the original state are lost. The cursor is positioned before the first row. A RowSetChangedEvent is sent to all registered listeners prior to returning.
Throws:
java.sql.SQLException - if a database-access error occurs.

release


public void release()

             throws java.sql.SQLException
Releases the current contents of the rowset. Outstanding updates are discarded. The rowset contains no rows after release is called. A RowSetChangedEvent is sent to all registered listeners prior to returning.
Throws:
java.sql.SQLException - if a database-access error occurs.

cancelRowDelete


public void cancelRowDelete()

                     throws java.sql.SQLException
Cancels deletion of the current row. After calling cancelRowDelete() the current row is no longer marked for deletion. An exception is thrown if there is no current row. Note: This method can be ignored if deleted rows aren't being shown (the normal case).
Throws:
java.sql.SQLException - if a database-access error occurs.

cancelRowInsert


public void cancelRowInsert()

                     throws java.sql.SQLException
Cancels insertion of the current row. An exception is thrown if the row isn't an inserted row. The current row is immediately removed from the rowset. This operation cannot be undone.
Throws:
java.sql.SQLException - if a database-access error occurs.

createShared


public RowSet createShared()

                    throws java.sql.SQLException
Returns a new rowset object backed by the same data. Updates made by a shared duplicate are visible to the original rowset and other duplicates. A rowset and its duplicates form a set of cursors that iterate over a shared set of rows, providing different views of the underlying data. Duplicates also share property values. So, for example, if a rowset is read-only then all of its duplicates will be read-only.
Returns:
a shared rowset object
Throws:
java.sql.SQLException - if a database-access error occurs.

clone


public java.lang.Object clone()
Returns an identical rowset object backed by a deep copy of this rowset's data. Updates made on a copy are not visible to the original rowset. A copy of a rowset is completely independent from the original. Making a copy saves the cost of creating an identical rowset from first principles. This can be quite expensive, for example, involving querying a remote database server.
Returns:
a copy of the rowset
Throws:
java.sql.SQLException - if a database-access error occurs.
Overrides:
clone in class java.lang.Object

createCopy


public RowSet createCopy()

                  throws java.sql.SQLException
Same as clone() above().
Returns:
a copy of the rowset
Throws:
java.sql.SQLException - if a database-access error occurs.

toCollection


public java.util.Collection toCollection()

                                  throws java.sql.SQLException
Convert the rowset to a collection of tables. Each tables represents a row of the original rowset. The tables are keyed by column number. A copy of the rowset's contents is made.
Returns:
a collection object
Throws:
java.sql.SQLException - if a database-access error occurs.

toCollection


public java.util.Collection toCollection(int column)

                                  throws java.sql.SQLException
Return a column of the rowset as a collection. Makes a copy of the column's data.
Returns:
a collection object
Throws:
java.sql.SQLException - if a database-access error occurs.

getReader


public RowSetReader getReader()

                       throws java.sql.SQLException
Get the rowset's reader. A reader is a component of type RowSetReader that is registered with a rowset instance and is called by the rowset when it needs to read a new set of rows.
Returns:
the rowset's reader
Throws:
java.sql.SQLException - if a database-access error occurs.

setReader


public void setReader(RowSetReader reader)

               throws java.sql.SQLException
Set the rowset's reader. Setting this property is optional. A default reader is used if none is provided.
Parameters:
reader - a new RowSetReader (what if null?)
Throws:
java.sql.SQLException - if a database-access error occurs.

getWriter


public RowSetWriter getWriter()

                       throws java.sql.SQLException
Get the rowset's writer. A writer is a component of type RowSetWriter that is registered with a rowset instance and is called by the rowset when it needs to write an individual modified row of data to a data source.
Returns:
the rowset's writer
Throws:
java.sql.SQLException - if a database-access error occurs.

setWriter


public void setWriter(RowSetWriter writer)

               throws java.sql.SQLException
Set the rowset's writer. Setting this property is optional. A default writer is used if none is provided.
Parameters:
writer - a new RowSetWriter (what if null?)
Throws:
java.sql.SQLException - if a database-access error occurs.