/*

* Copyright (c) 1996, 2013, Oracle and/or its affiliates. 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. Oracle designates this

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

* by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

* or visit www.oracle.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>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&trade; 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>ResultSetMetaData</code>

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

*

* @see Statement#executeQuery

* @see Statement#getResultSet

* @see ResultSetMetaData

*/

public interface ResultSet extends Wrapper, AutoCloseable {

/**

* Moves the cursor forward 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 created, 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.

*

*

* @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 Use {@code getBigDecimal(int columnIndex)}

* or {@code getBigDecimal(String columnLabel)}

*/

@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 <code>LONGVARCHAR</code> 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>

*/

@Deprecated

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.

*

* <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 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>false</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

*/

boolean getBoolean(String columnLabel) 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 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>0</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

*/

byte getByte(String columnLabel) 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 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>0</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

*/

short getShort(String columnLabel) 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 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>0</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

*/

int getInt(String columnLabel) 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 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>0</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

*/

long getLong(String columnLabel) 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 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>0</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

*/

float getFloat(String columnLabel) 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 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>0</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

*/

double getDouble(String columnLabel) throws SQLException;

/**

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

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

* a <code>java.math.BigDecimal</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

* @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 columnLabel 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 getBigDecimal(int columnIndex)}

* or {@code getBigDecimal(String columnLabel)}

*/

@Deprecated

BigDecimal getBigDecimal(String columnLabel, 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 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

*/

byte[] getBytes(String columnLabel) 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 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

*/

java.sql.Date getDate(String columnLabel) 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 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

*/

java.sql.Time getTime(String columnLabel) 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 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

*/

java.sql.Timestamp getTimestamp(String columnLabel) 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 <code>LONGVARCHAR</code> 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>available</code>

* is called whether there is data available or not.

*

* @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 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 columnLabel is not valid;

* if a database access error occurs or this method is

* called on a closed result set

*/

java.io.InputStream getAsciiStream(String columnLabel) throws SQLException;

/**

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

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

* Unicode 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 technology-enabled 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 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 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 columnLabel 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> instead

*/

@Deprecated

java.io.InputStream getUnicodeStream(String columnLabel) throws SQLException;

/**

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

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

* <code>byte</code>s.

* 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>available</code>

* is called whether there is data available or not.

*

* @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 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 result 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

*/

java.io.InputStream getBinaryStream(String columnLabel)

throws SQLException;

// Advanced features:

/**

* Retrieves the first warning reported by calls on this

* <code>ResultSet</code> object.

* Subsequent warnings on this <code>ResultSet</code> object

* will be chained to the <code>SQLWarning</code> object that

* this method returns.

*

* <P>The warning chain is automatically cleared each time a new

* row is read. This method may not be called on a <code>ResultSet</code>

* object that has been closed; doing so will cause an

* <code>SQLException</code> to be thrown.

* <P>

* <B>Note:</B> This warning chain only covers warnings caused

* by <code>ResultSet</code> methods. Any warning caused by

* <code>Statement</code> methods

* (such as reading OUT parameters) will be chained on the

* <code>Statement</code> object.

*

* @return the first <code>SQLWarning</code> object reported or

* <code>null</code> if there are none

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

* called on a closed result set

*/

SQLWarning getWarnings() throws SQLException;

/**

* Clears all warnings reported on this <code>ResultSet</code> object.

* After this method is called, the method <code>getWarnings</code>

* returns <code>null</code> until a new warning is

* reported for this <code>ResultSet</code> object.

*

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

* called on a closed result set

*/

void clearWarnings() throws SQLException;

/**

* Retrieves the name of the SQL cursor used by this <code>ResultSet</code>

* object.

*

* <P>In SQL, a result table is retrieved through a cursor that is

* named. The current row of a result set can be updated or deleted

* using a positioned update/delete statement that references the

* cursor name. To insure that the cursor has the proper isolation

* level to support update, the cursor's <code>SELECT</code> statement

* should be of the form <code>SELECT FOR UPDATE</code>. If

* <code>FOR UPDATE</code> is omitted, the positioned updates may fail.

*

* <P>The JDBC API supports this SQL feature by providing the name of the

* SQL cursor used by a <code>ResultSet</code> object.

* The current row of a <code>ResultSet</code> object

* is also the current row of this SQL cursor.

*

* @return the SQL name for this <code>ResultSet</code> object's cursor

* @exception SQLException 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

*/

String getCursorName() throws SQLException;

/**

* Retrieves the number, types and properties of

* this <code>ResultSet</code> object's columns.

*

* @return the description of this <code>ResultSet</code> object's columns

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

* called on a closed result set

*/

ResultSetMetaData getMetaData() throws SQLException;

/**

* <p>Gets the value of the designated column in the current row

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

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

*

* <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 for built-in types specified in the JDBC

* specification. If the value is an SQL <code>NULL</code>,

* the driver returns a Java <code>null</code>.

*

* <p>This method may also be used to read database-specific

* abstract data types.

*

* In the JDBC 2.0 API, the behavior of method

* <code>getObject</code> is extended to materialize

* data of SQL user-defined types.

* <p>

* If <code>Connection.getTypeMap</code> does not throw a

* <code>SQLFeatureNotSupportedException</code>,

* then when a column contains a structured or distinct value,

* the behavior of this method is as

* if it were a call to: <code>getObject(columnIndex,

* this.getStatement().getConnection().getTypeMap())</code>.

*

* If <code>Connection.getTypeMap</code> does throw a

* <code>SQLFeatureNotSupportedException</code>,

* then structured values are not supported, and distinct values

* are mapped to the default Java class as determined by the

* underlying SQL type of the DISTINCT type.

*

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

* @return a <code>java.lang.Object</code> holding the column value

* @exception SQLException if the columnIndex is not valid;

* if a database access error occurs or this method is

* called on a closed result set

*/

Object getObject(int columnIndex) throws SQLException;

/**

* <p>Gets the value of the designated column in the current row

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

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

*

* <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 for built-in types specified in the JDBC

* specification. If the value is an SQL <code>NULL</code>,

* the driver returns a Java <code>null</code>.

* <P>

* This method may also be used to read database-specific

* abstract data types.

* <P>

* In the JDBC 2.0 API, the behavior of the method

* <code>getObject</code> is extended to materialize

* data of SQL user-defined types. When a column contains

* a structured or distinct value, the behavior of this method is as

* if it were a call to: <code>getObject(columnIndex,

* this.getStatement().getConnection().getTypeMap())</code>.

*

* @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 a <code>java.lang.Object</code> holding the column value

* @exception SQLException if the columnLabel is not valid;

* if a database access error occurs or this method is

* called on a closed result set

*/

Object getObject(String columnLabel) throws SQLException;

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

/**

* Maps the given <code>ResultSet</code> column label to its

* <code>ResultSet</code> column index.

*

* @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 index of the given column name

* @exception SQLException if the <code>ResultSet</code> object

* does not contain a column labeled <code>columnLabel</code>, a database access error occurs

* or this method is called on a closed result set

*/

int findColumn(String columnLabel) throws SQLException;

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

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

// Getters and Setters

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

/**

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

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

* <code>java.io.Reader</code> object.

* @return a <code>java.io.Reader</code> object that contains the column

* value; if the value is SQL <code>NULL</code>, the value returned is

* <code>null</code> in the Java programming language.

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

* @exception SQLException if the columnIndex is not valid;

* if a database access error occurs or this method is

* called on a closed result set

* @since 1.2

*/

java.io.Reader getCharacterStream(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.io.Reader</code> object.

*

* @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 a <code>java.io.Reader</code> object that contains the column

* value; if the value is SQL <code>NULL</code>, the value returned is

* <code>null</code> in the Java programming language

* @exception SQLException if the columnLabel is not valid;

* if a database access error occurs or this method is

* called on a closed result set

* @since 1.2

*/

java.io.Reader getCharacterStream(String columnLabel) throws SQLException;

/**

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

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

* <code>java.math.BigDecimal</code> with full precision.

*

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

* @return the column value (full precision);

* if the value is SQL <code>NULL</code>, the value returned is

* <code>null</code> in the Java programming language.

* @exception SQLException if the columnIndex is not valid;