All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface java.sql.ResultSet

public interface ResultSet

A ResultSet provides access to a table of data generated by executing a Statement. The table rows are retrieved in sequence. Within a row its column values can be accessed in any order.

A ResultSet 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.

The getXXX methods retrieve column values for the current row. You can retrieve values either using the index number of the column, or by using the name of the column. In general using the column index will be more efficient. Columns are numbered from 1.

For maximum portability, ResultSet columns within each row should be read in left-to-right order and each column should be read only once.

For the getXXX methods, the JDBC driver attempts to convert the underlying data to the specified Java type and returns a suitable Java value. See the JDBC specification for allowable mappings from SQL types to Java types with the ResultSet.getXXX methods.

Column names used as input to getXXX methods are case insensitive. When performing a getXXX using a column name, if several columns have the same name, then 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. For columns that are NOT explicitly named in the query, it is best to use column numbers. If column names were used there is no way for the programmer to guarantee that they actually refer to the intended columns.

A ResultSet is automatically closed by the Statement that generated it when that Statement is closed, re-executed, or is used to retrieve the next result from a sequence of multiple results.

The number, types and properties of a ResultSet's columns are provided by the ResulSetMetaData object returned by the getMetaData method.

See Also:

executeQuery, getResultSet, ResultSetMetaData

clearWarnings()

After this call getWarnings returns null until a new warning is reported for this ResultSet.

close()

In some cases, it is desirable to immediately release a ResultSet's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.

findColumn(String)

Map a Resultset column name to a ResultSet column index.

getAsciiStream(int)

A column value can be retrieved as a stream of ASCII characters and then read in chunks from the stream.

getAsciiStream(String)

A column value can be retrieved as a stream of ASCII characters and then read in chunks from the stream.

getBigDecimal(int, int)

Get the value of a column in the current row as a java.lang.BigDecimal object.

getBigDecimal(String, int)

Get the value of a column in the current row as a java.lang.BigDecimal object.

getBinaryStream(int)

A column value can be retrieved as a stream of uninterpreted bytes and then read in chunks from the stream.

getBinaryStream(String)

A column value can be retrieved as a stream of uninterpreted bytes and then read in chunks from the stream.

getBoolean(int)

Get the value of a column in the current row as a Java boolean.

getBoolean(String)

Get the value of a column in the current row as a Java boolean.

getByte(int)

Get the value of a column in the current row as a Java byte.

getByte(String)

Get the value of a column in the current row as a Java byte.

getBytes(int)

Get the value of a column in the current row as a Java byte array.

getBytes(String)

Get the value of a column in the current row as a Java byte array.

getCursorName()

Get the name of the SQL cursor used by this ResultSet.

getDate(int)

Get the value of a column in the current row as a java.sql.Date object.

getDate(String)

Get the value of a column in the current row as a java.sql.Date object.

getDouble(int)

Get the value of a column in the current row as a Java double.

getDouble(String)

Get the value of a column in the current row as a Java double.

getFloat(int)

Get the value of a column in the current row as a Java float.

getFloat(String)

Get the value of a column in the current row as a Java float.

getInt(int)

Get the value of a column in the current row as a Java int.

getInt(String)

Get the value of a column in the current row as a Java int.

getLong(int)

Get the value of a column in the current row as a Java long.

getLong(String)

Get the value of a column in the current row as a Java long.

getMetaData()

The number, types and properties of a ResultSet's columns are provided by the getMetaData method.

getObject(int)

Get the value of a column in the current row as a Java object.

getObject(String)

Get the value of a column in the current row as a Java object.

getShort(int)

Get the value of a column in the current row as a Java short.

getShort(String)

Get the value of a column in the current row as a Java short.

getString(int)

Get the value of a column in the current row as a Java String.

getString(String)

Get the value of a column in the current row as a Java String.

getTime(int)

Get the value of a column in the current row as a java.sql.Time object.

getTime(String)

Get the value of a column in the current row as a java.sql.Time object.

getTimestamp(int)

Get the value of a column in the current row as a java.sql.Timestamp object.

getTimestamp(String)

Get the value of a column in the current row as a java.sql.Timestamp object.

getUnicodeStream(int)

A column value can be retrieved as a stream of Unicode characters and then read in chunks from the stream.

getUnicodeStream(String)

A column value can be retrieved as a stream of Unicode characters and then read in chunks from the stream.

getWarnings()

The first warning reported by calls on this ResultSet is returned.

next()

A ResultSet is initially positioned before its first row; the first call to next makes the first row the current row; the second call makes the second row the current row, etc.

wasNull()

A column may have the value of SQL NULL; wasNull reports whether the last column read had this special value.

    method next() returns boolean public abstract    Signals SQLException

A ResultSet is initially positioned before its first row; the first call to next makes the first row the current row; the second call makes the second row the current row, etc.

If an input stream from the previous row is open, it is implicitly closed. The ResultSet's warning chain is cleared when a new row is read.

Returns:

