A table of data representing a database result set, which
is usually generated by executing a statement that queries the database.
ResultSet object maintains a cursor pointing
to its current row of data. Initially the cursor is positioned
before the first row. The
next method moves the
cursor to the next row, and because it returns
when there are no more rows in the
it can be used in a
while loop to iterate through
the result set.
ResultSet object is not updatable and
has a cursor that moves forward only. Thus, you can
iterate through it only once and only from the first row to the
last row. It is possible to
ResultSet objects that are scrollable and/or
updatable. The following code fragment, in which
is a valid
Connection object, illustrates how to make
a result set that is scrollable and insensitive to updates by others, and
that is updatable. See
ResultSet fields for other
Statement stmt = con.createStatement(
ResultSet rs = stmt.executeQuery("SELECT a, b FROM TABLE2");
// rs will be scrollable, will not show changes made by others,
// and will be updatable
, and so on)
for retrieving column values from the current row.
Values can be retrieved using either the index number of the
column or the name of the column. In general, using the
column index will be more efficient. Columns are numbered from 1.
For maximum portability, result set columns within each row should be
read in left-to-right order, and each column should be read only once.
For the getter methods, a JDBC driver attempts
to convert the underlying data to the Java type specified in the
getter method and returns a suitable Java value. The JDBC specification
has a table showing the allowable mappings from SQL types to Java types
that can be used by the
ResultSet getter methods.
Column names used as input to getter methods are case
insensitive. When a getter method is called with
a column name and several columns have the same name,
the value of the first matching column will be returned.
The column name option is
designed to be used when column names are used in the SQL
query that generated the result set.
For columns that are NOT explicitly named in the query, it
is best to use column numbers. If column names are used, the
programmer should take care to guarantee that they uniquely refer to
the intended columns, which can be assured with the SQL AS clause.
A set of updater methods were added to this interface
in the JDBC 2.0 API (JavaTM 2 SDK,
Standard Edition, version 1.2). The comments regarding parameters
to the getter methods also apply to parameters to the
The updater methods may be used in two ways:
- to update a column value in the current row. In a scrollable
ResultSet object, the cursor can be moved backwards
and forwards, to an absolute position, or to a position
relative to the current row.
The following code fragment updates the
in the fifth row of the
rs and then uses the method
to update the data source table from which
rs was derived.
rs.absolute(5); // moves the cursor to the fifth row of rs
rs.updateString("NAME", "AINSWORTH"); // updates the
NAME column of row 5 to be
rs.updateRow(); // updates the row in the data source
- to insert column values into the insert row. An updatable
ResultSet object has a special row associated with
it that serves as a staging area for building a row to be inserted.
The following code fragment moves the cursor to the insert row, builds
a three-column row, and inserts it into
rs and into
the data source table using the method
rs.moveToInsertRow(); // moves cursor to the insert row
rs.updateString(1, "AINSWORTH"); // updates the
// first column of the insert row to be
rs.updateInt(2,35); // updates the second column to be
rs.updateBoolean(3, true); // updates the third column to
ResultSet object is automatically closed when the
Statement object that
generated it is closed, re-executed, or used
to retrieve the next result from a sequence of multiple results.
The number, types and properties of a
object's columns are provided by the
object returned by the