A table of data representing a database result set, which
is usually generated by executing a statement that queries the database.
A 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 false
when there are no more rows in the ResultSet
object,
it can be used in a while
loop to iterate through
the result set.
A default 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
produce ResultSet
objects that are scrollable and/or
updatable. The following code fragment, in which con
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
options.
Statement stmt = con.createStatement(
ResultSet.TYPE_SCROLL_INSENSITIVE,
ResultSet.CONCUR_UPDATABLE);
ResultSet rs = stmt.executeQuery("SELECT a, b FROM TABLE2");
// rs will be scrollable, will not show changes made by others,
// and will be updatable
The
ResultSet
interface provides
getter methods (
getBoolean
,
getLong
, 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
updater methods.
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 NAME
column
in the fifth row of the ResultSet
object
rs
and then uses the method updateRow
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 AINSWORTH
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 insertRow
.
rs.moveToInsertRow(); // moves cursor to the insert row
rs.updateString(1, "AINSWORTH"); // updates the
// first column of the insert row to be AINSWORTH
rs.updateInt(2,35); // updates the second column to be 35
rs.updateBoolean(3, true); // updates the third column to true
rs.insertRow();
rs.moveToCurrentRow();
A 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 ResultSet
object's columns are provided by the ResulSetMetaData
object returned by the ResultSet.getMetaData
method.