OpenJDK 27 · javax.sql.rowset.JdbcRowSet · APIdia, the JavaDoc alternative

The standard interface that all standard implementations of JdbcRowSet must implement.

1.0 Overview

A wrapper around a ResultSet object that makes it possible to use the result set as a JavaBeans component. Thus, a JdbcRowSet object can be one of the Beans that a tool makes available for composing an application. Because a JdbcRowSet is a connected rowset, that is, it continually maintains its connection to a database using a JDBC technology-enabled driver, it also effectively makes the driver a JavaBeans component.

Because it is always connected to its database, an instance of JdbcRowSet can simply take calls invoked on it and in turn call them on its ResultSet object. As a consequence, a result set can, for example, be a component in a Swing application.

Another advantage of a JdbcRowSet object is that it can be used to make a ResultSet object scrollable and updatable. All RowSet objects are by default scrollable and updatable. If the driver and database being used do not support scrolling and/or updating of result sets, an application can populate a JdbcRowSet object with the data of a ResultSet object and then operate on the JdbcRowSet object as if it were the ResultSet object.

2.0 Creating a `JdbcRowSet` Object

The reference implementation of the JdbcRowSet interface, JdbcRowSetImpl, provides an implementation of the default constructor. A new instance is initialized with default values, which can be set with new values as needed. A new instance is not really functional until its execute method is called. In general, this method does the following:

establishes a connection with a database
creates a PreparedStatement object and sets any of its placeholder parameters
executes the statement to create a ResultSet object

If the execute method is successful, it will set the appropriate private JdbcRowSet fields with the following:

a Connection object -- the connection between the rowset and the database
a PreparedStatement object -- the query that produces the result set
a ResultSet object -- the result set that the rowset's command produced and that is being made, in effect, a JavaBeans component

If these fields have not been set, meaning that the execute method has not executed successfully, no methods other than execute and close may be called on the rowset. All other public methods will throw an exception.

Before calling the execute method, however, the command and properties needed for establishing a connection must be set. The following code fragment creates a JdbcRowSetImpl object, sets the command and connection properties, sets the placeholder parameter, and then invokes the method execute.

    JdbcRowSetImpl jrs = new JdbcRowSetImpl();
    jrs.setCommand("SELECT * FROM TITLES WHERE TYPE = ?");
    jrs.setURL("jdbc:myDriver:myAttribute");
    jrs.setUsername("cervantes");
    jrs.setPassword("sancho");
    jrs.setString(1, "BIOGRAPHY");
    jrs.execute();

The variable jrs now represents an instance of JdbcRowSetImpl that is a thin wrapper around the ResultSet object containing all the rows in the table TITLES where the type of book is biography. At this point, operations called on jrs will affect the rows in the result set, which is effectively a JavaBeans component.

The implementation of the RowSet method execute in the JdbcRowSet reference implementation differs from that in the CachedRowSet reference implementation to account for the different requirements of connected and disconnected RowSet objects.

Method Summary

Modifier and Type	Method and Description
public void	commit() Each `JdbcRowSet` contains a `Connection` object from the `ResultSet` or JDBC properties passed to it's constructors.
public boolean	Returns: `true` if auto-commit is enabled; `false` otherwise getAutoCommit() Each `JdbcRowSet` contains a `Connection` object from the original `ResultSet` or JDBC properties passed to it.
public RowSetWarning	Returns: the first `RowSetWarning` object reported on this `JdbcRowSet` object or `null` if there are none getRowSetWarnings() Retrieves the first warning reported by calls on this `JdbcRowSet` object.
public boolean	Returns: `true` if deleted rows are visible; `false` otherwise getShowDeleted() Retrieves a `boolean` indicating whether rows marked for deletion appear in the set of current rows.
public void	rollback() Each `JdbcRowSet` contains a `Connection` object from the original `ResultSet` or JDBC properties passed to it.
public void	rollback(Savepoint The `Savepoint` to rollback to s) Each `JdbcRowSet` contains a `Connection` object from the original `ResultSet` or JDBC properties passed to it.
public void	setAutoCommit(boolean `true` to enable auto-commit; `false` to disable auto-commit autoCommit) Each `JdbcRowSet` contains a `Connection` object from the original `ResultSet` or JDBC properties passed to it.
public void	setShowDeleted(boolean `true` if deleted rows should be shown; `false` otherwise b) Sets the property `showDeleted` to the given `boolean` value.

Inherited from 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
Inherited from javax.sql.rowset.Joinable:: getMatchColumnIndexes getMatchColumnNames setMatchColumn setMatchColumn setMatchColumn setMatchColumn unsetMatchColumn unsetMatchColumn unsetMatchColumn unsetMatchColumn

