Java 1.2 How-To/JavaHowTo.iso/3rdParty/jbuilder/unsupported/JDK1.2beta3/SOURCE/SRC.ZIP/java/sql/ResultSet.java

Java Source | 1998-03-20 | 47.3 KB | 1,454 lines

/*
 * @(#)ResultSet.java    1.12 98/03/18
 *
 * Copyright 1996-1998 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

package java.sql;

import java.math.BigDecimal;

/**
 * <P>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.
 *
 * <P>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.
 *
 * <P>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.
 *
 * <P>For maximum portability, ResultSet columns within each row should be
 * read in left-to-right order and each column should be read only once.
 *
 * <P>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.
 *
 * <P>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.
 *
 * <P>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.
 *
 * <P>The number, types and properties of a ResultSet's columns are
 * provided by the ResulSetMetaData object returned by the getMetaData
 * method.
 *
 * @see Statement#executeQuery
 * @see Statement#getResultSet
 * @see ResultSetMetaData
 */

public interface ResultSet {

    /**
     * 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.
     *
     * <P>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.
     *
     * @return true if the new current row is valid; false if there
     * are no more rows
     * @exception SQLException if a database-access error occurs.
     */
    boolean next() throws 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.
     *
     * <P><B>Note:</B> 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.
     *
     * @exception SQLException if a database-access error occurs.
     */
    void close() throws 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.
     *
     * @return true if last column read was SQL NULL
     * @exception SQLException if a database-access error occurs.
     */
    boolean wasNull() throws SQLException;

    //======================================================================
    // Methods for accessing results by column index
    //======================================================================