true if the new current row is valid; false if there are no more rows

Throws: SQLException

if a database-access error occurs.

    method close()  public abstract    Signals SQLException

In some cases, it is desirable to immediately release a ResultSet's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.

Note: A ResultSet is automatically closed by the Statement that generated it when that Statement is closed, re-executed, or is used to retrieve the next result from a sequence of multiple results. A ResultSet is also automatically closed when it is garbage collected.

Throws: SQLException

if a database-access error occurs.

    method wasNull() returns boolean public abstract    Signals SQLException

A column may have the value of SQL NULL; wasNull reports whether the last column read had this special value. Note that you must first call getXXX on a column to try to read its value and then call wasNull() to find if the value was the SQL NULL.

Returns:

true if last column read was SQL NULL

Throws: SQLException

if a database-access error occurs.

    method getString(columnIndex=int) returns String public abstract    Signals SQLException

Get the value of a column in the current row as a Java String.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getBoolean(columnIndex=int) returns boolean public abstract    Signals SQLException

Get the value of a column in the current row as a Java boolean.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is false

Throws: SQLException

if a database-access error occurs.

    method getByte(columnIndex=int) returns byte public abstract    Signals SQLException

Get the value of a column in the current row as a Java byte.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getShort(columnIndex=int) returns short public abstract    Signals SQLException

Get the value of a column in the current row as a Java short.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getInt(columnIndex=int) returns int public abstract    Signals SQLException

Get the value of a column in the current row as a Java int.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getLong(columnIndex=int) returns long public abstract    Signals SQLException

Get the value of a column in the current row as a Java long.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getFloat(columnIndex=int) returns float public abstract    Signals SQLException

Get the value of a column in the current row as a Java float.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getDouble(columnIndex=int) returns double public abstract    Signals SQLException

Get the value of a column in the current row as a Java double.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getBigDecimal(columnIndex=int, -
                         scale=int) returns BigDecimal public abstract    Signals SQLException

Get the value of a column in the current row as a java.lang.BigDecimal object.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

scale - the number of digits to the right of the decimal

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getBytes(columnIndex=int) returns byte[] public abstract    Signals SQLException

Get the value of a column in the current row as a Java byte array. The bytes represent the raw values returned by the driver.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getDate(columnIndex=int) returns Date public abstract    Signals SQLException

Get the value of a column in the current row as a java.sql.Date object.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getTime(columnIndex=int) returns Time public abstract    Signals SQLException

Get the value of a column in the current row as a java.sql.Time object.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getTimestamp(columnIndex=int) returns Timestamp public abstract    Signals SQLException

Get the value of a column in the current row as a java.sql.Timestamp object.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getAsciiStream(columnIndex=int) returns InputStream public abstract    Signals SQLException

A column value can be retrieved as a stream of ASCII characters and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into ASCII.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. . Also, a stream may return 0 for available() whether there is data available or not.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

a Java input stream that delivers the database column value as a stream of one byte ASCII characters. If the value is SQL NULL then the result is null.

Throws: SQLException

if a database-access error occurs.

    method getUnicodeStream(columnIndex=int) returns InputStream public abstract    Signals SQLException

A column value can be retrieved as a stream of Unicode characters and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into Unicode.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. . Also, a stream may return 0 for available() whether there is data available or not.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

a Java input stream that delivers the database column value as a stream of two byte Unicode characters. If the value is SQL NULL then the result is null.

Throws: SQLException

if a database-access error occurs.

    method getBinaryStream(columnIndex=int) returns InputStream public abstract    Signals SQLException

A column value can be retrieved as a stream of uninterpreted bytes and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARBINARY values.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. Also, a stream may return 0 for available() whether there is data available or not.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

a Java input stream that delivers the database column value as a stream of uninterpreted bytes. If the value is SQL NULL then the result is null.

Throws: SQLException

if a database-access error occurs.

    method getString(columnName=String) returns String public abstract    Signals SQLException

Get the value of a column in the current row as a Java String.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getBoolean(columnName=String) returns boolean public abstract    Signals SQLException

Get the value of a column in the current row as a Java boolean.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is false

Throws: SQLException

if a database-access error occurs.

    method getByte(columnName=String) returns byte public abstract    Signals SQLException

Get the value of a column in the current row as a Java byte.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getShort(columnName=String) returns short public abstract    Signals SQLException

Get the value of a column in the current row as a Java short.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getInt(columnName=String) returns int public abstract    Signals SQLException

Get the value of a column in the current row as a Java int.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getLong(columnName=String) returns long public abstract    Signals SQLException

Get the value of a column in the current row as a Java long.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getFloat(columnName=String) returns float public abstract    Signals SQLException

Get the value of a column in the current row as a Java float.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getDouble(columnName=String) returns double public abstract    Signals SQLException

Get the value of a column in the current row as a Java double.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is 0

Throws: SQLException

if a database-access error occurs.

    method getBigDecimal(columnName=String, -
                         scale=int) returns BigDecimal public abstract    Signals SQLException

