Java > Open Source Codes > java > sql > ResultSet


1 /*
2  * @(#)ResultSet.java 1.49 04/06/28
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.sql;
9
10 import java.math.BigDecimal ;
11 import java.util.Calendar ;
12
13 /**
14  * A table of data representing a database result set, which
15  * is usually generated by executing a statement that queries the database.
16  *
17  * <P>A <code>ResultSet</code> object maintains a cursor pointing
18  * to its current row of data. Initially the cursor is positioned
19  * before the first row. The <code>next</code> method moves the
20  * cursor to the next row, and because it returns <code>false</code>
21  * when there are no more rows in the <code>ResultSet</code> object,
22  * it can be used in a <code>while</code> loop to iterate through
23  * the result set.
24  * <P>
25  * A default <code>ResultSet</code> object is not updatable and
26  * has a cursor that moves forward only. Thus, you can
27  * iterate through it only once and only from the first row to the
28  * last row. It is possible to
29  * produce <code>ResultSet</code> objects that are scrollable and/or
30  * updatable. The following code fragment, in which <code>con</code>
31  * is a valid <code>Connection</code> object, illustrates how to make
32  * a result set that is scrollable and insensitive to updates by others, and
33  * that is updatable. See <code>ResultSet</code> fields for other
34  * options.
35  * <PRE>
36  *
37  * Statement stmt = con.createStatement(
38  * ResultSet.TYPE_SCROLL_INSENSITIVE,
39  * ResultSet.CONCUR_UPDATABLE);
40  * ResultSet rs = stmt.executeQuery("SELECT a, b FROM TABLE2");
41  * // rs will be scrollable, will not show changes made by others,
42  * // and will be updatable
43  *
44  * </PRE>
45  * The <code>ResultSet</code> interface provides
46  * <i>getter</i> methods (<code>getBoolean</code>, <code>getLong</code>, and so on)
47  * for retrieving column values from the current row.
48  * Values can be retrieved using either the index number of the
49  * column or the name of the column. In general, using the
50  * column index will be more efficient. Columns are numbered from 1.
51  * For maximum portability, result set columns within each row should be
52  * read in left-to-right order, and each column should be read only once.
53  *
54  * <P>For the getter methods, a JDBC driver attempts
55  * to convert the underlying data to the Java type specified in the
56  * getter method and returns a suitable Java value. The JDBC specification
57  * has a table showing the allowable mappings from SQL types to Java types
58  * that can be used by the <code>ResultSet</code> getter methods.
59  * <P>
60  * <P>Column names used as input to getter methods are case
61  * insensitive. When a getter method is called with
62  * a column name and several columns have the same name,
63  * the value of the first matching column will be returned.
64  * The column name option is
65  * designed to be used when column names are used in the SQL
66  * query that generated the result set.
67  * For columns that are NOT explicitly named in the query, it
68  * is best to use column numbers. If column names are used, there is
69  * no way for the programmer to guarantee that they actually refer to
70  * the intended columns.
71  * <P>
72  * A set of updater methods were added to this interface
73  * in the JDBC 2.0 API (JDK 1.2).
74  * The comments regarding parameters
75  * to the getter methods also apply to parameters to the
76  * updater methods.
77  *<P>
78  * The updater methods may be used in two ways:
79  * <ol>
80  * <LI>to update a column value in the current row. In a scrollable
81  * <code>ResultSet</code> object, the cursor can be moved backwards
82  * and forwards, to an absolute position, or to a position
83  * relative to the current row.
84  * The following code fragment updates the <code>NAME</code> column
85  * in the fifth row of the <code>ResultSet</code> object
86  * <code>rs</code> and then uses the method <code>updateRow</code>
87  * to update the data source table from which <code>rs</code> was derived.
88  * <PRE>
89  *
90  * rs.absolute(5); // moves the cursor to the fifth row of rs
91  * rs.updateString("NAME", "AINSWORTH"); // updates the
92  * // <code>NAME</code> column of row 5 to be <code>AINSWORTH</code>
93  * rs.updateRow(); // updates the row in the data source
94  *
95  * </PRE>
96  * <LI>to insert column values into the insert row. An updatable
97  * <code>ResultSet</code> object has a special row associated with
98  * it that serves as a staging area for building a row to be inserted.
99  * The following code fragment moves the cursor to the insert row, builds
100  * a three-column row, and inserts it into <code>rs</code> and into
101  * the data source table using the method <code>insertRow</code>.
102  * <PRE>
103  *
104  * rs.moveToInsertRow(); // moves cursor to the insert row
105  * rs.updateString(1, "AINSWORTH"); // updates the
106  * // first column of the insert row to be <code>AINSWORTH</code>
107  * rs.updateInt(2,35); // updates the second column to be <code>35</code>
108  * rs.updateBoolean(3, true); // updates the third column to <code>true</code>
109  * rs.insertRow();
110  * rs.moveToCurrentRow();
111  *
112  * </PRE>
113  * </ol>
114  * <P>A <code>ResultSet</code> object is automatically closed when the
115  * <code>Statement</code> object that
116  * generated it is closed, re-executed, or used
117  * to retrieve the next result from a sequence of multiple results.
118  *
119  * <P>The number, types and properties of a <code>ResultSet</code>
120  * object's columns are provided by the <code>ResulSetMetaData</code>
121  * object returned by the <code>ResultSet.getMetaData</code> method.
122  *
123  * @see Statement#executeQuery
124  * @see Statement#getResultSet
125  * @see ResultSetMetaData
126  */
127
128 public interface ResultSet {
129
130     /**
131      * Moves the cursor down one row from its current position.
132      * A <code>ResultSet</code> cursor is initially positioned
133      * before the first row; the first call to the method
134      * <code>next</code> makes the first row the current row; the
135      * second call makes the second row the current row, and so on.
136      *
137      * <P>If an input stream is open for the current row, a call
138      * to the method <code>next</code> will
139      * implicitly close it. A <code>ResultSet</code> object's
140      * warning chain is cleared when a new row is read.
141      *
142      * @return <code>true</code> if the new current row is valid;
143      * <code>false</code> if there are no more rows
144      * @exception SQLException if a database access error occurs
145      */
146     boolean next() throws SQLException ;
147
148
149     /**
150      * Releases this <code>ResultSet</code> object's database and
151      * JDBC resources immediately instead of waiting for
152      * this to happen when it is automatically closed.
153      *
154      * <P><B>Note:</B> A <code>ResultSet</code> object
155      * is automatically closed by the
156      * <code>Statement</code> object that generated it when
157      * that <code>Statement</code> object is closed,
158      * re-executed, or is used to retrieve the next result from a
159      * sequence of multiple results. A <code>ResultSet</code> object
160      * is also automatically closed when it is garbage collected.
161      *
162      * @exception SQLException if a database access error occurs
163      */
164     void close() throws SQLException ;
165
166     /**
167      * Reports whether
168      * the last column read had a value of SQL <code>NULL</code>.
169      * Note that you must first call one of the getter methods
170      * on a column to try to read its value and then call
171      * the method <code>wasNull</code> to see if the value read was
172      * SQL <code>NULL</code>.
173      *
174      * @return <code>true</code> if the last column value read was SQL
175      * <code>NULL</code> and <code>false</code> otherwise
176      * @exception SQLException if a database access error occurs
177      */
178     boolean wasNull() throws SQLException ;
179     
180     //======================================================================
181 // Methods for accessing results by column index
182 //======================================================================
183
184     /**
185      * Retrieves the value of the designated column in the current row
186      * of this <code>ResultSet</code> object as
187      * a <code>String</code> in the Java programming language.
188      *
189      * @param columnIndex the first column is 1, the second is 2, ...
190      * @return the column value; if the value is SQL <code>NULL</code>, the
191      * value returned is <code>null</code>
192      * @exception SQLException if a database access error occurs
193      */
194     String getString(int columnIndex) throws SQLException ;
195
196     /**
197      * Retrieves the value of the designated column in the current row
198      * of this <code>ResultSet</code> object as
199      * a <code>boolean</code> in the Java programming language.
200      *
201      * @param columnIndex the first column is 1, the second is 2, ...
202      * @return the column value; if the value is SQL <code>NULL</code>, the
203      * value returned is <code>false</code>
204      * @exception SQLException if a database access error occurs
205      */
206     boolean getBoolean(int columnIndex) throws SQLException ;
207
208     /**
209      * Retrieves the value of the designated column in the current row
210      * of this <code>ResultSet</code> object as
211      * a <code>byte</code> in the Java programming language.
212      *
213      * @param columnIndex the first column is 1, the second is 2, ...
214      * @return the column value; if the value is SQL <code>NULL</code>, the
215      * value returned is <code>0</code>
216      * @exception SQLException if a database access error occurs
217      */
218     byte getByte(int columnIndex) throws SQLException ;
219
220     /**
221      * Retrieves the value of the designated column in the current row
222      * of this <code>ResultSet</code> object as
223      * a <code>short</code> in the Java programming language.
224      *
225      * @param columnIndex the first column is 1, the second is 2, ...
226      * @return the column value; if the value is SQL <code>NULL</code>, the
227      * value returned is <code>0</code>
228      * @exception SQLException if a database access error occurs
229      */
230     short getShort(int columnIndex) throws SQLException ;
231
232     /**
233      * Retrieves the value of the designated column in the current row
234      * of this <code>ResultSet</code> object as
235      * an <code>int</code> in the Java programming language.
236      *
237      * @param columnIndex the first column is 1, the second is 2, ...
238      * @return the column value; if the value is SQL <code>NULL</code>, the
239      * value returned is <code>0</code>
240      * @exception SQLException if a database access error occurs
241      */
242     int getInt(int columnIndex) throws SQLException ;
243
244     /**
245      * Retrieves the value of the designated column in the current row
246      * of this <code>ResultSet</code> object as
247      * a <code>long</code> in the Java programming language.
248      *
249      * @param columnIndex the first column is 1, the second is 2, ...
250      * @return the column value; if the value is SQL <code>NULL</code>, the
251      * value returned is <code>0</code>
252      * @exception SQLException if a database access error occurs
253      */
254     long getLong(int columnIndex) throws SQLException ;
255
256     /**
257      * Retrieves the value of the designated column in the current row
258      * of this <code>ResultSet</code> object as
259      * a <code>float</code> in the Java programming language.
260      *
261      * @param columnIndex the first column is 1, the second is 2, ...
262      * @return the column value; if the value is SQL <code>NULL</code>, the
263      * value returned is <code>0</code>
264      * @exception SQLException if a database access error occurs
265      */
266     float getFloat(int columnIndex) throws SQLException ;
267
268     /**
269      * Retrieves the value of the designated column in the current row
270      * of this <code>ResultSet</code> object as
271      * a <code>double</code> in the Java programming language.
272      *
273      * @param columnIndex the first column is 1, the second is 2, ...
274      * @return the column value; if the value is SQL <code>NULL</code>, the
275      * value returned is <code>0</code>
276      * @exception SQLException if a database access error occurs
277      */
278     double getDouble(int columnIndex) throws SQLException ;
279
280     /**
281      * Retrieves the value of the designated column in the current row
282      * of this <code>ResultSet</code> object as
283      * a <code>java.sql.BigDecimal</code> in the Java programming language.
284      *
285      * @param columnIndex the first column is 1, the second is 2, ...
286      * @param scale the number of digits to the right of the decimal point
287      * @return the column value; if the value is SQL <code>NULL</code>, the
288      * value returned is <code>null</code>
289      * @exception SQLException if a database access error occurs
290      * @deprecated
291      */
292     @Deprecated
293     BigDecimal getBigDecimal(int columnIndex, int scale) throws SQLException ;
294
295     /**
296      * Retrieves the value of the designated column in the current row
297      * of this <code>ResultSet</code> object as
298      * a <code>byte</code> array in the Java programming language.
299      * The bytes represent the raw values returned by the driver.
300      *
301      * @param columnIndex the first column is 1, the second is 2, ...
302      * @return the column value; if the value is SQL <code>NULL</code>, the
303      * value returned is <code>null</code>
304      * @exception SQLException if a database access error occurs
305      */
306     byte[] getBytes(int columnIndex) throws SQLException ;
307
308     /**
309      * Retrieves the value of the designated column in the current row
310      * of this <code>ResultSet</code> object as
311      * a <code>java.sql.Date</code> object in the Java programming language.
312      *
313      * @param columnIndex the first column is 1, the second is 2, ...
314      * @return the column value; if the value is SQL <code>NULL</code>, the
315      * value returned is <code>null</code>
316      * @exception SQLException if a database access error occurs
317      */
318     java.sql.Date getDate(int columnIndex) throws SQLException ;
319
320     /**
321      * Retrieves the value of the designated column in the current row
322      * of this <code>ResultSet</code> object as
323      * a <code>java.sql.Time</code> object in the Java programming language.
324      *
325      * @param columnIndex the first column is 1, the second is 2, ...
326      * @return the column value; if the value is SQL <code>NULL</code>, the
327      * value returned is <code>null</code>
328      * @exception SQLException if a database access error occurs
329      */
330     java.sql.Time getTime(int columnIndex) throws SQLException ;
331
332     /**
333      * Retrieves the value of the designated column in the current row
334      * of this <code>ResultSet</code> object as
335      * a <code>java.sql.Timestamp</code> object in the Java programming language.
336      *
337      * @param columnIndex the first column is 1, the second is 2, ...
338      * @return the column value; if the value is SQL <code>NULL</code>, the
339      * value returned is <code>null</code>
340      * @exception SQLException if a database access error occurs
341      */
342     java.sql.Timestamp getTimestamp(int columnIndex) throws SQLException ;
343
344     /**
345      * Retrieves the value of the designated column in the current row
346      * of this <code>ResultSet</code> object as
347      * a stream of ASCII characters. The value can then be read in chunks from the
348      * stream. This method is particularly
349      * suitable for retrieving large <char>LONGVARCHAR</char> values.
350      * The JDBC driver will
351      * do any necessary conversion from the database format into ASCII.
352      *
353      * <P><B>Note:</B> All the data in the returned stream must be
354      * read prior to getting the value of any other column. The next
355      * call to a getter method implicitly closes the stream. Also, a
356      * stream may return <code>0</code> when the method
357      * <code>InputStream.available</code>
358      * is called whether there is data available or not.
359      *
360      * @param columnIndex the first column is 1, the second is 2, ...
361      * @return a Java input stream that delivers the database column value
362      * as a stream of one-byte ASCII characters;
363      * if the value is SQL <code>NULL</code>, the
364      * value returned is <code>null</code>
365      * @exception SQLException if a database access error occurs
366      */
367     java.io.InputStream getAsciiStream(int columnIndex) throws SQLException ;
368
369     /**
370      * Retrieves the value of the designated column in the current row
371      * of this <code>ResultSet</code> object as
372      * as a stream of two-byte Unicode characters. The first byte is
373      * the high byte; the second byte is the low byte.
374      *
375      * The value can then be read in chunks from the
376      * stream. This method is particularly
377      * suitable for retrieving large <code>LONGVARCHAR</code>values. The
378      * JDBC driver will do any necessary conversion from the database
379      * format into Unicode.
380      *
381      * <P><B>Note:</B> All the data in the returned stream must be
382      * read prior to getting the value of any other column. The next
383      * call to a getter method implicitly closes the stream.
384      * Also, a stream may return <code>0</code> when the method
385      * <code>InputStream.available</code>
386      * is called, whether there is data available or not.
387      *
388      * @param columnIndex the first column is 1, the second is 2, ...
389      * @return a Java input stream that delivers the database column value
390      * as a stream of two-byte Unicode characters;
391      * if the value is SQL <code>NULL</code>, the value returned is
392      * <code>null</code>
393      *
394      * @exception SQLException if a database access error occurs
395      * @deprecated use <code>getCharacterStream</code> in place of
396      * <code>getUnicodeStream</code>
397      */
398     @Deprecated
399     java.io.InputStream getUnicodeStream(int columnIndex) throws SQLException ;
400
401     /**
402      * Retrieves the value of the designated column in the current row
403      * of this <code>ResultSet</code> object as a binary stream of
404      * uninterpreted bytes. The value can then be read in chunks from the
405      * stream. This method is particularly
406      * suitable for retrieving large <code>LONGVARBINARY</code> values.
407      *
408      * <P><B>Note:</B> All the data in the returned stream must be
409      * read prior to getting the value of any other column. The next
410      * call to a getter method implicitly closes the stream. Also, a
411      * stream may return <code>0</code> when the method
412      * <code>InputStream.available</code>
413      * is called whether there is data available or not.
414      *
415      * @param columnIndex the first column is 1, the second is 2, ...
416      * @return a Java input stream that delivers the database column value
417      * as a stream of uninterpreted bytes;
418      * if the value is SQL <code>NULL</code>, the value returned is
419      * <code>null</code>
420      * @exception SQLException if a database access error occurs
421      */
422     java.io.InputStream getBinaryStream(int columnIndex)
423         throws SQLException ;
424
425
426     //======================================================================
427 // Methods for accessing results by column name
428 //======================================================================
429
430     /**
431      * Retrieves the value of the designated column in the current row
432      * of this <code>ResultSet</code> object as
433      * a <code>String</code> in the Java programming language.
434      *
435      * @param columnName the SQL name of the column
436      * @return the column value; if the value is SQL <code>NULL</code>, the
437      * value returned is <code>null</code>
438      * @exception SQLException if a database access error occurs
439      */
440     String getString(String columnName) throws SQLException ;
441
442     /**
443      * Retrieves the value of the designated column in the current row
444      * of this <code>ResultSet</code> object as
445      * a <code>boolean</code> in the Java programming language.
446      *
447      * @param columnName the SQL name of the column
448      * @return the column value; if the value is SQL <code>NULL</code>, the
449      * value returned is <code>false</code>
450      * @exception SQLException if a database access error occurs
451      */
452     boolean getBoolean(String columnName) throws SQLException ;
453
454     /**
455      * Retrieves the value of the designated column in the current row
456      * of this <code>ResultSet</code> object as
457      * a <code>byte</code> in the Java programming language.
458      *
459      * @param columnName the SQL name of the column
460      * @return the column value; if the value is SQL <code>NULL</code>, the
461      * value returned is <code>0</code>
462      * @exception SQLException if a database access error occurs
463      */
464     byte getByte(String columnName) throws SQLException ;
465
466     /**
467      * Retrieves the value of the designated column in the current row
468      * of this <code>ResultSet</code> object as
469      * a <code>short</code> in the Java programming language.
470      *
471      * @param columnName the SQL name of the column
472      * @return the column value; if the value is SQL <code>NULL</code>, the
473      * value returned is <code>0</code>
474      * @exception SQLException if a database access error occurs
475      */
476     short getShort(String columnName) throws SQLException ;
477
478     /**
479      * Retrieves the value of the designated column in the current row
480      * of this <code>ResultSet</code> object as
481      * an <code>int</code> in the Java programming language.
482      *
483      * @param columnName the SQL name of the column
484      * @return the column value; if the value is SQL <code>NULL</code>, the
485      * value returned is <code>0</code>
486      * @exception SQLException if a database access error occurs
487      */
488     int getInt(String columnName) throws SQLException ;
489
490     /**
491      * Retrieves the value of the designated column in the current row
492      * of this <code>ResultSet</code> object as
493      * a <code>long</code> in the Java programming language.
494      *
495      * @param columnName the SQL name of the column
496      * @return the column value; if the value is SQL <code>NULL</code>, the
497      * value returned is <code>0</code>
498      * @exception SQLException if a database access error occurs
499      */
500     long getLong(String columnName) throws SQLException ;
501
502     /**
503      * Retrieves the value of the designated column in the current row
504      * of this <code>ResultSet</code> object as
505      * a <code>float</code> in the Java programming language.
506      *
507      * @param columnName the SQL name of the column
508      * @return the column value; if the value is SQL <code>NULL</code>, the
509      * value returned is <code>0</code>
510      * @exception SQLException if a database access error occurs
511      */
512     float getFloat(String columnName) throws SQLException ;
513
514     /**
515      * Retrieves the value of the designated column in the current row
516      * of this <code>ResultSet</code> object as
517      * a <code>double</code> in the Java programming language.
518      *
519      * @param columnName the SQL name of the column
520      * @return the column value; if the value is SQL <code>NULL</code>, the
521      * value returned is <code>0</code>
522      * @exception SQLException if a database access error occurs
523      */
524     double getDouble(String columnName) throws SQLException ;
525
526     /**
527      * Retrieves the value of the designated column in the current row
528      * of this <code>ResultSet</code> object as
529      * a <code>java.math.BigDecimal</code> in the Java programming language.
530      *
531      * @param columnName the SQL name of the column
532      * @param scale the number of digits to the right of the decimal point
533      * @return the column value; if the value is SQL <code>NULL</code>, the
534      * value returned is <code>null</code>
535      * @exception SQLException if a database access error occurs
536      * @deprecated
537      */
538     @Deprecated
539     BigDecimal getBigDecimal(String columnName, int scale) throws SQLException ;
540
541     /**
542      * Retrieves the value of the designated column in the current row
543      * of this <code>ResultSet</code> object as
544      * a <code>byte</code> array in the Java programming language.
545      * The bytes represent the raw values returned by the driver.
546      *
547      * @param columnName the SQL name of the column
548      * @return the column value; if the value is SQL <code>NULL</code>, the
549      * value returned is <code>null</code>
550      * @exception SQLException if a database access error occurs
551      */
552     byte[] getBytes(String columnName) throws SQLException ;
553
554     /**
555      * Retrieves the value of the designated column in the current row
556      * of this <code>ResultSet</code> object as
557      * a <code>java.sql.Date</code> object in the Java programming language.
558      *
559      * @param columnName the SQL name of the column
560      * @return the column value; if the value is SQL <code>NULL</code>, the
561      * value returned is <code>null</code>
562      * @exception SQLException if a database access error occurs
563      */
564     java.sql.Date getDate(String columnName) throws SQLException ;
565
566     /**
567      * Retrieves the value of the designated column in the current row
568      * of this <code>ResultSet</code> object as
569      * a <code>java.sql.Time</code> object in the Java programming language.
570      *
571      * @param columnName the SQL name of the column
572      * @return the column value;
573      * if the value is SQL <code>NULL</code>,
574      * the value returned is <code>null</code>
575      * @exception SQLException if a database access error occurs
576      */
577     java.sql.Time getTime(String columnName) throws SQLException ;
578
579     /**
580      * Retrieves the value of the designated column in the current row
581      * of this <code>ResultSet</code> object as
582      * a <code>java.sql.Timestamp</code> object.
583      *
584      * @param columnName the SQL name of the column
585      * @return the column value; if the value is SQL <code>NULL</code>, the
586      * value returned is <code>null</code>
587      * @exception SQLException if a database access error occurs
588      */
589     java.sql.Timestamp getTimestamp(String columnName) throws SQLException ;
590
591     /**
592      * Retrieves the value of the designated column in the current row
593      * of this <code>ResultSet</code> object as a stream of
594      * ASCII characters. The value can then be read in chunks from the
595      * stream. This method is particularly
596      * suitable for retrieving large <code>LONGVARCHAR</code> values.
597      * The JDBC driver will
598      * do any necessary conversion from the database format into ASCII.
599      *
600      * <P><B>Note:</B> All the data in the returned stream must be
601      * read prior to getting the value of any other column. The next
602      * call to a getter method implicitly closes the stream. Also, a
603      * stream may return <code>0</code> when the method <code>available</code>
604      * is called whether there is data available or not.
605      *
606      * @param columnName the SQL name of the column
607      * @return a Java input stream that delivers the database column value
608      * as a stream of one-byte ASCII characters.
609      * If the value is SQL <code>NULL</code>,
610      * the value returned is <code>null</code>.
611      * @exception SQLException if a database access error occurs
612      */
613     java.io.InputStream getAsciiStream(String columnName) throws SQLException ;
614
615     /**
616      * Retrieves the value of the designated column in the current row
617      * of this <code>ResultSet</code> object as a stream of two-byte
618      * Unicode characters. The first byte is the high byte; the second
619      * byte is the low byte.
620      *
621      * The value can then be read in chunks from the
622      * stream. This method is particularly
623      * suitable for retrieving large <code>LONGVARCHAR</code> values.
624      * The JDBC technology-enabled driver will
625      * do any necessary conversion from the database format into Unicode.
626      *
627      * <P><B>Note:</B> All the data in the returned stream must be
628      * read prior to getting the value of any other column. The next
629      * call to a getter method implicitly closes the stream.
630      * Also, a stream may return <code>0</code> when the method
631      * <code>InputStream.available</code> is called, whether there
632      * is data available or not.
633      *
634      * @param columnName the SQL name of the column
635      * @return a Java input stream that delivers the database column value
636      * as a stream of two-byte Unicode characters.
637      * If the value is SQL <code>NULL</code>, the value returned
638      * is <code>null</code>.
639      * @exception SQLException if a database access error occurs
640      * @deprecated use <code>getCharacterStream</code> instead
641      */
642     @Deprecated
643     java.io.InputStream getUnicodeStream(String columnName) throws SQLException ;
644
645     /**
646      * Retrieves the value of the designated column in the current row
647      * of this <code>ResultSet</code> object as a stream of uninterpreted
648      * <code>byte</code>s.
649      * The value can then be read in chunks from the
650      * stream. This method is particularly
651      * suitable for retrieving large <code>LONGVARBINARY</code>
652      * values.
653      *
654      * <P><B>Note:</B> All the data in the returned stream must be
655      * read prior to getting the value of any other column. The next
656      * call to a getter method implicitly closes the stream. Also, a
657      * stream may return <code>0</code> when the method <code>available</code>
658      * is called whether there is data available or not.
659      *
660      * @param columnName the SQL name of the column
661      * @return a Java input stream that delivers the database column value
662      * as a stream of uninterpreted bytes;
663      * if the value is SQL <code>NULL</code>, the result is <code>null</code>
664      * @exception SQLException if a database access error occurs
665      */
666     java.io.InputStream getBinaryStream(String columnName)
667         throws SQLException ;
668
669
670     //=====================================================================
671 // Advanced features:
672 //=====================================================================
673
674     /**
675      * Retrieves the first warning reported by calls on this
676      * <code>ResultSet</code> object.
677      * Subsequent warnings on this <code>ResultSet</code> object
678      * will be chained to the <code>SQLWarning</code> object that
679      * this method returns.
680      *
681      * <P>The warning chain is automatically cleared each time a new
682      * row is read. This method may not be called on a <code>ResultSet</code>
683      * object that has been closed; doing so will cause an
684      * <code>SQLException</code> to be thrown.
685      * <P>
686      * <B>Note:</B> This warning chain only covers warnings caused
687      * by <code>ResultSet</code> methods. Any warning caused by
688      * <code>Statement</code> methods
689      * (such as reading OUT parameters) will be chained on the
690      * <code>Statement</code> object.
691      *
692      * @return the first <code>SQLWarning</code> object reported or
693      * <code>null</code> if there are none
694      * @exception SQLException if a database access error occurs or this method is
695      * called on a closed result set
696      */
697     SQLWarning getWarnings() throws SQLException ;
698
699     /**
700      * Clears all warnings reported on this <code>ResultSet</code> object.
701      * After this method is called, the method <code>getWarnings</code>
702      * returns <code>null</code> until a new warning is
703      * reported for this <code>ResultSet</code> object.
704      *
705      * @exception SQLException if a database access error occurs
706      */
707     void clearWarnings() throws SQLException ;
708
709     /**
710      * Retrieves the name of the SQL cursor used by this <code>ResultSet</code>
711      * object.
712      *
713      * <P>In SQL, a result table is retrieved through a cursor that is
714      * named. The current row of a result set can be updated or deleted
715      * using a positioned update/delete statement that references the
716      * cursor name. To insure that the cursor has the proper isolation
717      * level to support update, the cursor's <code>SELECT</code> statement
718      * should be of the form <code>SELECT FOR UPDATE</code>. If
719      * <code>FOR UPDATE</code> is omitted, the positioned updates may fail.
720      *
721      * <P>The JDBC API supports this SQL feature by providing the name of the
722      * SQL cursor used by a <code>ResultSet</code> object.
723      * The current row of a <code>ResultSet</code> object
724      * is also the current row of this SQL cursor.
725      *
726      * <P><B>Note:</B> If positioned update is not supported, a
727      * <code>SQLException</code> is thrown.
728      *
729      * @return the SQL name for this <code>ResultSet</code> object's cursor
730      * @exception SQLException if a database access error occurs
731      */
732     String getCursorName() throws SQLException ;
733
734     /**
735      * Retrieves the number, types and properties of
736      * this <code>ResultSet</code> object's columns.
737      *
738      * @return the description of this <code>ResultSet</code> object's columns
739      * @exception SQLException if a database access error occurs
740      */
741     ResultSetMetaData getMetaData() throws SQLException ;
742
743     /**
744      * <p>Gets the value of the designated column in the current row
745      * of this <code>ResultSet</code> object as
746      * an <code>Object</code> in the Java programming language.
747      *
748      * <p>This method will return the value of the given column as a
749      * Java object. The type of the Java object will be the default
750      * Java object type corresponding to the column's SQL type,
751      * following the mapping for built-in types specified in the JDBC
752      * specification. If the value is an SQL <code>NULL</code>,
753      * the driver returns a Java <code>null</code>.
754      *
755      * <p>This method may also be used to read database-specific
756      * abstract data types.
757      *
758      * In the JDBC 2.0 API, the behavior of method
759      * <code>getObject</code> is extended to materialize
760      * data of SQL user-defined types. When a column contains
761      * a structured or distinct value, the behavior of this method is as
762      * if it were a call to: <code>getObject(columnIndex,
763      * this.getStatement().getConnection().getTypeMap())</code>.
764      *
765      * @param columnIndex the first column is 1, the second is 2, ...
766      * @return a <code>java.lang.Object</code> holding the column value
767      * @exception SQLException if a database access error occurs
768      */
769     Object getObject(int columnIndex) throws SQLException ;
770
771     /**
772      * <p>Gets the value of the designated column in the current row
773      * of this <code>ResultSet</code> object as
774      * an <code>Object</code> in the Java programming language.
775      *
776      * <p>This method will return the value of the given column as a
777      * Java object. The type of the Java object will be the default
778      * Java object type corresponding to the column's SQL type,
779      * following the mapping for built-in types specified in the JDBC
780      * specification. If the value is an SQL <code>NULL</code>,
781      * the driver returns a Java <code>null</code>.
782      * <P>
783      * This method may also be used to read database-specific
784      * abstract data types.
785      * <P>
786      * In the JDBC 2.0 API, the behavior of the method
787      * <code>getObject</code> is extended to materialize
788      * data of SQL user-defined types. When a column contains
789      * a structured or distinct value, the behavior of this method is as
790      * if it were a call to: <code>getObject(columnIndex,
791      * this.getStatement().getConnection().getTypeMap())</code>.
792      *
793      * @param columnName the SQL name of the column
794      * @return a <code>java.lang.Object</code> holding the column value
795      * @exception SQLException if a database access error occurs
796      */
797     Object getObject(String columnName) throws SQLException ;
798
799     //----------------------------------------------------------------
800
801     /**
802      * Maps the given <code>ResultSet</code> column name to its
803      * <code>ResultSet</code> column index.
804      *
805      * @param columnName the name of the column
806      * @return the column index of the given column name
807      * @exception SQLException if the <code>ResultSet</code> object
808      * does not contain <code>columnName</code> or a database access error occurs
809      */
810     int findColumn(String columnName) throws SQLException ;
811
812
813     //--------------------------JDBC 2.0-----------------------------------
814
815     //---------------------------------------------------------------------
816 // Getters and Setters
817 //---------------------------------------------------------------------
818
819     /**
820      * Retrieves the value of the designated column in the current row
821      * of this <code>ResultSet</code> object as a
822      * <code>java.io.Reader</code> object.
823      * @return a <code>java.io.Reader</code> object that contains the column
824      * value; if the value is SQL <code>NULL</code>, the value returned is
825      * <code>null</code> in the Java programming language.
826      * @param columnIndex the first column is 1, the second is 2, ...
827      * @exception SQLException if a database access error occurs
828      * @since 1.2
829      */
830     java.io.Reader getCharacterStream(int columnIndex) throws SQLException ;
831
832     /**
833      * Retrieves the value of the designated column in the current row
834      * of this <code>ResultSet</code> object as a
835      * <code>java.io.Reader</code> object.
836      *
837      * @param columnName the name of the column
838      * @return a <code>java.io.Reader</code> object that contains the column
839      * value; if the value is SQL <code>NULL</code>, the value returned is
840      * <code>null</code> in the Java programming language
841      * @exception SQLException if a database access error occurs
842      * @since 1.2
843      */
844     java.io.Reader getCharacterStream(String columnName) throws SQLException ;
845
846     /**
847      * Retrieves the value of the designated column in the current row
848      * of this <code>ResultSet</code> object as a
849      * <code>java.math.BigDecimal</code> with full precision.
850      *
851      * @param columnIndex the first column is 1, the second is 2, ...
852      * @return the column value (full precision);
853      * if the value is SQL <code>NULL</code>, the value returned is
854      * <code>null</code> in the Java programming language.
855      * @exception SQLException if a database access error occurs
856      * @since 1.2
857      */
858     BigDecimal getBigDecimal(int columnIndex) throws SQLException ;
859
860     /**
861      * Retrieves the value of the designated column in the current row
862      * of this <code>ResultSet</code> object as a
863      * <code>java.math.BigDecimal</code> with full precision.
864      *
865      * @param columnName the column name
866      * @return the column value (full precision);
867      * if the value is SQL <code>NULL</code>, the value returned is
868      * <code>null</code> in the Java programming language.
869      * @exception SQLException if a database access error occurs
870      * @since 1.2
871      *
872      */
873     BigDecimal getBigDecimal(String columnName) throws SQLException ;
874
875     //---------------------------------------------------------------------
876 // Traversal/Positioning
877 //---------------------------------------------------------------------
878
879     /**
880      * Retrieves whether the cursor is before the first row in
881      * this <code>ResultSet</code> object.
882      *
883      * @return <code>true</code> if the cursor is before the first row;
884      * <code>false</code> if the cursor is at any other position or the
885      * result set contains no rows
886      * @exception SQLException if a database access error occurs
887      * @since 1.2
888      */
889     boolean isBeforeFirst() throws SQLException ;
890       
891     /**
892      * Retrieves whether the cursor is after the last row in
893      * this <code>ResultSet</code> object.
894      *
895      * @return <code>true</code> if the cursor is after the last row;
896      * <code>false</code> if the cursor is at any other position or the
897      * result set contains no rows
898      * @exception SQLException if a database access error occurs
899      * @since 1.2
900      */
901     boolean isAfterLast() throws SQLException ;
902  
903     /**
904      * Retrieves whether the cursor is on the first row of
905      * this <code>ResultSet</code> object.
906      *
907      * @return <code>true</code> if the cursor is on the first row;
908      * <code>false</code> otherwise
909      * @exception SQLException if a database access error occurs
910      * @since 1.2
911      */
912     boolean isFirst() throws SQLException ;
913  
914     /**
915      * Retrieves whether the cursor is on the last row of
916      * this <code>ResultSet</code> object.
917      * Note: Calling the method <code>isLast</code> may be expensive
918      * because the JDBC driver
919      * might need to fetch ahead one row in order to determine
920      * whether the current row is the last row in the result set.
921      *
922      * @return <code>true</code> if the cursor is on the last row;
923      * <code>false</code> otherwise
924      * @exception SQLException if a database access error occurs
925      * @since 1.2
926      */
927     boolean isLast() throws SQLException ;
928
929     /**
930      * Moves the cursor to the front of
931      * this <code>ResultSet</code> object, just before the
932      * first row. This method has no effect if the result set contains no rows.
933      *
934      * @exception SQLException if a database access error
935      * occurs or the result set type is <code>TYPE_FORWARD_ONLY</code>
936      * @since 1.2
937      */
938     void beforeFirst() throws SQLException ;
939
940     /**
941      * Moves the cursor to the end of
942      * this <code>ResultSet</code> object, just after the
943      * last row. This method has no effect if the result set contains no rows.
944      * @exception SQLException if a database access error
945      * occurs or the result set type is <code>TYPE_FORWARD_ONLY</code>
946      * @since 1.2
947      */
948     void afterLast() throws SQLException ;
949