    /**
     * Get the value of a column in the current row as a Java String.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    String getString(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java boolean.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is false
     * @exception SQLException if a database-access error occurs.
     */
    boolean getBoolean(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java byte.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    byte getByte(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java short.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    short getShort(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java int.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    int getInt(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java long.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    long getLong(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java float.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    float getFloat(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java double.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    double getDouble(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a java.lang.BigDecimal object.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @param scale the number of digits to the right of the decimal
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    BigDecimal getBigDecimal(int columnIndex, int scale) throws 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.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    byte[] getBytes(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a java.sql.Date object.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    java.sql.Date getDate(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a java.sql.Time object.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    java.sql.Time getTime(int columnIndex) throws SQLException;

    /**
     * Get the value of a column in the current row as a java.sql.Timestamp object.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    java.sql.Timestamp getTimestamp(int columnIndex) throws 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.
     *
     * <P><B>Note:</B> 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.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return 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.
     * @exception SQLException if a database-access error occurs.
     */
    java.io.InputStream getAsciiStream(int columnIndex) throws 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.
     *
     * <P><B>Note:</B> 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.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return 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.
     * @exception SQLException if a database-access error occurs.
     * @deprecated
     */
    java.io.InputStream getUnicodeStream(int columnIndex) throws 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.
     *
     * <P><B>Note:</B> 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.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return 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.
     * @exception SQLException if a database-access error occurs.
     */
    java.io.InputStream getBinaryStream(int columnIndex)
        throws SQLException;


    //======================================================================
    // Methods for accessing results by column name
    //======================================================================

    /**
     * Get the value of a column in the current row as a Java String.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    String getString(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java boolean.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is false
     * @exception SQLException if a database-access error occurs.
     */
    boolean getBoolean(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java byte.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    byte getByte(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java short.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    short getShort(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java int.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    int getInt(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java long.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    long getLong(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java float.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    float getFloat(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a Java double.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is 0
     * @exception SQLException if a database-access error occurs.
     */
    double getDouble(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a java.lang.BigDecimal
     * object.
     *
     * @param columnName is the SQL name of the column
     * @param scale the number of digits to the right of the decimal
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    BigDecimal getBigDecimal(String columnName, int scale) throws 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.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    byte[] getBytes(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a java.sql.Date object.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    java.sql.Date getDate(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a java.sql.Time object.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    java.sql.Time getTime(String columnName) throws SQLException;

    /**
     * Get the value of a column in the current row as a java.sql.Timestamp object.
     *
     * @param columnName is the SQL name of the column
     * @return the column value; if the value is SQL NULL, the result is null
     * @exception SQLException if a database-access error occurs.
     */
    java.sql.Timestamp getTimestamp(String columnName) throws 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.
     *
     * <P><B>Note:</B> 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.
     *
     * @param columnName is the SQL name of the column
     * @return 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.
     * @exception SQLException if a database-access error occurs.
     */
    java.io.InputStream getAsciiStream(String columnName) throws 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.
     *
     * <P><B>Note:</B> 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.
     *
     * @param columnName is the SQL name of the column
     * @return 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.
     * @exception SQLException if a database-access error occurs.
     * @deprecated
     */
    java.io.InputStream getUnicodeStream(String columnName) throws 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.
     *
     * <P><B>Note:</B> 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.
     *
     * @param columnName is the SQL name of the column
     * @return 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.
     * @exception SQLException if a database-access error occurs.
     */
    java.io.InputStream getBinaryStream(String columnName)
        throws SQLException;


    //=====================================================================
    // Advanced features:
    //=====================================================================

    /**
     * <p>The first warning reported by calls on this ResultSet is
     * returned. Subsequent ResultSet warnings will be chained to this
     * SQLWarning.
     *
     * <P>The warning chain is automatically cleared each time a new
     * row is read.
     *
     * <P><B>Note:</B> 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.
     *
     * @return the first SQLWarning or null
     * @exception SQLException if a database-access error occurs.
     */
    SQLWarning getWarnings() throws SQLException;

    /**
     * After this call getWarnings returns null until a new warning is
     * reported for this ResultSet.
     *
     * @exception SQLException if a database-access error occurs.
     */
    void clearWarnings() throws SQLException;

    /**
     * Get the name of the SQL cursor used by this ResultSet.
     *
     * <P>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.
     *
     * <P>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.
     *
     * <P><B>Note:</B> If positioned update is not supported a
     * SQLException is thrown
     *
     * @return the ResultSet's SQL cursor name
     * @exception SQLException if a database-access error occurs.
     */
    String getCursorName() throws SQLException;

    /**
     * The number, types and properties of a ResultSet's columns
     * are provided by the getMetaData method.
     *
     * @return the description of a ResultSet's columns
     * @exception SQLException if a database-access error occurs.
     */
    ResultSetMetaData getMetaData() throws SQLException;

    /**
     * <p>Get the value of a column in the current row as a Java object.
     *
     * <p>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.
     *
     * <p>This method may also be used to read datatabase specific abstract
     * data types.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return A java.lang.Object holding the column value.
     * @exception SQLException if a database-access error occurs.
     */
    Object getObject(int columnIndex) throws SQLException;

    /**
     * <p>Get the value of a column in the current row as a Java object.
     *
     * <p>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.
     *
     * <p>This method may also be used to read datatabase specific abstract
     * data types.
     *
     * @param columnName is the SQL name of the column
     * @return A java.lang.Object holding the column value.
     * @exception SQLException if a database-access error occurs.
     */
    Object getObject(String columnName) throws SQLException;

    //----------------------------------------------------------------

    /**
     * Map a Resultset column name to a ResultSet column index.
     *
     * @param columnName the name of the column
     * @return the column index
     * @exception SQLException if a database-access error occurs.
     */
    int findColumn(String columnName) throws SQLException;


    //--------------------------JDBC 2.0-----------------------------------

    //---------------------------------------------------------------------
    // Getter's and Setter's
    //---------------------------------------------------------------------

    /**
     * JDBC 2.0
     *
     * <p>Get the value of a column in the current row as a java.io.Reader.
     */
    java.io.Reader getCharacterStream(int columnIndex) throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Get the value of a column in the current row as a java.io.Reader.
     */
    java.io.Reader getCharacterStream(String columnName) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get the value of a column in the current row as a java.lang.BigDecimal
     * object.
     *
     * @param columnIndex the first column is 1, the second is 2, ...
     * @return the column value (full precision); if the value is SQL NULL,
     * the result is null
     * @exception SQLException if a database-access error occurs.
     */
    BigDecimal getBigDecimal(int columnIndex) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get the value of a column in the current row as a java.lang.BigDecimal
     * object.
     *
     */
    BigDecimal getBigDecimal(String columnName) throws SQLException;

    //---------------------------------------------------------------------
    // Traversal/Positioning
    //---------------------------------------------------------------------

    /**
     * JDBC 2.0
     *
     * <p>Determine if the cursor is before the first row in the result
     * set.
     *
     * @return true if before the first row, false otherwise. Returns
     * false when the result set contains no rows.
     * @exception SQLException if a database-access error occurs.
     */
    boolean isBeforeFirst() throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Determine if the cursor is after the last row in the result
     * set.
     *
     * @return true if after the last row, false otherwise.  Returns
     * false when the result set contains no rows.
     * @exception SQLException if a database-access error occurs.
     */
    boolean isAfterLast() throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Determine if the cursor is on the first row of the result set.
     *
     * @return true if on the first row, false otherwise.
     * @exception SQLException if a database-access error occurs.
     */
    boolean isFirst() throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Determine if the cursor is on the last row of the result set.
     * Note: Calling isLast() may be expensive since the JDBC driver
     * might need to fetch ahead one row in order to determine
     * whether the current row is the last row in the result set.
     *
     * @return true if on the last row, false otherwise.
     * @exception SQLException if a database-access error occurs.
     */
    boolean isLast() throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Moves to the front of the result set, just before the
     * first row. Has no effect if the result set contains no rows.
     *
     * @exception SQLException if a database-access error occurs, or
     * result set type is TYPE_FORWARD_ONLY
     */
    void beforeFirst() throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Moves to the end of the result set, just after the last
     * row.  Has no effect if the result set contains no rows.
     *
     * @exception SQLException if a database-access error occurs, or
     * result set type is TYPE_FORWARD_ONLY.
     */
    void afterLast() throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Moves to the first row in the result set.
     *
     * @return true if on a valid row, false if no rows in the result set.
     * @exception SQLException if a database-access error occurs, or
     * result set type is TYPE_FORWARD_ONLY.
     */
    boolean first() throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Moves to the last row in the result set.
     *
     * @return true if on a valid row, false if no rows in the result set.
     * @exception SQLException if a database-access error occurs, or
     * result set type is TYPE_FORWARD_ONLY.
     */
    boolean last() throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Determine the current row number.  The first row is number 1, the
     * second number 2, etc.
     *
     * @return the current row number, else return 0 if there is no
     * current row.
     * @exception SQLException if a database-access error occurs.
     */
    int getRow() throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Move to an absolute row number in the result set.
     *
     * <p>If row is positive, moves to an absolute row with respect to the
     * beginning of the result set.  The first row is row 1, the second
     * is row 2, etc.
     *
     * <p>If row is negative, moves to an absolute row position with respect to
     * the end of result set.  For example, calling absolute(-1) positions the
     * cursor on the last row, absolute(-2) indicates the next-to-last
     * row, etc.
     *
     * <p>An attempt to position the cursor beyond the first/last row in
     * the result set, leaves the cursor before/after the first/last
     * row, respectively.
     *
     * <p>Note: Calling absolute(1) is the same as calling first().
     * Calling absolute(-1) is the same as calling last().
     *
     * @return true if on the result set, false if off.
     * @exception SQLException if a database-access error occurs, or
     * row is 0, or result set type is TYPE_FORWARD_ONLY.
     */
    boolean absolute( int row ) throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Moves a relative number of rows, either positive or negative.
     * Attempting to move beyond the first/last row in the
     * result set positions the cursor before/after the
     * the first/last row. Calling relative(0) is valid, but does
     * not change the cursor position.
     *
     * <p>Note: Calling relative(1) is different than calling next()
     * since is makes sense to call next() when there is no current row,
     * for example, when the cursor is positioned before the first row
     * or after the last row of the result set.
     *
     * @return true if on a row, false otherwise.
     * @exception SQLException if a database-access error occurs, or there
     * is no current row, or result set type is TYPE_FORWARD_ONLY.
     */
    boolean relative( int rows ) throws SQLException;

    /**
     * JDBC 2.0
     *
     * <p>Moves to the previous row in the result set.
     *
     * <p>Note: previous() is not the same as relative(-1) since it
     * makes sense to call previous() when there is no current row.
     *
     * @return true if on a valid row, false if off the result set.
     * @exception SQLException if a database-access error occurs, or
     * result set type is TYPE_FORWAR_DONLY.
     */
    boolean previous() throws SQLException;

    //---------------------------------------------------------------------
    // Properties
    //---------------------------------------------------------------------

    /**
     * JDBC 2.0
     *
     * The rows in a result set will be processed in a forward direction;
     * first-to-last.
     */
    int FETCH_FORWARD = 1000;

    /**
     * JDBC 2.0
     *
     * The rows in a result set will be processed in a reverse direction;
     * last-to-first.
     */
    int FETCH_REVERSE = 1001;

    /**
     * JDBC 2.0
     *
     * The order in which rows in a result set will be processed is unknown.
     */
    int FETCH_UNKNOWN = 1002;

    /**
     * JDBC 2.0
     *
     * Give a hint as to the direction in which the rows in this result set
     * will be processed.  The initial value is determined by the statement
     * that produced the result set.  The fetch direction may be changed
     * at any time.
     *
     * @exception SQLException if a database-access error occurs, or
     * the result set type is TYPE_FORWARD_ONLY and direction is not
     * FETCH_FORWARD.
     */
    void setFetchDirection(int direction) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Return the fetch direction for this result set.
     *
     * @exception SQLException if a database-access error occurs
     */
    int getFetchDirection() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Give the JDBC driver a hint as to the number of rows that should
     * be fetched from the database when more rows are needed for this result
     * set.  If the fetch size specified is zero, then the JDBC driver
     * ignores the value, and is free to make its own best guess as to what
     * the fetch size should be.  The default value is set by the statement
     * that creates the result set.  The fetch size may be changed at any
     * time.
     *
     * @param rows the number of rows to fetch
     * @exception SQLException if a database-access error occurs, or the
     * condition 0 <= rows <= this.getMaxRows() is not satisfied.
     */
    void setFetchSize(int rows) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Return the fetch size for this result set.
     *
     * @exception SQLException if a database-access error occurs
     */
    int getFetchSize() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Give the JDBC driver a hint as to the number of keys contained in the
     * keyset of a TYPE_KEYSET result set.  The number of keys specified only
     * affects this result set. The initial value is set by the statement
     * that created the result set.  The keyset size may be changed at any
     * time.
     *
     * @param rows the number of keys in a keyset
     * @exception SQLException if a database-access error occurs, or the
     * condition this.getFetchSize() <= keys <= this.getMaxRows() is not
     * satisfied.
     */
    void setKeysetSize(int keys) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Return the keyset size for this result set.
     *
     * @exception SQLException if a database-access error occurs
     */
    int getKeysetSize() throws SQLException;

    /**
     * JDBC 2.0
     */
    int TYPE_FORWARD_ONLY = 1003;

    /**
     * JDBC 2.0
     */
    int TYPE_STATIC = 1004;

    /**
     * JDBC 2.0
     */
    int TYPE_KEYSET = 1005;

    /**
     * JDBC 2.0
     */
    int TYPE_DYNAMIC = 1006;

    /**
     * JDBC 2.0
     *
     * Return the type of this result set.  The type is determined based
     * on the statement that created the result set.
     *
     * @return TYPE_FORWARD_ONLY, TYPE_STATIC, TYPE_KEYSET, or
     * TYPE_DYNAMIC.
     * @exception SQLException if a database-access error occurs
     */
    int getType() throws SQLException;

    /**
     * JDBC 2.0
     *
     *
     */
    int CONCUR_READ_ONLY = 1007;

    /**
     * JDBC 2.0
     *
     *
     */
    int CONCUR_LOCK = 1008;

    /**
     * JDBC 2.0
     *
     *
     */
    int CONCUR_VERSION = 1009;

    /**
     * JDBC 2.0
     *
     *
     */
    int CONCUR_VALUE = 1010;

    /**
     * JDBC 2.0
     *
     * Return the concurrency of this result set.  The concurrency
     * used is determined by the statement that created the result set.
     *
     * @return the concurrency type, CONCUR_READ_ONLY, etc.
     * @exception SQLException if a database-access error occurs
     */
    int getConcurrency() throws SQLException;

    //---------------------------------------------------------------------
    // Updates
    //---------------------------------------------------------------------

    /**
     * JDBC 2.0
     *
     * Determine if the current row has been updated.
     *
     * The value returned depends on whether or not the result set
     * can detect changes, see DatabaseMetaData.rowChangesAreDetected().
     *
     * @return true if updated
     * @exception SQLException if a database-access error occurs
     *
     * @see DatabaseMetaData#detectsRowChanges
     */
    boolean rowUpdated() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Determine if the current row has been inserted.
     *
     * The value returned depends on whether or not the result set
     * can detect changes, see DatabaseMetaData.rowChangesAreDetected().
     *
     * @return true if inserted
     * @exception SQLException if a database-access error occurs
     *
     * @see DatabaseMetaData#detectsRowChanges
     */
    boolean rowInserted() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Determine if this row has been deleted.  A result set of type
     * keyset or static may contain rows that have been deleted.
     *
     * The value returned depends on whether or not the result set
     * can detect changes, see DatabaseMetaData.rowChangesAreDetected().
     *
     * @return true if deleted
     * @exception SQLException if a database-access error occurs
     *
     * @see DatabaseMetaData#detectsRowChanges
     */
    boolean rowDeleted() throws SQLException;

    /**
     * The updateXXX() methods are used to update column values in the
     * current row, or the insert row.
     * The updateXXX() methods do not update the underlying
     * database, instead, they update an in-memory copy of the data read
     * from the database.
     *
     * The insert row is a special row associated with an updatable
     * result set.  It is essentially a buffer where a new row may
     * be constructed by calling the updateXXX() methods prior to
     * inserting the row into the result set.
     *
     * To update the underlying database, updateRow(), insertRow, or
     * deleteRow may be called.
     */

    /**
     * JDBC 2.0
     */
    void updateNull(int columnIndex) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateBoolean(int columnIndex, boolean x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateByte(int columnIndex, byte x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateShort(int columnIndex, short x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateInt(int columnIndex, int x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateLong(int columnIndex, long x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateFloat(int columnIndex, float x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateDouble(int columnIndex, double x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateBigDecimal(int columnIndex, BigDecimal x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateString(int columnIndex, String x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateBytes(int columnIndex, byte x[]) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateDate(int columnIndex, java.sql.Date x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateTime(int columnIndex, java.sql.Time x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateTimestamp(int columnIndex, java.sql.Timestamp x)
      throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateAsciiStream(int columnIndex,
               java.io.InputStream x,
               int length) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateBinaryStream(int columnIndex,
                java.io.InputStream x,
                int length) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateCharacterStream(int columnIndex,
                 java.io.Reader reader,
                 int length) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateObject(int columnIndex, Object x, int scale)
      throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateObject(int columnIndex, Object x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateNull(String columnName) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateBoolean(String columnName, boolean x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateByte(String columnName, byte x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateShort(String columnName, short x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateInt(String columnName, int x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateLong(String columnName, long x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateFloat(String columnName, float x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateDouble(String columnName, double x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateBigDecimal(String columnName, BigDecimal x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateString(String columnName, String x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateBytes(String columnName, byte x[]) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateDate(String columnName, java.sql.Date x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateTime(String columnName, java.sql.Time x) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateTimestamp(String columnName, java.sql.Timestamp x)
      throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateAsciiStream(String columnName,
               java.io.InputStream x,
               int length) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateBinaryStream(String columnName,
                java.io.InputStream x,
                int length) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateCharacterStream(String columnName,
                 java.io.Reader reader,
                 int length) throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateObject(String columnName, Object x, int scale)
      throws SQLException;

    /**
     * JDBC 2.0
     */
    void updateObject(String columnName, Object x) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Insert the contents of the insert row into the result set and
     * the database.  Must be on the insert row when this method is called.
     *
     * @exception SQLException if a database-access error occurs
     */
    void insertRow() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Update the underlying database with the new contents of the
     * current row.  Cannot be called when on the insert row.
     */
    void updateRow() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Delete the current row from the result set and the underlying
     * database.  Cannot be called when on the insert row.
     *
     * @exception SQLException if a database-access error occurs
     */
    void deleteRow() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Refresh the value of the current row with the value in the database.
     * Cannot be called when on the insert row.
     *
     * @exception SQLException if a database-access error occurs
     */
    void refreshRow() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Move to the insert row.  The current row is remembered.
     *
     * Only the updateXXX() and insertRow() methods may be called
     * when the result set is in insert mode.
     *
     * @exception SQLException if a database-access error occurs
     */
    void moveToInsertRow() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Move the cursor to the current row.  Has no effect unless the
     * cursor is on the insert row.
     *
     * @exception SQLException if a database-access error occurs
     */
    void moveToCurrentRow() throws SQLException;

    /**
     * JDBC 2.0
     *
     * New behavior for getObject.
     * The behavior of the current overloading of method getObject
     * is extended to materialize data of SQL user-defined types.
     * When the column @i is a UDT value, the behavior of this
     * method is as if it were a call to:
     * getObject(i, this.getConnection().getTypeMap())
     *
     * @param i the first column is 1, the second is 2, ...
     * @return the object representing the SQL user-defined type
     *
       Object  getObject (int i) throws SQLException;
     */

    /**
     * JDBC 2.0
     *
     * Returns the value of column @i.  Use the @map to determine
     * the class from which to construct data of SQL Named Types.
     *
     * @param i the first column is 1, the second is 2, ...
     * @param map the mapping from SQL type names to Java classes
     * @return the object representing the SQL user-defined type
     */
     Object  getObject (int i, java.util.Map map) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a REF(<structured-type>) column.
     *
     * @param i the first column is 1, the second is 2, ...
     * @return an object representing data of an SQL REF Type
     */
     Ref getRef (int i) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a LOCATOR(BLOB) column.
     *
     * @param i the first column is 1, the second is 2, ...
     * @return an object representing data of a locator to a BLOB
     */
     BlobLocator GetBlobLocator (int i) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a LOCATOR(CLOB) column.
     *
     * @param i the first column is 1, the second is 2, ...
     * @return an object representing data of a locator to a CLOB
     */
     ClobLocator getClobLocator (int i) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a LOCATOR(<structured-type>) column.
     *
     * @param i the first column is 1, the second is 2, ...
     * @return an object representing data of a locator to an instance
     * of a Structured Type
     */
     StructLocator getStructLocator (int i) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a LOCATOR(<array>) column.
     *
     * @param i the first column is 1, the second is 2, ...
     * @return an object representing data of a locator to an SQL array
     */
     ArrayLocator getArrayLocator (int i) throws SQLException;

     /**
      * JDBC 2.0
      *
      * Return the Statement that produced te ResultSet.
      */
     Statement getStatement() throws SQLException;

    /**
     * JDBC 2.0
     *
     * Returns the value of column @i.  Use the @map to determine
     * the class from which to construct data of SQL Named Types.
     *
     * @param i the first column is 1, the second is 2, ...
     * @param map the mapping from SQL type names to Java classes
     * @return the object representing the SQL user-defined type
     */
     Object  getObject (String colName, java.util.Map map)
       throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a REF(<structured-type>) column.
     *
     * @param i the column name
     * @return an object representing data of an SQL REF Type
     */
     Ref getRef (String colName) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a LOCATOR(BLOB) column.
     *
     * @param i the column name
     * @return an object representing data of a locator to a BLOB
     */
     BlobLocator GetBlobLocator (String colName) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a LOCATOR(CLOB) column.
     *
     * @param i the column name
     * @return an object representing data of a locator to a CLOB
     */
     ClobLocator getClobLocator (String colName) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a LOCATOR(<structured-type>) column.
     *
     * @param i the column name
     * @return an object representing data of a locator to an instance
     * of a Structured Type
     */
     StructLocator getStructLocator (String colName) throws SQLException;

    /**
     * JDBC 2.0
     *
     * Get a LOCATOR(<array>) column.
     *
     * @param i the column name
     * @return an object representing data of a locator to an SQL array
     */
     ArrayLocator getArrayLocator (String colName) throws SQLException;
}