/* * Copyright (c) 1996, 2011, 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> * <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>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 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 <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> */ 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>Lines 1–500 of 4139. Load more
/* * Copyright (c) 1996, 2011, 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> * <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>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 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 <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> */ 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>