Method Detail

commit back to summary

commit	back to summary
public void commit() throws SQLException Each `JdbcRowSet` contains a `Connection` object from the `ResultSet` or JDBC properties passed to it's constructors. This method wraps the `Connection` commit method to allow flexible auto commit or non auto commit transactional control support. Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled. Exceptions SQLException: if a database access error occurs or this Connection object within this `JdbcRowSet` is in auto-commit mode See Also `java.sql.Connection#setAutoCommit`

public void commit() throws SQLException

Each JdbcRowSet contains a Connection object from the ResultSet or JDBC properties passed to it's constructors. This method wraps the Connection commit method to allow flexible auto commit or non auto commit transactional control support.

Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled.

Exceptions

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

See Also

java.sql.Connection#setAutoCommit

getAutoCommit back to summary

getAutoCommit	back to summary
public boolean getAutoCommit() throws SQLException Each `JdbcRowSet` contains a `Connection` object from the original `ResultSet` or JDBC properties passed to it. This method wraps the `Connection`'s `getAutoCommit` method to allow an application to determine the `JdbcRowSet` transaction behavior. Sets this connection's auto-commit mode to the given state. If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either the method commit or the method rollback. By default, new connections are in auto-commit mode. Returns:boolean `true` if auto-commit is enabled; `false` otherwise Exceptions SQLException: if a database access error occurs See Also `java.sql.Connection#getAutoCommit()`

public boolean getAutoCommit() throws SQLException

Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it. This method wraps the Connection's getAutoCommit method to allow an application to determine the JdbcRowSet transaction behavior.

Sets this connection's auto-commit mode to the given state. If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by a call to either the method commit or the method rollback. By default, new connections are in auto-commit mode.

Returns:boolean

true if auto-commit is enabled; false otherwise

Exceptions

SQLException:: if a database access error occurs

See Also

java.sql.Connection#getAutoCommit()

getRowSetWarnings back to summary

getRowSetWarnings	back to summary
public RowSetWarning getRowSetWarnings() throws SQLException Retrieves the first warning reported by calls on this `JdbcRowSet` object. If a second warning was reported on this `JdbcRowSet` object, it will be chained to the first warning and can be retrieved by calling the method `RowSetWarning.getNextWarning` on the first warning. Subsequent warnings on this `JdbcRowSet` object will be chained to the `RowSetWarning` objects returned by the method `RowSetWarning.getNextWarning`. 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 an `SQLException` to be thrown. Because it is always connected to its data source, a `JdbcRowSet` object can rely on the presence of active `Statement`, `Connection`, and `ResultSet` instances. This means that applications can obtain additional `SQLWarning` notifications by calling the `getNextWarning` methods that they provide. Disconnected `Rowset` objects, such as a `CachedRowSet` object, do not have access to these `getNextWarning` methods. Returns:RowSetWarning the first `RowSetWarning` object reported on this `JdbcRowSet` object or `null` if there are none Exceptions SQLException: if this method is called on a closed `JdbcRowSet` object See Also `RowSetWarning`

public RowSetWarning getRowSetWarnings() throws SQLException

Retrieves the first warning reported by calls on this JdbcRowSet object. If a second warning was reported on this JdbcRowSet object, it will be chained to the first warning and can be retrieved by calling the method RowSetWarning.getNextWarning on the first warning. Subsequent warnings on this JdbcRowSet object will be chained to the RowSetWarning objects returned by the method RowSetWarning.getNextWarning. 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 an SQLException to be thrown.

Because it is always connected to its data source, a JdbcRowSet object can rely on the presence of active Statement, Connection, and ResultSet instances. This means that applications can obtain additional SQLWarning notifications by calling the getNextWarning methods that they provide. Disconnected Rowset objects, such as a CachedRowSet object, do not have access to these getNextWarning methods.

Returns:RowSetWarning

the first RowSetWarning object reported on this JdbcRowSet object or null if there are none

Exceptions

SQLException:: if this method is called on a closed JdbcRowSet object

See Also

RowSetWarning

getShowDeleted back to summary

getShowDeleted	back to summary
public boolean getShowDeleted() throws SQLException Retrieves a `boolean` indicating whether rows marked for deletion appear in the set of current rows. If `true` is returned, deleted rows are visible with the current rows. If `false` is returned, rows are not visible with the set of current rows. The default value is `false`. Standard rowset implementations may choose to restrict this behavior for security considerations or for certain deployment scenarios. The visibility of deleted rows is 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:boolean `true` if deleted rows are visible; `false` otherwise Exceptions SQLException: if a rowset implementation is unable to to determine whether rows marked for deletion remain visible See Also `setShowDeleted`

