- All Superinterfaces:
AutoCloseable
,Joinable
,ResultSet
,RowSet
,Wrapper
- All Known Subinterfaces:
FilteredRowSet
,JoinRowSet
,WebRowSet
public interface CachedRowSet extends RowSet, Joinable
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
The following line of code uses the default constructor for
CachedRowSet
supplied in the reference implementation (RI) to create a default
CachedRowSet
object.
CachedRowSetImpl crs = new CachedRowSetImpl();This new
CachedRowSet
object will have its properties set to the
default properties of a BaseRowSet
object, and, in addition, it will
have an RIOptimisticProvider
object as its synchronization provider.
RIOptimisticProvider
, one of two SyncProvider
implementations included in the RI, is the default provider that the
SyncFactory
singleton will supply when no synchronization
provider is specified.
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 theCachedRowSet
object crs2 that is initialized with default values except that itsSyncProvider
object is the one specified.CachedRowSetImpl crs2 = new CachedRowSetImpl( "com.fred.providers.HighAvailabilityProvider");
- Setting the
SyncProvider
using theCachedRowSet
methodsetSyncProvider
The following line of code resets theSyncProvider
object for crs, theCachedRowSet
object created with the default constructor.crs.setSyncProvider("com.fred.providers.HighAvailabilityProvider");
SyncFactory
and SyncProvider
for
more details.
2.0 Retrieving Data from a CachedRowSet
Object
Data is retrieved from a CachedRowSet
object by using the
getter methods inherited from the ResultSet
interface. The following examples, in which crs
is a
CachedRowSet
object, demonstrate how to iterate through the rows, retrieving the column
values in each row. The first example uses the version of the
getter methods that take a column number; the second example
uses the version that takes a column name. Column numbers are generally
used when the RowSet
object's command
is of the form SELECT * FROM TABLENAME
; column names are most
commonly used when the command specifies columns by name.
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
An application can get information about the columns in a CachedRowSet
object by calling ResultSetMetaData
and RowSetMetaData
methods on a RowSetMetaData
object. The following code fragment,
in which crs is a CachedRowSet
object, illustrates the process.
The first line creates a RowSetMetaData
object with information
about the columns in crs. The method getMetaData
,
inherited from the ResultSet
interface, returns a
ResultSetMetaData
object, which is cast to a
RowSetMetaData
object before being assigned to the variable
rsmd. The second line finds out how many columns jrs has, and
the third line gets the JDBC type of values stored in the second column of
jrs
.
RowSetMetaData rsmd = (RowSetMetaData)crs.getMetaData(); int count = rsmd.getColumnCount(); int type = rsmd.getColumnType(2);The
RowSetMetaData
interface differs from the
ResultSetMetaData
interface in two ways.
- It includes
setter
methods: ARowSet
object uses these methods internally when it is populated with data from a differentResultSet
object. - It contains fewer
getter
methods: SomeResultSetMetaData
methods to not apply to aRowSet
object. For example, methods retrieving whether a column value is writable or read only do not apply because all of aRowSet
object's columns will be writable or read only, depending on whether the rowset is updatable or not.
RowSetMetaData
object, implementations must
override the getMetaData()
method defined in
java.sql.ResultSet
and return a RowSetMetaData
object.
3.0 Updating a CachedRowSet
Object
Updating a CachedRowSet
object is similar to updating a
ResultSet
object, but because the rowset is not connected to
its data source while it is being updated, it must take an additional step
to effect changes in its underlying data source. After calling the method
updateRow
or insertRow
, a
CachedRowSet
object must also call the method acceptChanges
to have updates
written to the data source. The following example, in which the cursor is
on a row in the CachedRowSet
object crs, shows
the code required to update two column values in the current row and also
update the RowSet
object's underlying data source.
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
When the methodacceptChanges
is executed, the
CachedRowSet
object's writer, a RowSetWriterImpl
object, is called behind the scenes to write the changes made to the
rowset to the underlying data source. The writer is implemented to make a
connection to the data source and write updates to it.
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
RIOptimisticProvider
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
Being JavaBeans components, all rowsets participate in the JavaBeans event model, inheriting methods for registering listeners and notifying them of changes from theBaseRowSet
class. A listener for a
CachedRowSet
object is a component that wants to be notified
whenever there is a change in the rowset. For example, if a
CachedRowSet
object contains the results of a query and
those
results are being displayed in, say, a table and a bar graph, the table and
bar graph could be registered as listeners with the rowset so that they can
update themselves to reflect changes. To become listeners, the table and
bar graph classes must implement the RowSetListener
interface.
Then they can be added to the CachedRowSet
object's list of
listeners, as is illustrated in the following lines of code.
crs.addRowSetListener(table); crs.addRowSetListener(barGraph);Each
CachedRowSet
method that moves the cursor or changes
data also notifies registered listeners of the changes, so
table
and barGraph
will be notified when there is
a change in crs
.
6.0 Passing Data to Thin Clients
One of the main reasons to use aCachedRowSet
object is to
pass data between different components of an application. Because it is
serializable, a CachedRowSet
object can be used, for example,
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.
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
A second major use forCachedRowSet
objects is to provide
scrolling and updating for ResultSet
objects that
do not provide these capabilities themselves. In other words, a
CachedRowSet
object can be used to augment the
capabilities of a JDBC technology-enabled driver (hereafter called a
"JDBC driver") when the DBMS does not provide full support for scrolling and
updating. To achieve the effect of making a non-scrollable and read-only
ResultSet
object scrollable and updatable, a programmer
simply needs to create a CachedRowSet
object populated
with that ResultSet
object's data. This is demonstrated
in the following code fragment, where stmt
is a
Statement
object.
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
Another advantage of theCachedRowSet
class is that it makes it
possible to retrieve and store data from sources other than a relational
database. The reader for a rowset can be implemented to read and populate
its rowset with data from any tabular data source, including a spreadsheet
or flat file.
Because 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-SQL data sources. Nevertheless, it is expected that most of the time,
CachedRowSet
objects will contain data that was fetched
from an SQL database using the JDBC API.
9.0 Setting Properties
All rowsets maintain a set of properties, which will usually be set using a tool. The number and kinds of properties a rowset has will vary, depending on what the rowset does and how it gets its data. For example, rowsets that get their data from aResultSet
object need to
set the properties that are required for making a database connection.
If a rowset uses the DriverManager
facility to make a
connection, it needs to set a property for the JDBC URL that identifies
the appropriate driver, and it needs to set the properties that give the
user name and password.
If, on the other hand, the rowset uses a DataSource
object
to make the connection, which is the preferred method, it does not need to
set the property for the JDBC URL. Instead, it needs to set
properties for the logical name of the data source, for the user name,
and for the password.
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
Because aCachedRowSet
object stores data in memory,
the amount of data that it can contain at any one
time is determined by the amount of memory available. To get around this limitation,
a CachedRowSet
object can retrieve data from a ResultSet
object in chunks of data, called pages. To take advantage of this mechanism,
an application sets the number of rows to be included in a page using the method
setPageSize
. In other words, if the page size is set to five, a chunk
of five rows of
data will be fetched from the data source at one time. An application can also
optionally set the maximum number of rows that may be fetched at one time. If the
maximum number of rows is set to zero, or no maximum number of rows is set, there is
no limit to the number of rows that may be fetched at a time.
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);When this code runs, crs will be populated with four rows from rsHandle starting with the tenth row.
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);After this code has run, crs will contain five rows of data from the
ResultSet
object produced by the command for crs. The writer
for crs will use conHandle to connect to the data source and
execute the command for crs. An application is then able to operate on the
data in crs in the same way that it would operate on data in any other
CachedRowSet
object.
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 } }After this code fragment has been run, the application will have traversed all 1000 rows, but it will have had no more than 100 rows in memory at a time.
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 } }
- Since:
- 1.5
-
Field Summary
Fields Modifier and Type Field Description static boolean
COMMIT_ON_ACCEPT_CHANGES
Deprecated.Because this field is final (it is part of an interface), its value cannot be changed.Fields declared in interface 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
-
Method Summary
Modifier and Type Method Description void
acceptChanges()
Propagates row update, insert and delete changes made to thisCachedRowSet
object to the underlying data source.void
acceptChanges(Connection con)
Propagates all row update, insert and delete changes to the data source backing thisCachedRowSet
object using the specifiedConnection
object to establish a connection to the data source.boolean
columnUpdated(int idx)
Indicates whether the designated column in the current row of thisCachedRowSet
object has been updated.boolean
columnUpdated(String columnName)
Indicates whether the designated column in the current row of thisCachedRowSet
object has been updated.void
commit()
EachCachedRowSet
object'sSyncProvider
contains aConnection
object from theResultSet
or JDBC properties passed to it's constructors.CachedRowSet
createCopy()
Creates aRowSet
object that is a deep copy of the data in thisCachedRowSet
object.CachedRowSet
createCopyNoConstraints()
Creates aCachedRowSet
object that is a deep copy of thisCachedRowSet
object's data but is independent of it.CachedRowSet
createCopySchema()
Creates aCachedRowSet
object that is an empty copy of thisCachedRowSet
object.RowSet
createShared()
Returns a newRowSet
object backed by the same data as that of thisCachedRowSet
object.void
execute(Connection conn)
Populates thisCachedRowSet
object with data, using the given connection to produce the result set from which the data will be read.int[]
getKeyColumns()
Returns an array containing one or more column numbers indicating the columns that form a key that uniquely identifies a row in thisCachedRowSet
object.ResultSet
getOriginal()
Returns aResultSet
object containing the original value of thisCachedRowSet
object.ResultSet
getOriginalRow()
Returns aResultSet
object containing the original value for the current row only of thisCachedRowSet
object.int
getPageSize()
Returns the page-size for theCachedRowSet
objectRowSetWarning
getRowSetWarnings()
Retrieves the first warning reported by calls on thisRowSet
object.boolean
getShowDeleted()
Retrieves aboolean
indicating whether rows marked for deletion appear in the set of current rows.SyncProvider
getSyncProvider()
Retrieves theSyncProvider
implementation for thisCachedRowSet
object.String
getTableName()
Returns an identifier for the object (table) that was used to create thisCachedRowSet
object.boolean
nextPage()
Increments the current page of theCachedRowSet
.void
populate(ResultSet data)
Populates thisCachedRowSet
object with data from the givenResultSet
object.void
populate(ResultSet rs, int startRow)
Populates thisCachedRowSet
object with data from the givenResultSet
object.boolean
previousPage()
Decrements the current page of theCachedRowSet
.void
release()
Releases the current contents of thisCachedRowSet
object and sends arowSetChanged
event to all registered listeners.void
restoreOriginal()
Restores thisCachedRowSet
object to its original value, that is, its value before the last set of changes.void
rollback()
EachCachedRowSet
object'sSyncProvider
contains aConnection
object from the originalResultSet
or JDBC properties passed to it.void
rollback(Savepoint s)
EachCachedRowSet
object'sSyncProvider
contains aConnection
object from the originalResultSet
or JDBC properties passed to it.void
rowSetPopulated(RowSetEvent event, int numRows)
Notifies registered listeners that a RowSet object in the given RowSetEvent object has populated a number of additional rows.void
setKeyColumns(int[] keys)
Sets thisCachedRowSet
object'skeyCols
field with the given array of column numbers, which forms a key for uniquely identifying a row in thisCachedRowSet
object.void
setMetaData(RowSetMetaData md)
Sets the metadata for thisCachedRowSet
object with the givenRowSetMetaData
object.void
setOriginalRow()
Sets the current row in thisCachedRowSet
object as the original row.void
setPageSize(int size)
Sets theCachedRowSet
object's page-size.void
setShowDeleted(boolean b)
Sets the propertyshowDeleted
to the givenboolean
value, which determines whether rows marked for deletion appear in the set of current rows.void
setSyncProvider(String provider)
Sets theSyncProvider
object for thisCachedRowSet
object to the one specified.void
setTableName(String tabName)
Sets the identifier for the table from which thisCachedRowSet
object was derived to the given table name.int
size()
Returns the number of rows in thisCachedRowSet
object.Collection<?>
toCollection()
Converts thisCachedRowSet
object to aCollection
object that contains all of thisCachedRowSet
object's data.Collection<?>
toCollection(int column)
Converts the designated column in thisCachedRowSet
object to aCollection
object.Collection<?>
toCollection(String column)
Converts the designated column in thisCachedRowSet
object to aCollection
object.void
undoDelete()
Cancels the deletion of the current row and notifies listeners that a row has changed.void
undoInsert()
Immediately removes the current row from thisCachedRowSet
object if the row has been inserted, and also notifies listeners that a row has changed.void
undoUpdate()
Immediately reverses the last update operation if the row has been modified.Methods declared in interface javax.sql.rowset.Joinable
getMatchColumnIndexes, getMatchColumnNames, setMatchColumn, setMatchColumn, setMatchColumn, setMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn, unsetMatchColumn
Methods declared in interface 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, 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, updateObject, updateObject, updateObject, updateObject, updateRef, updateRef, updateRow, updateRowId, updateRowId, updateShort, updateShort, updateSQLXML, updateSQLXML, updateString, updateString, updateTime, updateTime, updateTimestamp, updateTimestamp, wasNull
Methods declared in interface 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
Methods declared in interface java.sql.Wrapper
isWrapperFor, unwrap
-
Field Details
-
COMMIT_ON_ACCEPT_CHANGES
Deprecated.Because this field is final (it is part of an interface), its value cannot be changed.Causes theCachedRowSet
object'sSyncProvider
to commit the changes whenacceptChanges()
is called. If set to false, the changes will not be committed until one of theCachedRowSet
interface transaction methods is called.- See Also:
commit()
,rollback()
, Constant Field Values
-
-
Method Details
-
populate
Populates thisCachedRowSet
object with data from the givenResultSet
object.This method can be used as an alternative to the
execute
method when an application has a connection to an openResultSet
object. Using the methodpopulate
can be more efficient than using the version of theexecute
method that takes no parameters because it does not open a new connection and re-execute thisCachedRowSet
object's command. Using thepopulate
method is more a matter of convenience when compared to using the version ofexecute
that takes aResultSet
object.- Parameters:
data
- theResultSet
object containing the data to be read into thisCachedRowSet
object- Throws:
SQLException
- if a nullResultSet
object is supplied or thisCachedRowSet
object cannot retrieve the associatedResultSetMetaData
object- See Also:
execute(java.sql.Connection)
,ResultSet
,ResultSetMetaData
-
execute
Populates thisCachedRowSet
object with data, using the given connection to produce the result set from which the data will be read. This method should close any database connections that it creates to ensure that thisCachedRowSet
object is disconnected except when it is reading data from its data source or writing data to its data source.The reader for this
CachedRowSet
object will use conn to establish a connection to the data source so that it can execute the rowset's command and read data from the the resultingResultSet
object into thisCachedRowSet
object. This method also closes conn after it has populated thisCachedRowSet
object.If this method is called when an implementation has already been populated, the contents and the metadata are (re)set. Also, if this method is called before the method
acceptChanges
has been called to commit outstanding updates, those updates are lost.- Parameters:
conn
- a standard JDBCConnection
object with valid properties- Throws:
SQLException
- if an invalidConnection
object is supplied or an error occurs in establishing the connection to the data source- See Also:
populate(java.sql.ResultSet)
,Connection
-
acceptChanges
Propagates row update, insert and delete changes made to thisCachedRowSet
object to the underlying data source.This method calls on this
CachedRowSet
object's writer to do the work behind the scenes. StandardCachedRowSet
implementations should use theSyncFactory
singleton to obtain aSyncProvider
instance providing aRowSetWriter
object (writer). The writer will attempt to propagate changes made in thisCachedRowSet
object back to the data source.When the method
acceptChanges
executes successfully, in addition to writing changes to the data source, it makes the values in the current row be the values in the original row.Depending on the synchronization level of the
SyncProvider
implementation being used, the writer will compare the original values with those in the data source to check for conflicts. When there is a conflict, theRIOptimisticProvider
implementation, for example, throws aSyncProviderException
and does not write anything to the data source.An application may choose to catch the
SyncProviderException
object and retrieve theSyncResolver
object it contains. TheSyncResolver
object lists the conflicts row by row and sets a lock on the data source to avoid further conflicts while the current conflicts are being resolved. Further, for each conflict, it provides methods for examining the conflict and setting the value that should be persisted in the data source. After all conflicts have been resolved, an application must call theacceptChanges
method again to write resolved values to the data source. If all of the values in the data source are already the values to be persisted, the methodacceptChanges
does nothing.Some provider implementations may use locks to ensure that there are no conflicts. In such cases, it is guaranteed that the writer will succeed in writing changes to the data source when the method
acceptChanges
is called. This method may be called immediately after the methodsupdateRow
,insertRow
, ordeleteRow
have been called, but it is more efficient to call it only once after all changes have been made so that only one connection needs to be established.Note: The
acceptChanges()
method will determine if theCOMMIT_ON_ACCEPT_CHANGES
is set to true or not. If it is set to true, all updates in the synchronization are committed to the data source. Otherwise, the application must explicitly call thecommit()
orrollback()
methods as appropriate.- 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
Propagates all row update, insert and delete changes to the data source backing thisCachedRowSet
object using the specifiedConnection
object to establish a connection to the data source.The other version of the
acceptChanges
method is not passed a connection because it uses theConnection
object already defined within theRowSet
object, which is the connection used for populating it initially.This form of the method
acceptChanges
is similar to the form that takes no arguments; however, unlike the other form, this form can be used only when the underlying data source is a JDBC data source. The updatedConnection
properties must be used by theSyncProvider
to reset theRowSetWriter
configuration to ensure that the contents of theCachedRowSet
object are synchronized correctly.When the method
acceptChanges
executes successfully, in addition to writing changes to the data source, it makes the values in the current row be the values in the original row.Depending on the synchronization level of the
SyncProvider
implementation being used, the writer will compare the original values with those in the data source to check for conflicts. When there is a conflict, theRIOptimisticProvider
implementation, for example, throws aSyncProviderException
and does not write anything to the data source.An application may choose to catch the
SyncProviderException
object and retrieve theSyncResolver
object it contains. TheSyncResolver
object lists the conflicts row by row and sets a lock on the data source to avoid further conflicts while the current conflicts are being resolved. Further, for each conflict, it provides methods for examining the conflict and setting the value that should be persisted in the data source. After all conflicts have been resolved, an application must call theacceptChanges
method again to write resolved values to the data source. If all of the values in the data source are already the values to be persisted, the methodacceptChanges
does nothing.Some provider implementations may use locks to ensure that there are no conflicts. In such cases, it is guaranteed that the writer will succeed in writing changes to the data source when the method
acceptChanges
is called. This method may be called immediately after the methodsupdateRow
,insertRow
, ordeleteRow
have been called, but it is more efficient to call it only once after all changes have been made so that only one connection needs to be established.Note: The
acceptChanges()
method will determine if theCOMMIT_ON_ACCEPT_CHANGES
is set to true or not. If it is set to true, all updates in the synchronization are committed to the data source. Otherwise, the application must explicitly call thecommit
orrollback
methods as appropriate.- Parameters:
con
- a standard JDBCConnection
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
Restores thisCachedRowSet
object to its original value, that is, its value before the last set of changes. If there have been no changes to the rowset or only one set of changes, the original value is the value with which thisCachedRowSet
object was populated; otherwise, the original value is the value it had immediately before its current value.When this method is called, a
CachedRowSet
implementation must ensure that all updates, inserts, and deletes to the current rowset instance are replaced by the previous values. In addition, the cursor should be reset to the first row and arowSetChanged
event should be fired to notify all registered listeners.- Throws:
SQLException
- if an error occurs rolling back the current value of thisCachedRowSet
object to its previous value- See Also:
RowSetListener.rowSetChanged(javax.sql.RowSetEvent)
-
release
Releases the current contents of thisCachedRowSet
object and sends arowSetChanged
event to all registered listeners. Any outstanding updates are discarded and the rowset contains no rows after this method is called. There are no interactions with the underlying data source, and any rowset content, metadata, and content updates should be non-recoverable.This
CachedRowSet
object should lock until its contents and associated updates are fully cleared, thus preventing 'dirty' reads by other components that hold a reference to thisRowSet
object. In addition, the contents cannot be released until all components reading thisCachedRowSet
object have completed their reads. ThisCachedRowSet
object should be returned to normal behavior after firing therowSetChanged
event.The metadata, including JDBC properties and Synchronization SPI properties, are maintained for future use. It is important that properties such as the
command
property be relevant to the originating data source from which thisCachedRowSet
object was originally established.This method empties a rowset, as opposed to the
close
method, which marks the entire rowset as recoverable to allow the garbage collector the rowset's Java VM resources.- Throws:
SQLException
- if an error occurs flushing the contents of thisCachedRowSet
object- See Also:
RowSetListener.rowSetChanged(javax.sql.RowSetEvent)
,ResultSet.close()
-
undoDelete
Cancels the deletion of the current row and notifies listeners that a row has changed. After this method is called, the current row is no longer marked for deletion. This method can be called at any time during the lifetime of the rowset.In addition, multiple cancellations of row deletions can be made by adjusting the position of the cursor using any of the cursor position control methods such as:
CachedRowSet.absolute
CachedRowSet.first
CachedRowSet.last
- 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
Immediately removes the current row from thisCachedRowSet
object if the row has been inserted, and also notifies listeners that a row has changed. This method can be called at any time during the lifetime of a rowset and assuming the current row is within the exception limitations (see below), it cancels the row insertion of the current row.In addition, multiple cancellations of row insertions can be made by adjusting the position of the cursor using any of the cursor position control methods such as:
CachedRowSet.absolute
CachedRowSet.first
CachedRowSet.last
- 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
Immediately reverses the last update operation if the row has been modified. This method can be called to reverse updates on all columns until all updates in a row have been rolled back to their state just prior to the last synchronization (acceptChanges
) or population. This method may also be called while performing updates to the insert row.undoUpdate
may be called at any time during the lifetime of a rowset; however, after a synchronization has occurred, this method has no effect until further modification to the rowset data has occurred.- Throws:
SQLException
- if the cursor is before the first row or after the last row in thisCachedRowSet
object- See Also:
undoDelete()
,undoInsert()
,ResultSet.cancelRowUpdates()
-
columnUpdated
Indicates whether the designated column in the current row of thisCachedRowSet
object has been updated.- Parameters:
idx
- anint
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
Indicates whether the designated column in the current row of thisCachedRowSet
object has been updated.- Parameters:
columnName
- aString
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
Converts thisCachedRowSet
object to aCollection
object that contains all of thisCachedRowSet
object's data. Implementations have some latitude in how they can represent thisCollection
object because of the abstract nature of theCollection
framework. Each row must be fully represented in either a general purposeCollection
implementation or a specializedCollection
implementation, such as aTreeMap
object or aVector
object. An SQLNULL
column value must be represented as anull
in the Java programming language.The standard reference implementation for the
CachedRowSet
interface uses aTreeMap
object for the rowset, with the values in each row being contained inVector
objects. It is expected that most implementations will do the same.The
TreeMap
type of collection guarantees that the map will be in ascending key order, sorted according to the natural order for the key's class. Each key references aVector
object that corresponds to one row of aRowSet
object. Therefore, the size of eachVector
object must be exactly equal to the number of columns in theRowSet
object. The key used by theTreeMap
collection is determined by the implementation, which may choose to leverage a set key that is available within the internalRowSet
tabular structure by virtue of a key already set either on theRowSet
object itself or on the underlying SQL data.- Returns:
- a
Collection
object that contains the values in each row in thisCachedRowSet
object - Throws:
SQLException
- if an error occurs generating the collection- See Also:
toCollection(int)
,toCollection(String)
-
toCollection
Converts the designated column in thisCachedRowSet
object to aCollection
object. Implementations have some latitude in how they can represent thisCollection
object because of the abstract nature of theCollection
framework. Each column value should be fully represented in either a general purposeCollection
implementation or a specializedCollection
implementation, such as aVector
object. An SQLNULL
column value must be represented as anull
in the Java programming language.The standard reference implementation uses a
Vector
object to contain the column values, and it is expected that most implementations will do the same. If aVector
object is used, it size must be exactly equal to the number of rows in thisCachedRowSet
object.- Parameters:
column
- anint
indicating the column whose values are to be represented in aCollection
object- Returns:
- a
Collection
object that contains the values stored in the specified column of thisCachedRowSet
object - Throws:
SQLException
- if an error occurs generating the collection or an invalid column id is provided- See Also:
toCollection()
,toCollection(String)
-
toCollection
Converts the designated column in thisCachedRowSet
object to aCollection
object. Implementations have some latitude in how they can represent thisCollection
object because of the abstract nature of theCollection
framework. Each column value should be fully represented in either a general purposeCollection
implementation or a specializedCollection
implementation, such as aVector
object. An SQLNULL
column value must be represented as anull
in the Java programming language.The standard reference implementation uses a
Vector
object to contain the column values, and it is expected that most implementations will do the same. If aVector
object is used, it size must be exactly equal to the number of rows in thisCachedRowSet
object.- Parameters:
column
- aString
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 thisCachedRowSet
object - Throws:
SQLException
- if an error occurs generating the collection or an invalid column id is provided- See Also:
toCollection()
,toCollection(int)
-
getSyncProvider
Retrieves theSyncProvider
implementation for thisCachedRowSet
object. Internally, this method is used by a rowset to trigger read or write actions between the rowset and the data source. For example, a rowset may need to get a handle on the rowset reader (RowSetReader
object) from theSyncProvider
to allow the rowset to be populated.RowSetReader rowsetReader = null; SyncProvider provider = SyncFactory.getInstance("javax.sql.rowset.provider.RIOptimisticProvider"); if (provider instanceof RIOptimisticProvider) { rowsetReader = provider.getRowSetReader(); }
Assuming rowsetReader is a private, accessible field within the rowset implementation, when an application calls theexecute
method, it in turn calls on the reader'sreadData
method to populate theRowSet
object.rowsetReader.readData((RowSetInternal)this);
In addition, an application can use the
SyncProvider
object returned by this method to call methods that return information about theSyncProvider
object, including information about the vendor, version, provider identification, synchronization grade, and locks it currently has set.- Returns:
- the
SyncProvider
object that was set when the rowset was instantiated, or if none was set, the default provider - Throws:
SQLException
- if an error occurs while returning theSyncProvider
object- See Also:
setSyncProvider(java.lang.String)
-
setSyncProvider
Sets theSyncProvider
object for thisCachedRowSet
object to the one specified. This method allows theSyncProvider
object to be reset.A
CachedRowSet
implementation should always be instantiated with an availableSyncProvider
mechanism, but there are cases where resetting theSyncProvider
object is desirable or necessary. For example, an application might want to use the defaultSyncProvider
object for a time and then choose to use a provider that has more recently become available and better fits its needs.Resetting the
SyncProvider
object causes theRowSet
object to request a newSyncProvider
implementation from theSyncFactory
. This has the effect of resetting all previous connections and relationships with the originating data source and can potentially drastically change the synchronization behavior of a disconnected rowset.- Parameters:
provider
- aString
object giving the fully qualified class name of aSyncProvider
implementation- Throws:
SQLException
- if an error occurs while attempting to reset theSyncProvider
implementation- See Also:
getSyncProvider()
-
size
int size()Returns the number of rows in thisCachedRowSet
object.- Returns:
- number of rows in the rowset
-
setMetaData
Sets the metadata for thisCachedRowSet
object with the givenRowSetMetaData
object. When aRowSetReader
object is reading the contents of a rowset, it creates aRowSetMetaData
object and initializes it using the methods in theRowSetMetaData
implementation. The reference implementation uses theRowSetMetaDataImpl
class. When the reader has completed reading the rowset contents, this method is called internally to pass theRowSetMetaData
object to the rowset.- Parameters:
md
- aRowSetMetaData
object containing metadata about the columns in thisCachedRowSet
object- Throws:
SQLException
- if invalid metadata is supplied to the rowset
-
getOriginal
Returns aResultSet
object containing the original value of thisCachedRowSet
object.The cursor for the
ResultSet
object should be positioned before the first row. In addition, the returnedResultSet
object should have the following properties:- ResultSet.TYPE_SCROLL_INSENSITIVE
- ResultSet.CONCUR_UPDATABLE
The original value for a
RowSet
object is the value it had before the last synchronization with the underlying data source. If there have been no synchronizations, the original value will be the value with which theRowSet
object was populated. This method is called internally when an application calls the methodacceptChanges
and theSyncProvider
object has been implemented to check for conflicts. If this is the case, the writer compares the original value with the value currently in the data source to check for conflicts.- Returns:
- a
ResultSet
object that contains the original value for thisCachedRowSet
object - Throws:
SQLException
- if an error occurs producing theResultSet
object
-
getOriginalRow
Returns aResultSet
object containing the original value for the current row only of thisCachedRowSet
object.The cursor for the
ResultSet
object should be positioned before the first row. In addition, the returnedResultSet
object should have the following properties:- ResultSet.TYPE_SCROLL_INSENSITIVE
- ResultSet.CONCUR_UPDATABLE
- Returns:
- the original result set of the row
- Throws:
SQLException
- if there is no current row- See Also:
setOriginalRow()
-
setOriginalRow
Sets the current row in thisCachedRowSet
object as the original row.This method is called internally after the any modified values in the current row have been synchronized with the data source. The current row must be tagged as no longer inserted, deleted or updated.
A call to
setOriginalRow
is irreversible.- Throws:
SQLException
- if there is no current row or an error is encountered resetting the contents of the original row- See Also:
getOriginalRow()
-
getTableName
Returns an identifier for the object (table) that was used to create thisCachedRowSet
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 thisCachedRowSet
object ornull
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
Sets the identifier for the table from which thisCachedRowSet
object was derived to the given table name. The writer uses this name to determine which table to use when comparing the values in the data source with theCachedRowSet
object's values during a synchronization attempt. The table identifier also indicates where modified values from thisCachedRowSet
object should be written.The implementation of this
CachedRowSet
object may obtain the the name internally from theRowSetMetaDataImpl
object.- Parameters:
tabName
- aString
object identifying the table from which thisCachedRowSet
object was derived; cannot benull
but may be an empty string- Throws:
SQLException
- if an error is encountered naming the table or tabName isnull
- See Also:
RowSetMetaData.setTableName(int, java.lang.String)
,RowSetWriter
,SyncProvider
-
getKeyColumns
Returns an array containing one or more column numbers indicating the columns that form a key that uniquely identifies a row in thisCachedRowSet
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 thisCachedRowSet
object is empty- See Also:
setKeyColumns(int[])
,Joinable.getMatchColumnIndexes()
,Joinable.getMatchColumnNames()
-
setKeyColumns
Sets thisCachedRowSet
object'skeyCols
field with the given array of column numbers, which forms a key for uniquely identifying a row in thisCachedRowSet
object.If a
CachedRowSet
object becomes part of aJoinRowSet
object, the keys defined by this method and the resulting constraints are maintained if the columns designated as key columns also become match columns.- Parameters:
keys
- an array ofint
indicating the columns that form a primary key for thisCachedRowSet
object; every element in the array must be greater than0
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)
-
createCopy
Creates aRowSet
object that is a deep copy of the data in thisCachedRowSet
object. In contrast to theRowSet
object generated from acreateShared
call, updates made to the copy of the originalRowSet
object must not be visible to the originalRowSet
object. Also, any event listeners that are registered with the originalRowSet
must not have scope over the newRowSet
copies. In addition, any constraint restrictions established must be maintained.- Returns:
- a new
RowSet
object that is a deep copy of thisCachedRowSet
object and is completely independent of thisCachedRowSet
object - Throws:
SQLException
- if an error occurs in generating the copy of the of thisCachedRowSet
object- See Also:
createShared()
,createCopySchema()
,createCopyNoConstraints()
,RowSetEvent
,RowSetListener
-
createCopySchema
Creates aCachedRowSet
object that is an empty copy of thisCachedRowSet
object. The copy must not contain any contents but only represent the table structure of the originalCachedRowSet
object. In addition, primary or foreign key constraints set in the originatingCachedRowSet
object must be equally enforced in the new emptyCachedRowSet
object. In contrast to theRowSet
object generated from acreateShared
method call, updates made to a copy of thisCachedRowSet
object with thecreateCopySchema
method must not be visible to it.Applications can form a
WebRowSet
object from theCachedRowSet
object returned by this method in order to export theRowSet
schema definition to XML for future use.- Returns:
- An empty copy of this
CachedRowSet
object - Throws:
SQLException
- if an error occurs in cloning the structure of thisCachedRowSet
object- See Also:
createShared()
,createCopySchema()
,createCopyNoConstraints()
,RowSetEvent
,RowSetListener
-
createCopyNoConstraints
Creates aCachedRowSet
object that is a deep copy of thisCachedRowSet
object's data but is independent of it. In contrast to theRowSet
object generated from acreateShared
method call, updates made to a copy of thisCachedRowSet
object must not be visible to it. Also, any event listeners that are registered with thisCachedRowSet
object must not have scope over the newRowSet
object. In addition, any constraint restrictions established for thisCachedRowSet
object must not be maintained in the copy.- Returns:
- a new
CachedRowSet
object that is a deep copy of thisCachedRowSet
object and is completely independent of thisCachedRowSet
object - Throws:
SQLException
- if an error occurs in generating the copy of the of thisCachedRowSet
object- See Also:
createCopy()
,createShared()
,createCopySchema()
,RowSetEvent
,RowSetListener
-
getRowSetWarnings
Retrieves the first warning reported by calls on thisRowSet
object. Subsequent warnings on thisRowSet
object will be chained to theRowSetWarning
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 aSQLException
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
Retrieves aboolean
indicating whether rows marked for deletion appear in the set of current rows. Iftrue
is returned, deleted rows are visible with the current rows. Iffalse
is returned, rows are not visible with the set of current rows. The default value isfalse
.Standard rowset implementations may choose to restrict this behavior due to security considerations or to better fit certain deployment scenarios. This is left as implementation defined and does not represent standard behavior.
Note: Allowing deleted rows to remain visible complicates the behavior of some standard JDBC
RowSet
Implementations methods. However, most rowset users can simply ignore this extra detail because only very specialized applications will likely want to take advantage of this feature.- 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
Sets the propertyshowDeleted
to the givenboolean
value, which determines whether rows marked for deletion appear in the set of current rows. If the value is set totrue
, deleted rows are immediately visible with the set of current rows. If the value is set tofalse
, the deleted rows are set as invisible with the current set of rows.Standard rowset implementations may choose to restrict this behavior due to security considerations or to better fit certain deployment scenarios. This is left as implementations defined and does not represent standard behavior.
- 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
EachCachedRowSet
object'sSyncProvider
contains aConnection
object from theResultSet
or JDBC properties passed to it's constructors. This method wraps theConnection
commit method to allow flexible auto commit or non auto commit transactional control support.Makes all changes that are performed by the
acceptChanges()
method since the previous commit/rollback permanent. This method should be used only when auto-commit mode has been disabled.- Throws:
SQLException
- if a database access error occurs or this Connection object within thisCachedRowSet
is in auto-commit mode- See Also:
Connection.setAutoCommit(boolean)
-
rollback
EachCachedRowSet
object'sSyncProvider
contains aConnection
object from the originalResultSet
or JDBC properties passed to it.Undoes all changes made in the current transaction. This method should be used only when auto-commit mode has been disabled.
- Throws:
SQLException
- if a database access error occurs or this Connection object within thisCachedRowSet
is in auto-commit mode.
-
rollback
EachCachedRowSet
object'sSyncProvider
contains aConnection
object from the originalResultSet
or JDBC properties passed to it.Undoes all changes made in the current transaction back to the last
Savepoint
transaction marker. This method should be used only when auto-commit mode has been disabled.- Parameters:
s
- ASavepoint
transaction marker- Throws:
SQLException
- if a database access error occurs or this Connection object within thisCachedRowSet
is in auto-commit mode.
-
rowSetPopulated
Notifies registered listeners that a RowSet object in the given RowSetEvent object has populated a number of additional rows. ThenumRows
parameter ensures that this event will only be fired everynumRow
.The source of the event can be retrieved with the method event.getSource.
- Parameters:
event
- aRowSetEvent
object that contains theRowSet
object that is the source of the eventsnumRows
- when populating, the number of rows interval on which theCachedRowSet
populated should fire; the default value is zero; cannot be less thanfetchSize
or zero- Throws:
SQLException
-numRows < 0 or numRows < getFetchSize()
-
populate
Populates thisCachedRowSet
object with data from the givenResultSet
object. While related to thepopulate(ResultSet)
method, an additional parameter is provided to allow starting position within theResultSet
from where to populate the CachedRowSet instance.This method can be used as an alternative to the
execute
method when an application has a connection to an openResultSet
object. Using the methodpopulate
can be more efficient than using the version of theexecute
method that takes no parameters because it does not open a new connection and re-execute thisCachedRowSet
object's command. Using thepopulate
method is more a matter of convenience when compared to using the version ofexecute
that takes aResultSet
object.- Parameters:
startRow
- the position in theResultSet
from where to start populating the records in thisCachedRowSet
rs
- theResultSet
object containing the data to be read into thisCachedRowSet
object- Throws:
SQLException
- if a nullResultSet
object is supplied or thisCachedRowSet
object cannot retrieve the associatedResultSetMetaData
object- See Also:
execute(java.sql.Connection)
,populate(ResultSet)
,ResultSet
,ResultSetMetaData
-
setPageSize
Sets theCachedRowSet
object's page-size. ACachedRowSet
may be configured to populate itself in page-size sized batches of rows. When eitherpopulate()
orexecute()
are called, theCachedRowSet
fetches an additional page according to the original SQL query used to populate the RowSet.- Parameters:
size
- the page-size of theCachedRowSet
- Throws:
SQLException
- if an error occurs setting theCachedRowSet
page size or if the page size is less than 0.
-
getPageSize
int getPageSize()Returns the page-size for theCachedRowSet
object- Returns:
- an
int
page size
-
nextPage
Increments the current page of theCachedRowSet
. This causes theCachedRowSet
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
Decrements the current page of theCachedRowSet
. This causes theCachedRowSet
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.
-