/* ResultSet.java -- A SQL statement result set. Copyright (C) 1999 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath 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 for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. As a special exception, if you link this library with other files to produce an executable, this library does not by itself cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU General Public License. */ package java.sql; import java.io.InputStream; import java.io.Reader; import java.math.BigDecimal; /** * This interface provides access to the data set returned by a SQL * statement. An instance of this interface is returned by the various * execution methods in the Statement * This class models a cursor, which can be stepped through one row at a * time. Methods are provided for accessing columns by column name or by * index. *

* Note that a result set is invalidated if the statement that returned * it is closed. * * @author Aaron M. Renn (arenn@urbanophile.com) */ public interface ResultSet { /** * This method advances to the next row in the result set. Any streams * open on the current row are closed automatically. * * @return true if the next row exists, false * otherwise. * * @exception SQLException If an error occurs. */ public abstract boolean next() throws SQLException; /*************************************************************************/ /** * This method closes the result set and frees any associated resources. * * @exception SQLException If an error occurs. */ public abstract void close() throws SQLException; /*************************************************************************/ /** * This method tests whether the value of the last column that was fetched * was actually a SQL NULL value. * * @return true if the last column fetched was a NULL, * false otherwise. * * @exception SQLException If an error occurs. */ public abstract boolean wasNull() throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * String. * * @param index The index of the column to return. * * @return The column value as a String. * * @exception SQLException If an error occurs. */ public abstract String getString(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * Object. * * @param index The index of the column to return. * * @return The column value as an Object. * * @exception SQLException If an error occurs. */ public abstract Object getObject(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * boolean. * * @param index The index of the column to return. * * @return The column value as a boolean. * * @exception SQLException If an error occurs. */ public abstract boolean getBoolean(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * byte. * * @param index The index of the column to return. * * @return The column value as a byte. * * @exception SQLException If an error occurs. */ public abstract byte getByte(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * short. * * @param index The index of the column to return. * * @return The column value as a short. * * @exception SQLException If an error occurs. */ public abstract short getShort(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * int. * * @param index The index of the column to return. * * @return The column value as a int. * * @exception SQLException If an error occurs. */ public abstract int getInt(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * long. * * @param index The index of the column to return. * * @return The column value as a long. * * @exception SQLException If an error occurs. */ public abstract long getLong(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * float. * * @param index The index of the column to return. * * @return The column value as a float. * * @exception SQLException If an error occurs. */ public abstract float getFloat(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * double. * * @param index The index of the column to return. * * @return The column value as a double. * * @exception SQLException If an error occurs. */ public abstract double getDouble(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * BigDecimal. * * @param index The index of the column to return. * @param scale The number of digits to the right of the decimal to return. * * @return The column value as a BigDecimal. * * @exception SQLException If an error occurs. */ public abstract BigDecimal getBigDecimal(int index, int scale) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * byte array. * * @param index The index of the column to return. * * @return The column value as a byte array * * @exception SQLException If an error occurs. */ public abstract byte[] getBytes(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * java.sql.Date. * * @param index The index of the column to return. * * @return The column value as a java.sql.Date. * * @exception SQLException If an error occurs. */ public abstract java.sql.Date getDate(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * java.sql.Time. * * @param index The index of the column to return. * * @return The column value as a java.sql.Time. * * @exception SQLException If an error occurs. */ public abstract java.sql.Time getTime(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * java.sql.Timestamp. * * @param index The index of the column to return. * * @return The column value as a java.sql.Timestamp. * * @exception SQLException If an error occurs. */ public abstract java.sql.Timestamp getTimestamp(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as an ASCII * stream. Note that all the data from this stream must be read before * fetching the value of any other column. Please also be aware that * calling next() or close() on this result set * will close this stream as well. * * @param index The index of the column to return. * * @return The column value as an ASCII InputStream. * * @exception SQLException If an error occurs. */ public abstract InputStream getAsciiStream(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Unicode UTF-8 * stream. Note that all the data from this stream must be read before * fetching the value of any other column. Please also be aware that * calling next() or close() on this result set * will close this stream as well. * * @param index The index of the column to return. * * @return The column value as a Unicode UTF-8 InputStream. * * @exception SQLException If an error occurs. */ public abstract InputStream getUnicodeStream(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a raw byte * stream. Note that all the data from this stream must be read before * fetching the value of any other column. Please also be aware that * calling next() or close() on this result set * will close this stream as well. * * @param index The index of the column to return. * * @return The column value as a raw byte InputStream. * * @exception SQLException If an error occurs. */ public abstract InputStream getBinaryStream(int index) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * String. * * @param column The name of the column to return. * * @return The column value as a String. * * @exception SQLException If an error occurs. */ public abstract String getString(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * Object. * * @param column The name of the column to return. * * @return The column value as an Object. * * @exception SQLException If an error occurs. */ public abstract Object getObject(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * boolean. * * @param column The name of the column to return. * * @return The column value as a boolean. * * @exception SQLException If an error occurs. */ public abstract boolean getBoolean(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * byte. * * @param column The name of the column to return. * * @return The column value as a byte. * * @exception SQLException If an error occurs. */ public abstract byte getByte(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * short. * * @param column The name of the column to return. * * @return The column value as a short. * * @exception SQLException If an error occurs. */ public abstract short getShort(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * int. * * @param column The name of the column to return. * * @return The column value as a int. * * @exception SQLException If an error occurs. */ public abstract int getInt(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * long. * * @param column The name of the column to return. * * @return The column value as a long. * * @exception SQLException If an error occurs. */ public abstract long getLong(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * float. * * @param column The name of the column to return. * * @return The column value as a float. * * @exception SQLException If an error occurs. */ public abstract float getFloat(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * double. * * @param column The name of the column to return. * * @return The column value as a double. * * @exception SQLException If an error occurs. */ public abstract double getDouble(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * BigDecimal. * * @param column The name of the column to return. * @param scale The number of digits to the right of the decimal to return. * * @return The column value as a BigDecimal. * * @exception SQLException If an error occurs. */ public abstract BigDecimal getBigDecimal(String column, int scale) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * byte array. * * @param column The name of the column to return. * * @return The column value as a byte array * * @exception SQLException If an error occurs. */ public abstract byte[] getBytes(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * java.sql.Date. * * @param column The name of the column to return. * * @return The column value as a java.sql.Date. * * @exception SQLException If an error occurs. */ public abstract java.sql.Date getDate(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * java.sql.Time. * * @param column The name of the column to return. * * @return The column value as a java.sql.Time. * * @exception SQLException If an error occurs. */ public abstract java.sql.Time getTime(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Java * java.sql.Timestamp. * * @param column The name of the column to return. * * @return The column value as a java.sql.Timestamp. * * @exception SQLException If an error occurs. */ public abstract java.sql.Timestamp getTimestamp(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as an ASCII * stream. Note that all the data from this stream must be read before * fetching the value of any other column. Please also be aware that * calling next() or close() on this result set * will close this stream as well. * * @param column The name of the column to return. * * @return The column value as an ASCII InputStream. * * @exception SQLException If an error occurs. */ public abstract InputStream getAsciiStream(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a Unicode UTF-8 * stream. Note that all the data from this stream must be read before * fetching the value of any other column. Please also be aware that * calling next() or close() on this result set * will close this stream as well. * * @param column The name of the column to return. * * @return The column value as a Unicode UTF-8 InputStream. * * @exception SQLException If an error occurs. */ public abstract InputStream getUnicodeStream(String column) throws SQLException; /*************************************************************************/ /** * This method returns the value of the specified column as a raw byte * stream. Note that all the data from this stream must be read before * fetching the value of any other column. Please also be aware that * calling next() or close() on this result set * will close this stream as well. * * @param column The name of the column to return. * * @return The column value as a raw byte InputStream. * * @exception SQLException If an error occurs. */ public abstract InputStream getBinaryStream(String column) throws SQLException; /*************************************************************************/ /** * This method returns the first SQL warning associated with this result * set. Any additional warnings will be chained to this one. * * @return The first SQLWarning for this result set, or null if * there are no warnings. * * @exception SQLException If an error occurs. */ public abstract SQLWarning getWarnings() throws SQLException; /*************************************************************************/ /** * This method clears all warnings associated with this result set. * * @exception SQLException If an error occurs. */ public abstract void clearWarnings() throws SQLException; /*************************************************************************/ /** * This method returns the name of the database cursor used by this * result set. * * @return The name of the database cursor used by this result set. * * @exception SQLException If an error occurs. */ public abstract String getCursorName() throws SQLException; /*************************************************************************/ /** * This method returns data about the columns returned as part of the * result set as a ResultSetMetaData instance. * * @return The ResultSetMetaData instance for this result set. * * @exception SQLException If an error occurs. */ public abstract ResultSetMetaData getMetaData() throws SQLException; /*************************************************************************/ /** * This method returns the column index of the specified named column. * * @param column The name of the column. * * @return The index of the column. * * @exception SQLException If an error occurs. */ public abstract int findColumn(String column) throws SQLException; } // interface ResultSet