public boolean getShowDeleted() throws SQLException

Retrieves a boolean indicating whether rows marked for deletion appear in the set of current rows. If true is returned, deleted rows are visible with the current rows. If false is returned, rows are not visible with the set of current rows. The default value is false.

Standard rowset implementations may choose to restrict this behavior for security considerations or for certain deployment scenarios. The visibility of deleted rows is 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:boolean

true if deleted rows are visible; false otherwise

Exceptions

SQLException:: if a rowset implementation is unable to to determine whether rows marked for deletion remain visible

See Also

setShowDeleted

rollback back to summary

rollback	back to summary
public void rollback() throws SQLException Each `JdbcRowSet` contains a `Connection` object from the original `ResultSet` or JDBC properties passed to it. Undoes all changes made in the current transaction and releases any database locks currently held by this `Connection` object. This method should be used only when auto-commit mode has been disabled. Exceptions SQLException: if a database access error occurs or this `Connection` object within this `JdbcRowSet` is in auto-commit mode. See Also `rollback(Savepoint)`

public void rollback() throws SQLException

Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it. Undoes all changes made in the current transaction and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled.

Exceptions

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

See Also

rollback(Savepoint)

rollback back to summary

rollback	back to summary
public void rollback(Savepoint s) throws SQLException Each `JdbcRowSet` contains a `Connection` object from the original `ResultSet` or JDBC properties passed to it. Undoes all changes made in the current transaction to the last set savepoint and releases any database locks currently held by this `Connection` object. This method should be used only when auto-commit mode has been disabled. Parameters s:Savepoint The `Savepoint` to rollback to Exceptions SQLException: if a database access error occurs or this `Connection` object within this `JdbcRowSet` is in auto-commit mode. See Also `rollback`

public void rollback(Savepoint s) throws SQLException

Each JdbcRowSet contains a Connection object from the original ResultSet or JDBC properties passed to it. Undoes all changes made in the current transaction to the last set savepoint and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled.

Parameters

s:Savepoint: The Savepoint to rollback to

Exceptions

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

See Also

rollback

setAutoCommit back to summary

setAutoCommit	back to summary
public void setAutoCommit(boolean autoCommit) throws SQLException Each `JdbcRowSet` contains a `Connection` object from the original `ResultSet` or JDBC properties passed to it. This method wraps the `Connection`'s `getAutoCommit` method to allow an application to set the `JdbcRowSet` transaction behavior. Sets the current auto-commit mode for this `Connection` object. Parameters autoCommit:boolean `true` to enable auto-commit; `false` to disable auto-commit Exceptions SQLException: if a database access error occurs See Also `java.sql.Connection#setAutoCommit(boolean)`

public void setAutoCommit(boolean autoCommit) throws SQLException

Sets the current auto-commit mode for this Connection object.

Parameters

autoCommit:boolean: true to enable auto-commit; false to disable auto-commit

Exceptions

SQLException:: if a database access error occurs

setShowDeleted back to summary

setShowDeleted	back to summary
public void setShowDeleted(boolean b) throws SQLException Sets the property `showDeleted` to the given `boolean` value. This property determines whether rows marked for deletion continue to appear in the set of current rows. If the value is set to `true`, deleted rows are immediately visible with the set of current rows. If the value is set to `false`, the deleted rows are set as invisible with the current set of rows. Standard rowset implementations may choose to restrict this behavior for security considerations or for certain deployment scenarios. This is left as implementation-defined and does not represent standard behavior. Parameters b:boolean `true` if deleted rows should be shown; `false` otherwise Exceptions SQLException: if a rowset implementation is unable to to reset whether deleted rows should be visible See Also `getShowDeleted`

public void setShowDeleted(boolean b) throws SQLException

Sets the property showDeleted to the given boolean value. This property determines whether rows marked for deletion continue to appear in the set of current rows. If the value is set to true, deleted rows are immediately visible with the set of current rows. If the value is set to false, the deleted rows are set as invisible with the current set of rows.

Standard rowset implementations may choose to restrict this behavior for security considerations or for certain deployment scenarios. This is left as implementation-defined and does not represent standard behavior.

Parameters

b:boolean: true if deleted rows should be shown; false otherwise

Exceptions

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

See Also

getShowDeleted

public Interface JdbcRowSet

1.0 Overview

2.0 Creating a JdbcRowSet Object

Method Summary

Method Detail

2.0 Creating a `JdbcRowSet` Object