Get the value of a column in the current row as a java.lang.BigDecimal object.

Parameters:

columnName - is the SQL name of the column

scale - the number of digits to the right of the decimal

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getBytes(columnName=String) returns byte[] public abstract    Signals SQLException

Get the value of a column in the current row as a Java byte array. The bytes represent the raw values returned by the driver.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getDate(columnName=String) returns Date public abstract    Signals SQLException

Get the value of a column in the current row as a java.sql.Date object.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getTime(columnName=String) returns Time public abstract    Signals SQLException

Get the value of a column in the current row as a java.sql.Time object.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getTimestamp(columnName=String) returns Timestamp public abstract    Signals SQLException

Get the value of a column in the current row as a java.sql.Timestamp object.

Parameters:

columnName - is the SQL name of the column

Returns:

the column value; if the value is SQL NULL, the result is null

Throws: SQLException

if a database-access error occurs.

    method getAsciiStream(columnName=String) returns InputStream public abstract    Signals SQLException

A column value can be retrieved as a stream of ASCII characters and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into ASCII.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream.

Parameters:

columnName - is the SQL name of the column

Returns:

a Java input stream that delivers the database column value as a stream of one byte ASCII characters. If the value is SQL NULL then the result is null.

Throws: SQLException

if a database-access error occurs.

    method getUnicodeStream(columnName=String) returns InputStream public abstract    Signals SQLException

A column value can be retrieved as a stream of Unicode characters and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into Unicode.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream.

Parameters:

columnName - is the SQL name of the column

Returns:

a Java input stream that delivers the database column value as a stream of two byte Unicode characters. If the value is SQL NULL then the result is null.

Throws: SQLException

if a database-access error occurs.

    method getBinaryStream(columnName=String) returns InputStream public abstract    Signals SQLException

A column value can be retrieved as a stream of uninterpreted bytes and then read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARBINARY values.

Note: All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream.

Parameters:

columnName - is the SQL name of the column

Returns:

a Java input stream that delivers the database column value as a stream of uninterpreted bytes. If the value is SQL NULL then the result is null.

Throws: SQLException

if a database-access error occurs.

    method getWarnings() returns SQLWarning public abstract    Signals SQLException

The first warning reported by calls on this ResultSet is returned. Subsequent ResultSet warnings will be chained to this SQLWarning.

The warning chain is automatically cleared each time a new row is read.

Note: This warning chain only covers warnings caused by ResultSet methods. Any warning caused by statement methods (such as reading OUT parameters) will be chained on the Statement object.

Returns:

the first SQLWarning or null

Throws: SQLException

if a database-access error occurs.

    method clearWarnings()  public abstract    Signals SQLException

After this call getWarnings returns null until a new warning is reported for this ResultSet.

Throws: SQLException

if a database-access error occurs.

    method getCursorName() returns String public abstract    Signals SQLException

Get the name of the SQL cursor used by this ResultSet.

In SQL, a result table is retrieved through a cursor that is named. The current row of a result can be updated or deleted using a positioned update/delete statement that references the cursor name.

JDBC supports this SQL feature by providing the name of the SQL cursor used by a ResultSet. The current row of a ResultSet is also the current row of this SQL cursor.

Note: If positioned update is not supported a SQLException is thrown

Returns:

the ResultSet's SQL cursor name

Throws: SQLException

if a database-access error occurs.

    method getMetaData() returns ResultSetMetaData public abstract    Signals SQLException

The number, types and properties of a ResultSet's columns are provided by the getMetaData method.

Returns:

the description of a ResultSet's columns

Throws: SQLException

if a database-access error occurs.

    method getObject(columnIndex=int) returns Object public abstract    Signals SQLException

Get the value of a column in the current row as a Java object.

This method will return the value of the given column as a Java object. The type of the Java object will be the default Java Object type corresponding to the column's SQL type, following the mapping specified in the JDBC spec.

This method may also be used to read datatabase specific abstract data types.

Parameters:

columnIndex - the first column is 1, the second is 2, ...

Returns:

A java.lang.Object holding the column value.

Throws: SQLException

if a database-access error occurs.

    method getObject(columnName=String) returns Object public abstract    Signals SQLException

Get the value of a column in the current row as a Java object.

This method will return the value of the given column as a Java object. The type of the Java object will be the default Java Object type corresponding to the column's SQL type, following the mapping specified in the JDBC spec.

This method may also be used to read datatabase specific abstract data types.

Parameters:

columnName - is the SQL name of the column

Returns:

A java.lang.Object holding the column value.

Throws: SQLException

if a database-access error occurs.

    method findColumn(columnName=String) returns int public abstract    Signals SQLException

Map a Resultset column name to a ResultSet column index.

Parameters:

columnName - the name of the column

Returns:

the column index

Throws: SQLException

if a database-access error occurs.

All Packages  Class Hierarchy  This Package  Previous  Next  Index