/*

 * Copyright 1996-2006 Sun Microsystems, Inc.  All Rights Reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Sun designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Sun in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

 * CA 95054 USA or visit www.sun.com if you need additional information or

 * have any questions.

 */

package java.sql;

import java.math.BigDecimal;

import java.util.Calendar;

import java.io.Reader;

import java.io.InputStream;

/**

 * A table of data representing a database result set, which

 * is usually generated by executing a statement that queries the database.

 *

 * <P>A <code>ResultSet</code> object  maintains a cursor pointing

 * to its current row of data.  Initially the cursor is positioned

 * before the first row. The <code>next</code> method moves the

 * cursor to the next row, and because it returns <code>false</code>

 * when there are no more rows in the <code>ResultSet</code> object,

 * it can be used in a <code>while</code> loop to iterate through

 * the result set.

 * <P>

 * A default <code>ResultSet</code> 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 <code>ResultSet</code> objects that are scrollable and/or

 * updatable.  The following code fragment, in which <code>con</code>

 * is a valid <code>Connection</code> object, illustrates how to make

 * a result set that is scrollable and insensitive to updates by others, and

 * that is updatable. See <code>ResultSet</code> fields for other

 * options.

 * <PRE>

 *

 *       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

 *

 * </PRE>

 * The <code>ResultSet</code> interface provides

 * <i>getter</i> methods (<code>getBoolean</code>, <code>getLong</code>, 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.

 *

 * <P>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 <code>ResultSet</code> getter methods.

 * <P>

 * <P>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 <i>AS</i> clause.

 * <P>

 * A set of updater methods were added to this interface

 * in the JDBC 2.0 API (Java<sup><font size=-2>TM</font></sup> 2 SDK,

 * Standard Edition, version 1.2). The comments regarding parameters

 * to the getter methods also apply to parameters to the

 * updater methods.

 *<P>

 * The updater methods may be used in two ways:

 * <ol>

 * <LI>to update a column value in the current row.  In a scrollable

 *     <code>ResultSet</code> 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 <code>NAME</code> column

 *     in the fifth row of the <code>ResultSet</code> object

 *     <code>rs</code> and then uses the method <code>updateRow</code>

 *     to update the data source table from which <code>rs</code> was derived.

 * <PRE>

 *

 *       rs.absolute(5); // moves the cursor to the fifth row of rs

 *       rs.updateString("NAME", "AINSWORTH"); // updates the

 *          // <code>NAME</code> column of row 5 to be <code>AINSWORTH</code>

 *       rs.updateRow(); // updates the row in the data source

 *

 * </PRE>

 * <LI>to insert column values into the insert row.  An updatable

 *     <code>ResultSet</code> 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 <code>rs</code> and into

 *     the data source table using the method <code>insertRow</code>.

 * <PRE>

 *

 *       rs.moveToInsertRow(); // moves cursor to the insert row

 *       rs.updateString(1, "AINSWORTH"); // updates the

 *          // first column of the insert row to be <code>AINSWORTH</code>

 *       rs.updateInt(2,35); // updates the second column to be <code>35</code>

 *       rs.updateBoolean(3, true); // updates the third column to <code>true</code>

 *       rs.insertRow();

 *       rs.moveToCurrentRow();

 *

 * </PRE>

 * </ol>

 * <P>A <code>ResultSet</code> object is automatically closed when the

 * <code>Statement</code> object that

 * generated it is closed, re-executed, or used

 * to retrieve the next result from a sequence of multiple results.

 *

 * <P>The number, types and properties of a <code>ResultSet</code>

 * object's columns are provided by the <code>ResulSetMetaData</code>

 * object returned by the <code>ResultSet.getMetaData</code> method.

 *

 * @see Statement#executeQuery

 * @see Statement#getResultSet

 * @see ResultSetMetaData

 */

public interface ResultSet extends Wrapper {

    /**

     * Moves the cursor froward one row from its current position.

     * A <code>ResultSet</code> cursor is initially positioned

     * before the first row; the first call to the method

     * <code>next</code> makes the first row the current row; the

     * second call makes the second row the current row, and so on.

     * <p>

     * When a call to the <code>next</code> method returns <code>false</code>,

     * the cursor is positioned after the last row. Any

     * invocation of a <code>ResultSet</code> method which requires a

     * current row will result in a <code>SQLException</code> being thrown.

     *  If the result set type is <code>TYPE_FORWARD_ONLY</code>, it is vendor specified

     * whether their JDBC driver implementation will return <code>false</code> or

     *  throw an <code>SQLException</code> on a

     * subsequent call to <code>next</code>.

     *

     * <P>If an input stream is open for the current row, a call

     * to the method <code>next</code> will

     * implicitly close it. A <code>ResultSet</code> object's

     * warning chain is cleared when a new row is read.

     *

     * @return <code>true</code> if the new current row is valid;

     * <code>false</code> if there are no more rows

     * @exception SQLException if a database access error occurs or this method is

     *            called on a closed result set

     */

    boolean next() throws SQLException;

    /**

     * Releases this <code>ResultSet</code> object's database and

     * JDBC resources immediately instead of waiting for

     * this to happen when it is automatically closed.

     *

     * <P>The closing of a <code>ResultSet</code> object does <strong>not</strong> close the <code>Blob</code>,

     * <code>Clob</code> or <code>NClob</code> objects created by the <code>ResultSet</code>. <code>Blob</code>,

     * <code>Clob</code> or <code>NClob</code> objects remain valid for at least the duration of the

     * transaction in which they are creataed, unless their <code>free</code> method is invoked.

     *<p>

     * When a <code>ResultSet</code> is closed, any <code>ResultSetMetaData</code>

     * instances that were created by calling the  <code>getMetaData</code>

     * method remain accessible.

     *

     * <P><B>Note:</B> A <code>ResultSet</code> object

     * is automatically closed by the

     * <code>Statement</code> object that generated it when

     * that <code>Statement</code> object is closed,

     * re-executed, or is used to retrieve the next result from a

     * sequence of multiple results.

     *<p>

     * Calling the method <code>close</code> on a <code>ResultSet</code>

     * object that is already closed is a no-op.

     * <P>

     * <p>

     *

     * @exception SQLException if a database access error occurs

     */

    void close() throws SQLException;

    /**

     * Reports whether

     * the last column read had a value of SQL <code>NULL</code>.

     * Note that you must first call one of the getter methods

     * on a column to try to read its value and then call

     * the method <code>wasNull</code> to see if the value read was

     * SQL <code>NULL</code>.

     *

     * @return <code>true</code> if the last column value read was SQL

     *         <code>NULL</code> and <code>false</code> otherwise

     * @exception SQLException if a database access error occurs or this method is

     *            called on a closed result set

     */

    boolean wasNull() throws SQLException;

    // Methods for accessing results by column index

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>String</code> in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>null</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    String getString(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>boolean</code> in the Java programming language.

     *

     * <P>If the designated column has a datatype of CHAR or VARCHAR

     * and contains a "0" or has a datatype of BIT, TINYINT, SMALLINT, INTEGER or BIGINT

     * and contains  a 0, a value of <code>false</code> is returned.  If the designated column has a datatype

     * of CHAR or VARCHAR

     * and contains a "1" or has a datatype of BIT, TINYINT, SMALLINT, INTEGER or BIGINT

     * and contains  a 1, a value of <code>true</code> is returned.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>false</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    boolean getBoolean(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>byte</code> in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>0</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    byte getByte(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>short</code> in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>0</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    short getShort(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * an <code>int</code> in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>0</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    int getInt(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>long</code> in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>0</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    long getLong(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>float</code> in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>0</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    float getFloat(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>double</code> in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>0</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    double getDouble(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>java.sql.BigDecimal</code> in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @param scale the number of digits to the right of the decimal point

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>null</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

     * this method

     * @deprecated

     */

    BigDecimal getBigDecimal(int columnIndex, int scale) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>byte</code> array in the Java programming language.

     * 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 <code>NULL</code>, the

     * value returned is <code>null</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    byte[] getBytes(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>java.sql.Date</code> object in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>null</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    java.sql.Date getDate(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>java.sql.Time</code> object in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>null</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    java.sql.Time getTime(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>java.sql.Timestamp</code> object in the Java programming language.

     *

     * @param columnIndex the first column is 1, the second is 2, ...

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>null</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    java.sql.Timestamp getTimestamp(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a stream of ASCII characters. The value can then be read in chunks from the

     * stream. This method is particularly

     * suitable for retrieving large <char>LONGVARCHAR</char> 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 getter method implicitly closes the stream.  Also, a

     * stream may return <code>0</code> when the method

     * <code>InputStream.available</code>

     * is called 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 <code>NULL</code>, the

     * value returned is <code>null</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    java.io.InputStream getAsciiStream(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * as a stream of two-byte 3 characters. The first byte is

     * the high byte; the second byte is the low byte.

     *

     * The value can then be read in chunks from the

     * stream. This method is particularly

     * suitable for retrieving large <code>LONGVARCHAR</code>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 getter method implicitly closes the stream.

     * Also, a stream may return <code>0</code> when the method

     * <code>InputStream.available</code>

     * is called, 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 <code>NULL</code>, the value returned is

     *         <code>null</code>

     *

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

     * this method

     * @deprecated use <code>getCharacterStream</code> in place of

     *              <code>getUnicodeStream</code>

     */

    java.io.InputStream getUnicodeStream(int columnIndex) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as a  stream of

     * uninterpreted bytes. The value can then be read in chunks from the

     * stream. This method is particularly

     * suitable for retrieving large <code>LONGVARBINARY</code> 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 getter method implicitly closes the stream.  Also, a

     * stream may return <code>0</code> when the method

     * <code>InputStream.available</code>

     * is called 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 <code>NULL</code>, the value returned is

     *         <code>null</code>

     * @exception SQLException if the columnIndex is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    java.io.InputStream getBinaryStream(int columnIndex)

        throws SQLException;

    // Methods for accessing results by column label

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>String</code> in the Java programming language.

     *

     * @param columnLabel the label for the column specified with the SQL AS clause.  If the SQL AS clause was not specified, then the label is the name of the column

     * @return the column value; if the value is SQL <code>NULL</code>, the

     * value returned is <code>null</code>

     * @exception SQLException if the columnLabel is not valid;

     * if a database access error occurs or this method is

     *            called on a closed result set

     */

    String getString(String columnLabel) throws SQLException;

    /**

     * Retrieves the value of the designated column in the current row

     * of this <code>ResultSet</code> object as

     * a <code>boolean</code> in the Java programming language.