1 /*
2 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package java.sql;
27
28 import java.math.BigDecimal;
29 import java.util.Calendar;
30 import java.io.Reader;
31 import java.io.InputStream;
32
33 /**
34 * A table of data representing a database result set, which
35 * is usually generated by executing a statement that queries the database.
36 *
37 * <P>A <code>ResultSet</code> object maintains a cursor pointing
38 * to its current row of data. Initially the cursor is positioned
39 * before the first row. The <code>next</code> method moves the
40 * cursor to the next row, and because it returns <code>false</code>
41 * when there are no more rows in the <code>ResultSet</code> object,
42 * it can be used in a <code>while</code> loop to iterate through
43 * the result set.
44 * <P>
45 * A default <code>ResultSet</code> object is not updatable and
46 * has a cursor that moves forward only. Thus, you can
47 * iterate through it only once and only from the first row to the
48 * last row. It is possible to
49 * produce <code>ResultSet</code> objects that are scrollable and/or
50 * updatable. The following code fragment, in which <code>con</code>
51 * is a valid <code>Connection</code> object, illustrates how to make
52 * a result set that is scrollable and insensitive to updates by others, and
53 * that is updatable. See <code>ResultSet</code> fields for other
54 * options.
55 * <PRE>
56 *
57 * Statement stmt = con.createStatement(
58 * ResultSet.TYPE_SCROLL_INSENSITIVE,
59 * ResultSet.CONCUR_UPDATABLE);
60 * ResultSet rs = stmt.executeQuery("SELECT a, b FROM TABLE2");
61 * // rs will be scrollable, will not show changes made by others,
62 * // and will be updatable
63 *
64 * </PRE>
65 * The <code>ResultSet</code> interface provides
66 * <i>getter</i> methods (<code>getBoolean</code>, <code>getLong</code>, and so on)
67 * for retrieving column values from the current row.
68 * Values can be retrieved using either the index number of the
69 * column or the name of the column. In general, using the
70 * column index will be more efficient. Columns are numbered from 1.
71 * For maximum portability, result set columns within each row should be
72 * read in left-to-right order, and each column should be read only once.
73 *
74 * <P>For the getter methods, a JDBC driver attempts
75 * to convert the underlying data to the Java type specified in the
76 * getter method and returns a suitable Java value. The JDBC specification
77 * has a table showing the allowable mappings from SQL types to Java types
78 * that can be used by the <code>ResultSet</code> getter methods.
79 * <P>
80 * <P>Column names used as input to getter methods are case
81 * insensitive. When a getter method is called with
82 * a column name and several columns have the same name,
83 * the value of the first matching column will be returned.
84 * The column name option is
85 * designed to be used when column names are used in the SQL
86 * query that generated the result set.
87 * For columns that are NOT explicitly named in the query, it
88 * is best to use column numbers. If column names are used, the
89 * programmer should take care to guarantee that they uniquely refer to
90 * the intended columns, which can be assured with the SQL <i>AS</i> clause.
91 * <P>
92 * A set of updater methods were added to this interface
93 * in the JDBC 2.0 API (Java<sup><font size=-2>TM</font></sup> 2 SDK,
94 * Standard Edition, version 1.2). The comments regarding parameters
95 * to the getter methods also apply to parameters to the
96 * updater methods.
97 *<P>
98 * The updater methods may be used in two ways:
99 * <ol>
100 * <LI>to update a column value in the current row. In a scrollable
101 * <code>ResultSet</code> object, the cursor can be moved backwards
102 * and forwards, to an absolute position, or to a position
103 * relative to the current row.
104 * The following code fragment updates the <code>NAME</code> column
105 * in the fifth row of the <code>ResultSet</code> object
106 * <code>rs</code> and then uses the method <code>updateRow</code>
107 * to update the data source table from which <code>rs</code> was derived.
108 * <PRE>
109 *
110 * rs.absolute(5); // moves the cursor to the fifth row of rs
111 * rs.updateString("NAME", "AINSWORTH"); // updates the
112 * // <code>NAME</code> column of row 5 to be <code>AINSWORTH</code>
113 * rs.updateRow(); // updates the row in the data source
114 *
115 * </PRE>
116 * <LI>to insert column values into the insert row. An updatable
117 * <code>ResultSet</code> object has a special row associated with
118 * it that serves as a staging area for building a row to be inserted.
119 * The following code fragment moves the cursor to the insert row, builds
120 * a three-column row, and inserts it into <code>rs</code> and into
121 * the data source table using the method <code>insertRow</code>.
122 * <PRE>
123 *
124 * rs.moveToInsertRow(); // moves cursor to the insert row
125 * rs.updateString(1, "AINSWORTH"); // updates the
126 * // first column of the insert row to be <code>AINSWORTH</code>
127 * rs.updateInt(2,35); // updates the second column to be <code>35</code>
128 * rs.updateBoolean(3, true); // updates the third column to <code>true</code>
129 * rs.insertRow();
130 * rs.moveToCurrentRow();
131 *
132 * </PRE>
133 * </ol>
134 * <P>A <code>ResultSet</code> object is automatically closed when the
135 * <code>Statement</code> object that
136 * generated it is closed, re-executed, or used
137 * to retrieve the next result from a sequence of multiple results.
138 *
139 * <P>The number, types and properties of a <code>ResultSet</code>
140 * object's columns are provided by the <code>ResulSetMetaData</code>
141 * object returned by the <code>ResultSet.getMetaData</code> method.
142 *
143 * @see Statement#executeQuery
144 * @see Statement#getResultSet
145 * @see ResultSetMetaData
146 */
147
148 public interface ResultSet extends Wrapper {
149
150 /**
151 * Moves the cursor froward one row from its current position.
152 * A <code>ResultSet</code> cursor is initially positioned
153 * before the first row; the first call to the method
154 * <code>next</code> makes the first row the current row; the
155 * second call makes the second row the current row, and so on.
156 * <p>
157 * When a call to the <code>next</code> method returns <code>false</code>,
158 * the cursor is positioned after the last row. Any
159 * invocation of a <code>ResultSet</code> method which requires a
160 * current row will result in a <code>SQLException</code> being thrown.
161 * If the result set type is <code>TYPE_FORWARD_ONLY</code>, it is vendor specified
162 * whether their JDBC driver implementation will return <code>false</code> or
163 * throw an <code>SQLException</code> on a
164 * subsequent call to <code>next</code>.
165 *
166 * <P>If an input stream is open for the current row, a call
167 * to the method <code>next</code> will
168 * implicitly close it. A <code>ResultSet</code> object's
169 * warning chain is cleared when a new row is read.
170 *
171 * @return <code>true</code> if the new current row is valid;
172 * <code>false</code> if there are no more rows
173 * @exception SQLException if a database access error occurs or this method is
174 * called on a closed result set
175 */
176 boolean next() throws SQLException;
177
178
179 /**
180 * Releases this <code>ResultSet</code> object's database and
181 * JDBC resources immediately instead of waiting for
182 * this to happen when it is automatically closed.
183 *
184 * <P>The closing of a <code>ResultSet</code> object does <strong>not</strong> close the <code>Blob</code>,
185 * <code>Clob</code> or <code>NClob</code> objects created by the <code>ResultSet</code>. <code>Blob</code>,
186 * <code>Clob</code> or <code>NClob</code> objects remain valid for at least the duration of the
187 * transaction in which they are creataed, unless their <code>free</code> method is invoked.
188 *<p>
189 * When a <code>ResultSet</code> is closed, any <code>ResultSetMetaData</code>
190 * instances that were created by calling the <code>getMetaData</code>
191 * method remain accessible.
192 *
193 * <P><B>Note:</B> A <code>ResultSet</code> object
194 * is automatically closed by the
195 * <code>Statement</code> object that generated it when
196 * that <code>Statement</code> object is closed,
197 * re-executed, or is used to retrieve the next result from a
198 * sequence of multiple results.
199 *<p>
200 * Calling the method <code>close</code> on a <code>ResultSet</code>
201 * object that is already closed is a no-op.
202 * <P>
203 * <p>
204 *
205 * @exception SQLException if a database access error occurs
206 */
207 void close() throws SQLException;
208
209 /**
210 * Reports whether
211 * the last column read had a value of SQL <code>NULL</code>.
212 * Note that you must first call one of the getter methods
213 * on a column to try to read its value and then call
214 * the method <code>wasNull</code> to see if the value read was
215 * SQL <code>NULL</code>.
216 *
217 * @return <code>true</code> if the last column value read was SQL
218 * <code>NULL</code> and <code>false</code> otherwise
219 * @exception SQLException if a database access error occurs or this method is
220 * called on a closed result set
221 */
222 boolean wasNull() throws SQLException;
223
224 // Methods for accessing results by column index
225
226 /**
227 * Retrieves the value of the designated column in the current row
228 * of this <code>ResultSet</code> object as
229 * a <code>String</code> in the Java programming language.
230 *
231 * @param columnIndex the first column is 1, the second is 2, ...
232 * @return the column value; if the value is SQL <code>NULL</code>, the
233 * value returned is <code>null</code>
234 * @exception SQLException if the columnIndex is not valid;
235 * if a database access error occurs or this method is
236 * called on a closed result set
237 */
238 String getString(int columnIndex) throws SQLException;
239
240 /**
241 * Retrieves the value of the designated column in the current row
242 * of this <code>ResultSet</code> object as
243 * a <code>boolean</code> in the Java programming language.
244 *
245 * <P>If the designated column has a datatype of CHAR or VARCHAR
246 * and contains a "0" or has a datatype of BIT, TINYINT, SMALLINT, INTEGER or BIGINT
247 * and contains a 0, a value of <code>false</code> is returned. If the designated column has a datatype
248 * of CHAR or VARCHAR
249 * and contains a "1" or has a datatype of BIT, TINYINT, SMALLINT, INTEGER or BIGINT
250 * and contains a 1, a value of <code>true</code> is returned.
251 *
252 * @param columnIndex the first column is 1, the second is 2, ...
253 * @return the column value; if the value is SQL <code>NULL</code>, the
254 * value returned is <code>false</code>
255 * @exception SQLException if the columnIndex is not valid;
256 * if a database access error occurs or this method is
257 * called on a closed result set
258 */
259 boolean getBoolean(int columnIndex) throws SQLException;
260
261 /**
262 * Retrieves the value of the designated column in the current row
263 * of this <code>ResultSet</code> object as
264 * a <code>byte</code> in the Java programming language.
265 *
266 * @param columnIndex the first column is 1, the second is 2, ...
267 * @return the column value; if the value is SQL <code>NULL</code>, the
268 * value returned is <code>0</code>
269 * @exception SQLException if the columnIndex is not valid;
270 * if a database access error occurs or this method is
271 * called on a closed result set
272 */
273 byte getByte(int columnIndex) throws SQLException;
274
275 /**
276 * Retrieves the value of the designated column in the current row
277 * of this <code>ResultSet</code> object as
278 * a <code>short</code> in the Java programming language.
279 *
280 * @param columnIndex the first column is 1, the second is 2, ...
281 * @return the column value; if the value is SQL <code>NULL</code>, the
282 * value returned is <code>0</code>
283 * @exception SQLException if the columnIndex is not valid;
284 * if a database access error occurs or this method is
285 * called on a closed result set
286 */
287 short getShort(int columnIndex) throws SQLException;
288
289 /**
290 * Retrieves the value of the designated column in the current row
291 * of this <code>ResultSet</code> object as
292 * an <code>int</code> in the Java programming language.
293 *
294 * @param columnIndex the first column is 1, the second is 2, ...
295 * @return the column value; if the value is SQL <code>NULL</code>, the
296 * value returned is <code>0</code>
297 * @exception SQLException if the columnIndex is not valid;
298 * if a database access error occurs or this method is
299 * called on a closed result set
300 */
301 int getInt(int columnIndex) throws SQLException;
302
303 /**
304 * Retrieves the value of the designated column in the current row
305 * of this <code>ResultSet</code> object as
306 * a <code>long</code> in the Java programming language.
307 *
308 * @param columnIndex the first column is 1, the second is 2, ...
309 * @return the column value; if the value is SQL <code>NULL</code>, the
310 * value returned is <code>0</code>
311 * @exception SQLException if the columnIndex is not valid;
312 * if a database access error occurs or this method is
313 * called on a closed result set
314 */
315 long getLong(int columnIndex) throws SQLException;
316
317 /**
318 * Retrieves the value of the designated column in the current row
319 * of this <code>ResultSet</code> object as
320 * a <code>float</code> in the Java programming language.
321 *
322 * @param columnIndex the first column is 1, the second is 2, ...
323 * @return the column value; if the value is SQL <code>NULL</code>, the
324 * value returned is <code>0</code>
325 * @exception SQLException if the columnIndex is not valid;
326 * if a database access error occurs or this method is
327 * called on a closed result set
328 */
329 float getFloat(int columnIndex) throws SQLException;
330
331 /**
332 * Retrieves the value of the designated column in the current row
333 * of this <code>ResultSet</code> object as
334 * a <code>double</code> in the Java programming language.
335 *
336 * @param columnIndex the first column is 1, the second is 2, ...
337 * @return the column value; if the value is SQL <code>NULL</code>, the
338 * value returned is <code>0</code>
339 * @exception SQLException if the columnIndex is not valid;
340 * if a database access error occurs or this method is
341 * called on a closed result set
342 */
343 double getDouble(int columnIndex) throws SQLException;
344
345 /**
346 * Retrieves the value of the designated column in the current row
347 * of this <code>ResultSet</code> object as
348 * a <code>java.sql.BigDecimal</code> in the Java programming language.
349 *
350 * @param columnIndex the first column is 1, the second is 2, ...
351 * @param scale the number of digits to the right of the decimal point
352 * @return the column value; if the value is SQL <code>NULL</code>, the
353 * value returned is <code>null</code>
354 * @exception SQLException if the columnIndex is not valid;
355 * if a database access error occurs or this method is
356 * called on a closed result set
357 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
358 * this method
359 * @deprecated
360 */
361 BigDecimal getBigDecimal(int columnIndex, int scale) throws SQLException;
362
363 /**
364 * Retrieves the value of the designated column in the current row
365 * of this <code>ResultSet</code> object as
366 * a <code>byte</code> array in the Java programming language.
367 * The bytes represent the raw values returned by the driver.
368 *
369 * @param columnIndex the first column is 1, the second is 2, ...
370 * @return the column value; if the value is SQL <code>NULL</code>, the
371 * value returned is <code>null</code>
372 * @exception SQLException if the columnIndex is not valid;
373 * if a database access error occurs or this method is
374 * called on a closed result set
375 */
376 byte[] getBytes(int columnIndex) throws SQLException;
377
378 /**
379 * Retrieves the value of the designated column in the current row
380 * of this <code>ResultSet</code> object as
381 * a <code>java.sql.Date</code> object in the Java programming language.
382 *
383 * @param columnIndex the first column is 1, the second is 2, ...
384 * @return the column value; if the value is SQL <code>NULL</code>, the
385 * value returned is <code>null</code>
386 * @exception SQLException if the columnIndex is not valid;
387 * if a database access error occurs or this method is
388 * called on a closed result set
389 */
390 java.sql.Date getDate(int columnIndex) throws SQLException;
391
392 /**
393 * Retrieves the value of the designated column in the current row
394 * of this <code>ResultSet</code> object as
395 * a <code>java.sql.Time</code> object in the Java programming language.
396 *
397 * @param columnIndex the first column is 1, the second is 2, ...
398 * @return the column value; if the value is SQL <code>NULL</code>, the
399 * value returned is <code>null</code>
400 * @exception SQLException if the columnIndex is not valid;
401 * if a database access error occurs or this method is
402 * called on a closed result set
403 */
404 java.sql.Time getTime(int columnIndex) throws SQLException;
405
406 /**
407 * Retrieves the value of the designated column in the current row
408 * of this <code>ResultSet</code> object as
409 * a <code>java.sql.Timestamp</code> object in the Java programming language.
410 *
411 * @param columnIndex the first column is 1, the second is 2, ...
412 * @return the column value; if the value is SQL <code>NULL</code>, the
413 * value returned is <code>null</code>
414 * @exception SQLException if the columnIndex is not valid;
415 * if a database access error occurs or this method is
416 * called on a closed result set
417 */
418 java.sql.Timestamp getTimestamp(int columnIndex) throws SQLException;
419
420 /**
421 * Retrieves the value of the designated column in the current row
422 * of this <code>ResultSet</code> object as
423 * a stream of ASCII characters. The value can then be read in chunks from the
424 * stream. This method is particularly
425 * suitable for retrieving large <char>LONGVARCHAR</char> values.
426 * The JDBC driver will
427 * do any necessary conversion from the database format into ASCII.
428 *
429 * <P><B>Note:</B> All the data in the returned stream must be
430 * read prior to getting the value of any other column. The next
431 * call to a getter method implicitly closes the stream. Also, a
432 * stream may return <code>0</code> when the method
433 * <code>InputStream.available</code>
434 * is called whether there is data available or not.
435 *
436 * @param columnIndex the first column is 1, the second is 2, ...
437 * @return a Java input stream that delivers the database column value
438 * as a stream of one-byte ASCII characters;
439 * if the value is SQL <code>NULL</code>, the
440 * value returned is <code>null</code>
441 * @exception SQLException if the columnIndex is not valid;
442 * if a database access error occurs or this method is
443 * called on a closed result set
444 */
445 java.io.InputStream getAsciiStream(int columnIndex) throws SQLException;
446
447 /**
448 * Retrieves the value of the designated column in the current row
449 * of this <code>ResultSet</code> object as
450 * as a stream of two-byte 3 characters. The first byte is
451 * the high byte; the second byte is the low byte.
452 *
453 * The value can then be read in chunks from the
454 * stream. This method is particularly
455 * suitable for retrieving large <code>LONGVARCHAR</code>values. The
456 * JDBC driver will do any necessary conversion from the database
457 * format into Unicode.
458 *
459 * <P><B>Note:</B> All the data in the returned stream must be
460 * read prior to getting the value of any other column. The next
461 * call to a getter method implicitly closes the stream.
462 * Also, a stream may return <code>0</code> when the method
463 * <code>InputStream.available</code>
464 * is called, whether there is data available or not.
465 *
466 * @param columnIndex the first column is 1, the second is 2, ...
467 * @return a Java input stream that delivers the database column value
468 * as a stream of two-byte Unicode characters;
469 * if the value is SQL <code>NULL</code>, the value returned is
470 * <code>null</code>
471 *
472 * @exception SQLException if the columnIndex is not valid;
473 * if a database access error occurs or this method is
474 * called on a closed result set
475 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
476 * this method
477 * @deprecated use <code>getCharacterStream</code> in place of
478 * <code>getUnicodeStream</code>
479 */
480 java.io.InputStream getUnicodeStream(int columnIndex) throws SQLException;
481
482 /**
483 * Retrieves the value of the designated column in the current row
484 * of this <code>ResultSet</code> object as a stream of
485 * uninterpreted bytes. The value can then be read in chunks from the
486 * stream. This method is particularly
487 * suitable for retrieving large <code>LONGVARBINARY</code> values.
488 *
489 * <P><B>Note:</B> All the data in the returned stream must be
490 * read prior to getting the value of any other column. The next
491 * call to a getter method implicitly closes the stream. Also, a
492 * stream may return <code>0</code> when the method
493 * <code>InputStream.available</code>
494 * is called whether there is data available or not.
495 *
496 * @param columnIndex the first column is 1, the second is 2, ...
497 * @return a Java input stream that delivers the database column value
498 * as a stream of uninterpreted bytes;
499 * if the value is SQL <code>NULL</code>, the value returned is
500 * <code>null</code>
501 * @exception SQLException if the columnIndex is not valid;
502 * if a database access error occurs or this method is
503 * called on a closed result set
504 */
505 java.io.InputStream getBinaryStream(int columnIndex)
506 throws SQLException;
507
508
509 // Methods for accessing results by column label
510
511 /**
512 * Retrieves the value of the designated column in the current row
513 * of this <code>ResultSet</code> object as
514 * a <code>String</code> in the Java programming language.
515 *
516 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
517 * @return the column value; if the value is SQL <code>NULL</code>, the
518 * value returned is <code>null</code>
519 * @exception SQLException if the columnLabel is not valid;
520 * if a database access error occurs or this method is
521 * called on a closed result set
522 */
523 String getString(String columnLabel) throws SQLException;
524
525 /**
526 * Retrieves the value of the designated column in the current row
527 * of this <code>ResultSet</code> object as
528 * a <code>boolean</code> in the Java programming language.
529 *
530 * <P>If the designated column has a datatype of CHAR or VARCHAR
531 * and contains a "0" or has a datatype of BIT, TINYINT, SMALLINT, INTEGER or BIGINT
532 * and contains a 0, a value of <code>false</code> is returned. If the designated column has a datatype
533 * of CHAR or VARCHAR
534 * and contains a "1" or has a datatype of BIT, TINYINT, SMALLINT, INTEGER or BIGINT
535 * and contains a 1, a value of <code>true</code> is returned.
536 *
537 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
538 * @return the column value; if the value is SQL <code>NULL</code>, the
539 * value returned is <code>false</code>
540 * @exception SQLException if the columnLabel is not valid;
541 * if a database access error occurs or this method is
542 * called on a closed result set
543 */
544 boolean getBoolean(String columnLabel) throws SQLException;
545
546 /**
547 * Retrieves the value of the designated column in the current row
548 * of this <code>ResultSet</code> object as
549 * a <code>byte</code> in the Java programming language.
550 *
551 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
552 * @return the column value; if the value is SQL <code>NULL</code>, the
553 * value returned is <code>0</code>
554 * @exception SQLException if the columnLabel is not valid;
555 * if a database access error occurs or this method is
556 * called on a closed result set
557 */
558 byte getByte(String columnLabel) throws SQLException;
559
560 /**
561 * Retrieves the value of the designated column in the current row
562 * of this <code>ResultSet</code> object as
563 * a <code>short</code> in the Java programming language.
564 *
565 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
566 * @return the column value; if the value is SQL <code>NULL</code>, the
567 * value returned is <code>0</code>
568 * @exception SQLException if the columnLabel is not valid;
569 * if a database access error occurs or this method is
570 * called on a closed result set
571 */
572 short getShort(String columnLabel) throws SQLException;
573
574 /**
575 * Retrieves the value of the designated column in the current row
576 * of this <code>ResultSet</code> object as
577 * an <code>int</code> in the Java programming language.
578 *
579 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
580 * @return the column value; if the value is SQL <code>NULL</code>, the
581 * value returned is <code>0</code>
582 * @exception SQLException if the columnLabel is not valid;
583 * if a database access error occurs or this method is
584 * called on a closed result set
585 */
586 int getInt(String columnLabel) throws SQLException;
587
588 /**
589 * Retrieves the value of the designated column in the current row
590 * of this <code>ResultSet</code> object as
591 * a <code>long</code> in the Java programming language.
592 *
593 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
594 * @return the column value; if the value is SQL <code>NULL</code>, the
595 * value returned is <code>0</code>
596 * @exception SQLException if the columnLabel is not valid;
597 * if a database access error occurs or this method is
598 * called on a closed result set
599 */
600 long getLong(String columnLabel) throws SQLException;
601
602 /**
603 * Retrieves the value of the designated column in the current row
604 * of this <code>ResultSet</code> object as
605 * a <code>float</code> in the Java programming language.
606 *
607 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
608 * @return the column value; if the value is SQL <code>NULL</code>, the
609 * value returned is <code>0</code>
610 * @exception SQLException if the columnLabel is not valid;
611 * if a database access error occurs or this method is
612 * called on a closed result set
613 */
614 float getFloat(String columnLabel) throws SQLException;
615
616 /**
617 * Retrieves the value of the designated column in the current row
618 * of this <code>ResultSet</code> object as
619 * a <code>double</code> in the Java programming language.
620 *
621 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
622 * @return the column value; if the value is SQL <code>NULL</code>, the
623 * value returned is <code>0</code>
624 * @exception SQLException if the columnLabel is not valid;
625 * if a database access error occurs or this method is
626 * called on a closed result set
627 */
628 double getDouble(String columnLabel) throws SQLException;
629
630 /**
631 * Retrieves the value of the designated column in the current row
632 * of this <code>ResultSet</code> object as
633 * a <code>java.math.BigDecimal</code> in the Java programming language.
634 *
635 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
636 * @param scale the number of digits to the right of the decimal point
637 * @return the column value; if the value is SQL <code>NULL</code>, the
638 * value returned is <code>null</code>
639 * @exception SQLException if the columnLabel is not valid;
640 * if a database access error occurs or this method is
641 * called on a closed result set
642 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
643 * this method
644 * @deprecated
645 */
646 BigDecimal getBigDecimal(String columnLabel, int scale) throws SQLException;
647
648 /**
649 * Retrieves the value of the designated column in the current row
650 * of this <code>ResultSet</code> object as
651 * a <code>byte</code> array in the Java programming language.
652 * The bytes represent the raw values returned by the driver.
653 *
654 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
655 * @return the column value; if the value is SQL <code>NULL</code>, the
656 * value returned is <code>null</code>
657 * @exception SQLException if the columnLabel is not valid;
658 * if a database access error occurs or this method is
659 * called on a closed result set
660 */
661 byte[] getBytes(String columnLabel) throws SQLException;
662
663 /**
664 * Retrieves the value of the designated column in the current row
665 * of this <code>ResultSet</code> object as
666 * a <code>java.sql.Date</code> object in the Java programming language.
667 *
668 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
669 * @return the column value; if the value is SQL <code>NULL</code>, the
670 * value returned is <code>null</code>
671 * @exception SQLException if the columnLabel is not valid;
672 * if a database access error occurs or this method is
673 * called on a closed result set
674 */
675 java.sql.Date getDate(String columnLabel) throws SQLException;
676
677 /**
678 * Retrieves the value of the designated column in the current row
679 * of this <code>ResultSet</code> object as
680 * a <code>java.sql.Time</code> object in the Java programming language.
681 *
682 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
683 * @return the column value;
684 * if the value is SQL <code>NULL</code>,
685 * the value returned is <code>null</code>
686 * @exception SQLException if the columnLabel is not valid;
687 * if a database access error occurs or this method is
688 * called on a closed result set
689 */
690 java.sql.Time getTime(String columnLabel) throws SQLException;
691
692 /**
693 * Retrieves the value of the designated column in the current row
694 * of this <code>ResultSet</code> object as
695 * a <code>java.sql.Timestamp</code> object in the Java programming language.
696 *
697 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
698 * @return the column value; if the value is SQL <code>NULL</code>, the
699 * value returned is <code>null</code>
700 * @exception SQLException if the columnLabel is not valid;
701 * if a database access error occurs or this method is
702 * called on a closed result set
703 */
704 java.sql.Timestamp getTimestamp(String columnLabel) throws SQLException;
705
706 /**
707 * Retrieves the value of the designated column in the current row
708 * of this <code>ResultSet</code> object as a stream of
709 * ASCII characters. The value can then be read in chunks from the
710 * stream. This method is particularly
711 * suitable for retrieving large <code>LONGVARCHAR</code> values.
712 * The JDBC driver will
713 * do any necessary conversion from the database format into ASCII.
714 *
715 * <P><B>Note:</B> All the data in the returned stream must be
716 * read prior to getting the value of any other column. The next
717 * call to a getter method implicitly closes the stream. Also, a
718 * stream may return <code>0</code> when the method <code>available</code>
719 * is called whether there is data available or not.
720 *
721 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
722 * @return a Java input stream that delivers the database column value
723 * as a stream of one-byte ASCII characters.
724 * If the value is SQL <code>NULL</code>,
725 * the value returned is <code>null</code>.
726 * @exception SQLException if the columnLabel is not valid;
727 * if a database access error occurs or this method is
728 * called on a closed result set
729 */
730 java.io.InputStream getAsciiStream(String columnLabel) throws SQLException;
731
732 /**
733 * Retrieves the value of the designated column in the current row
734 * of this <code>ResultSet</code> object as a stream of two-byte
735 * Unicode characters. The first byte is the high byte; the second
736 * byte is the low byte.
737 *
738 * The value can then be read in chunks from the
739 * stream. This method is particularly
740 * suitable for retrieving large <code>LONGVARCHAR</code> values.
741 * The JDBC technology-enabled driver will
742 * do any necessary conversion from the database format into Unicode.
743 *
744 * <P><B>Note:</B> All the data in the returned stream must be
745 * read prior to getting the value of any other column. The next
746 * call to a getter method implicitly closes the stream.
747 * Also, a stream may return <code>0</code> when the method
748 * <code>InputStream.available</code> is called, whether there
749 * is data available or not.
750 *
751 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
752 * @return a Java input stream that delivers the database column value
753 * as a stream of two-byte Unicode characters.
754 * If the value is SQL <code>NULL</code>, the value returned
755 * is <code>null</code>.
756 * @exception SQLException if the columnLabel is not valid;
757 * if a database access error occurs or this method is
758 * called on a closed result set
759 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
760 * this method
761 * @deprecated use <code>getCharacterStream</code> instead
762 */
763 java.io.InputStream getUnicodeStream(String columnLabel) throws SQLException;
764
765 /**
766 * Retrieves the value of the designated column in the current row
767 * of this <code>ResultSet</code> object as a stream of uninterpreted
768 * <code>byte</code>s.
769 * The value can then be read in chunks from the
770 * stream. This method is particularly
771 * suitable for retrieving large <code>LONGVARBINARY</code>
772 * values.
773 *
774 * <P><B>Note:</B> All the data in the returned stream must be
775 * read prior to getting the value of any other column. The next
776 * call to a getter method implicitly closes the stream. Also, a
777 * stream may return <code>0</code> when the method <code>available</code>
778 * is called whether there is data available or not.
779 *
780 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
781 * @return a Java input stream that delivers the database column value
782 * as a stream of uninterpreted bytes;
783 * if the value is SQL <code>NULL</code>, the result is <code>null</code>
784 * @exception SQLException if the columnLabel is not valid;
785 * if a database access error occurs or this method is
786 * called on a closed result set
787 */
788 java.io.InputStream getBinaryStream(String columnLabel)
789 throws SQLException;
790
791
792 // Advanced features:
793
794 /**
795 * Retrieves the first warning reported by calls on this
796 * <code>ResultSet</code> object.
797 * Subsequent warnings on this <code>ResultSet</code> object
798 * will be chained to the <code>SQLWarning</code> object that
799 * this method returns.
800 *
801 * <P>The warning chain is automatically cleared each time a new
802 * row is read. This method may not be called on a <code>ResultSet</code>
803 * object that has been closed; doing so will cause an
804 * <code>SQLException</code> to be thrown.
805 * <P>
806 * <B>Note:</B> This warning chain only covers warnings caused
807 * by <code>ResultSet</code> methods. Any warning caused by
808 * <code>Statement</code> methods
809 * (such as reading OUT parameters) will be chained on the
810 * <code>Statement</code> object.
811 *
812 * @return the first <code>SQLWarning</code> object reported or
813 * <code>null</code> if there are none
814 * @exception SQLException if a database access error occurs or this method is
815 * called on a closed result set
816 */
817 SQLWarning getWarnings() throws SQLException;
818
819 /**
820 * Clears all warnings reported on this <code>ResultSet</code> object.
821 * After this method is called, the method <code>getWarnings</code>
822 * returns <code>null</code> until a new warning is
823 * reported for this <code>ResultSet</code> object.
824 *
825 * @exception SQLException if a database access error occurs or this method is
826 * called on a closed result set
827 */
828 void clearWarnings() throws SQLException;
829
830 /**
831 * Retrieves the name of the SQL cursor used by this <code>ResultSet</code>
832 * object.
833 *
834 * <P>In SQL, a result table is retrieved through a cursor that is
835 * named. The current row of a result set can be updated or deleted
836 * using a positioned update/delete statement that references the
837 * cursor name. To insure that the cursor has the proper isolation
838 * level to support update, the cursor's <code>SELECT</code> statement
839 * should be of the form <code>SELECT FOR UPDATE</code>. If
840 * <code>FOR UPDATE</code> is omitted, the positioned updates may fail.
841 *
842 * <P>The JDBC API supports this SQL feature by providing the name of the
843 * SQL cursor used by a <code>ResultSet</code> object.
844 * The current row of a <code>ResultSet</code> object
845 * is also the current row of this SQL cursor.
846 *
847 * @return the SQL name for this <code>ResultSet</code> object's cursor
848 * @exception SQLException if a database access error occurs or this method is called on a closed result set
849 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
850 * this method
851 */
852 String getCursorName() throws SQLException;
853
854 /**
855 * Retrieves the number, types and properties of
856 * this <code>ResultSet</code> object's columns.
857 *
858 * @return the description of this <code>ResultSet</code> object's columns
859 * @exception SQLException if a database access error occurs or this method is
860 * called on a closed result set
861 */
862 ResultSetMetaData getMetaData() throws SQLException;
863
864 /**
865 * <p>Gets the value of the designated column in the current row
866 * of this <code>ResultSet</code> object as
867 * an <code>Object</code> in the Java programming language.
868 *
869 * <p>This method will return the value of the given column as a
870 * Java object. The type of the Java object will be the default
871 * Java object type corresponding to the column's SQL type,
872 * following the mapping for built-in types specified in the JDBC
873 * specification. If the value is an SQL <code>NULL</code>,
874 * the driver returns a Java <code>null</code>.
875 *
876 * <p>This method may also be used to read database-specific
877 * abstract data types.
878 *
879 * In the JDBC 2.0 API, the behavior of method
880 * <code>getObject</code> is extended to materialize
881 * data of SQL user-defined types.
882 * <p>
883 * If <code>Connection.getTypeMap</code> does not throw a
884 * <code>SQLFeatureNotSupportedException</code>,
885 * then when a column contains a structured or distinct value,
886 * the behavior of this method is as
887 * if it were a call to: <code>getObject(columnIndex,
888 * this.getStatement().getConnection().getTypeMap())</code>.
889 *
890 * If <code>Connection.getTypeMap</code> does throw a
891 * <code>SQLFeatureNotSupportedException</code>,
892 * then structured values are not supported, and distinct values
893 * are mapped to the default Java class as determined by the
894 * underlying SQL type of the DISTINCT type.
895 *
896 * @param columnIndex the first column is 1, the second is 2, ...
897 * @return a <code>java.lang.Object</code> holding the column value
898 * @exception SQLException if the columnIndex is not valid;
899 * if a database access error occurs or this method is
900 * called on a closed result set
901 */
902 Object getObject(int columnIndex) throws SQLException;
903
904 /**
905 * <p>Gets the value of the designated column in the current row
906 * of this <code>ResultSet</code> object as
907 * an <code>Object</code> in the Java programming language.
908 *
909 * <p>This method will return the value of the given column as a
910 * Java object. The type of the Java object will be the default
911 * Java object type corresponding to the column's SQL type,
912 * following the mapping for built-in types specified in the JDBC
913 * specification. If the value is an SQL <code>NULL</code>,
914 * the driver returns a Java <code>null</code>.
915 * <P>
916 * This method may also be used to read database-specific
917 * abstract data types.
918 * <P>
919 * In the JDBC 2.0 API, the behavior of the method
920 * <code>getObject</code> is extended to materialize
921 * data of SQL user-defined types. When a column contains
922 * a structured or distinct value, the behavior of this method is as
923 * if it were a call to: <code>getObject(columnIndex,
924 * this.getStatement().getConnection().getTypeMap())</code>.
925 *
926 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
927 * @return a <code>java.lang.Object</code> holding the column value
928 * @exception SQLException if the columnLabel is not valid;
929 * if a database access error occurs or this method is
930 * called on a closed result set
931 */
932 Object getObject(String columnLabel) throws SQLException;
933
934 //----------------------------------------------------------------
935
936 /**
937 * Maps the given <code>ResultSet</code> column label to its
938 * <code>ResultSet</code> column index.
939 *
940 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
941 * @return the column index of the given column name
942 * @exception SQLException if the <code>ResultSet</code> object
943 * does not contain a column labeled <code>columnLabel</code>, a database access error occurs
944 * or this method is called on a closed result set
945 */
946 int findColumn(String columnLabel) throws SQLException;
947
948
949 //--------------------------JDBC 2.0-----------------------------------
950
951 //---------------------------------------------------------------------
952 // Getters and Setters
953 //---------------------------------------------------------------------
954
955 /**
956 * Retrieves the value of the designated column in the current row
957 * of this <code>ResultSet</code> object as a
958 * <code>java.io.Reader</code> object.
959 * @return a <code>java.io.Reader</code> object that contains the column
960 * value; if the value is SQL <code>NULL</code>, the value returned is
961 * <code>null</code> in the Java programming language.
962 * @param columnIndex the first column is 1, the second is 2, ...
963 * @exception SQLException if the columnIndex is not valid;
964 * if a database access error occurs or this method is
965 * called on a closed result set
966 * @since 1.2
967 */
968 java.io.Reader getCharacterStream(int columnIndex) throws SQLException;
969
970 /**
971 * Retrieves the value of the designated column in the current row
972 * of this <code>ResultSet</code> object as a
973 * <code>java.io.Reader</code> object.
974 *
975 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
976 * @return a <code>java.io.Reader</code> object that contains the column
977 * value; if the value is SQL <code>NULL</code>, the value returned is
978 * <code>null</code> in the Java programming language
979 * @exception SQLException if the columnLabel is not valid;
980 * if a database access error occurs or this method is
981 * called on a closed result set
982 * @since 1.2
983 */
984 java.io.Reader getCharacterStream(String columnLabel) throws SQLException;
985
986 /**
987 * Retrieves the value of the designated column in the current row
988 * of this <code>ResultSet</code> object as a
989 * <code>java.math.BigDecimal</code> with full precision.
990 *
991 * @param columnIndex the first column is 1, the second is 2, ...
992 * @return the column value (full precision);
993 * if the value is SQL <code>NULL</code>, the value returned is
994 * <code>null</code> in the Java programming language.
995 * @exception SQLException if the columnIndex is not valid;
996 * if a database access error occurs or this method is
997 * called on a closed result set
998 * @since 1.2
999 */
1000 BigDecimal getBigDecimal(int columnIndex) throws SQLException;
1001
1002 /**
1003 * Retrieves the value of the designated column in the current row
1004 * of this <code>ResultSet</code> object as a
1005 * <code>java.math.BigDecimal</code> with full precision.
1006 *
1007 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
1008 * @return the column value (full precision);
1009 * if the value is SQL <code>NULL</code>, the value returned is
1010 * <code>null</code> in the Java programming language.
1011 * @exception SQLException if the columnLabel is not valid;
1012 * if a database access error occurs or this method is
1013 * called on a closed result set
1014 * @since 1.2
1015 *
1016 */
1017 BigDecimal getBigDecimal(String columnLabel) throws SQLException;
1018
1019 //---------------------------------------------------------------------
1020 // Traversal/Positioning
1021 //---------------------------------------------------------------------
1022
1023 /**
1024 * Retrieves whether the cursor is before the first row in
1025 * this <code>ResultSet</code> object.
1026 * <p>
1027 * <strong>Note:</strong>Support for the <code>isBeforeFirst</code> method
1028 * is optional for <code>ResultSet</code>s with a result
1029 * set type of <code>TYPE_FORWARD_ONLY</code>
1030 *
1031 * @return <code>true</code> if the cursor is before the first row;
1032 * <code>false</code> if the cursor is at any other position or the
1033 * result set contains no rows
1034 * @exception SQLException if a database access error occurs or this method is
1035 * called on a closed result set
1036 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1037 * this method
1038 * @since 1.2
1039 */
1040 boolean isBeforeFirst() throws SQLException;
1041
1042 /**
1043 * Retrieves whether the cursor is after the last row in
1044 * this <code>ResultSet</code> object.
1045 * <p>
1046 * <strong>Note:</strong>Support for the <code>isAfterLast</code> method
1047 * is optional for <code>ResultSet</code>s with a result
1048 * set type of <code>TYPE_FORWARD_ONLY</code>
1049 *
1050 * @return <code>true</code> if the cursor is after the last row;
1051 * <code>false</code> if the cursor is at any other position or the
1052 * result set contains no rows
1053 * @exception SQLException if a database access error occurs or this method is
1054 * called on a closed result set
1055 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1056 * this method
1057 * @since 1.2
1058 */
1059 boolean isAfterLast() throws SQLException;
1060
1061 /**
1062 * Retrieves whether the cursor is on the first row of
1063 * this <code>ResultSet</code> object.
1064 * <p>
1065 * <strong>Note:</strong>Support for the <code>isFirst</code> method
1066 * is optional for <code>ResultSet</code>s with a result
1067 * set type of <code>TYPE_FORWARD_ONLY</code>
1068 *
1069 * @return <code>true</code> if the cursor is on the first row;
1070 * <code>false</code> otherwise
1071 * @exception SQLException if a database access error occurs or this method is
1072 * called on a closed result set
1073 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1074 * this method
1075 * @since 1.2
1076 */
1077 boolean isFirst() throws SQLException;
1078
1079 /**
1080 * Retrieves whether the cursor is on the last row of
1081 * this <code>ResultSet</code> object.
1082 * <strong>Note:</strong> Calling the method <code>isLast</code> may be expensive
1083 * because the JDBC driver
1084 * might need to fetch ahead one row in order to determine
1085 * whether the current row is the last row in the result set.
1086 * <p>
1087 * <strong>Note:</strong> Support for the <code>isLast</code> method
1088 * is optional for <code>ResultSet</code>s with a result
1089 * set type of <code>TYPE_FORWARD_ONLY</code>
1090 * @return <code>true</code> if the cursor is on the last row;
1091 * <code>false</code> otherwise
1092 * @exception SQLException if a database access error occurs or this method is
1093 * called on a closed result set
1094 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1095 * this method
1096 * @since 1.2
1097 */
1098 boolean isLast() throws SQLException;
1099
1100 /**
1101 * Moves the cursor to the front of
1102 * this <code>ResultSet</code> object, just before the
1103 * first row. This method has no effect if the result set contains no rows.
1104 *
1105 * @exception SQLException if a database access error
1106 * occurs; this method is called on a closed result set or the
1107 * result set type is <code>TYPE_FORWARD_ONLY</code>
1108 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1109 * this method
1110 * @since 1.2
1111 */
1112 void beforeFirst() throws SQLException;
1113
1114 /**
1115 * Moves the cursor to the end of
1116 * this <code>ResultSet</code> object, just after the
1117 * last row. This method has no effect if the result set contains no rows.
1118 * @exception SQLException if a database access error
1119 * occurs; this method is called on a closed result set
1120 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1121 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1122 * this method
1123 * @since 1.2
1124 */
1125 void afterLast() throws SQLException;
1126
1127 /**
1128 * Moves the cursor to the first row in
1129 * this <code>ResultSet</code> object.
1130 *
1131 * @return <code>true</code> if the cursor is on a valid row;
1132 * <code>false</code> if there are no rows in the result set
1133 * @exception SQLException if a database access error
1134 * occurs; this method is called on a closed result set
1135 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1136 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1137 * this method
1138 * @since 1.2
1139 */
1140 boolean first() throws SQLException;
1141
1142 /**
1143 * Moves the cursor to the last row in
1144 * this <code>ResultSet</code> object.
1145 *
1146 * @return <code>true</code> if the cursor is on a valid row;
1147 * <code>false</code> if there are no rows in the result set
1148 * @exception SQLException if a database access error
1149 * occurs; this method is called on a closed result set
1150 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1151 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1152 * this method
1153 * @since 1.2
1154 */
1155 boolean last() throws SQLException;
1156
1157 /**
1158 * Retrieves the current row number. The first row is number 1, the
1159 * second number 2, and so on.
1160 * <p>
1161 * <strong>Note:</strong>Support for the <code>getRow</code> method
1162 * is optional for <code>ResultSet</code>s with a result
1163 * set type of <code>TYPE_FORWARD_ONLY</code>
1164 *
1165 * @return the current row number; <code>0</code> if there is no current row
1166 * @exception SQLException if a database access error occurs
1167 * or this method is called on a closed result set
1168 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1169 * this method
1170 * @since 1.2
1171 */
1172 int getRow() throws SQLException;
1173
1174 /**
1175 * Moves the cursor to the given row number in
1176 * this <code>ResultSet</code> object.
1177 *
1178 * <p>If the row number is positive, the cursor moves to
1179 * the given row number with respect to the
1180 * beginning of the result set. The first row is row 1, the second
1181 * is row 2, and so on.
1182 *
1183 * <p>If the given row number is negative, the cursor moves to
1184 * an absolute row position with respect to
1185 * the end of the result set. For example, calling the method
1186 * <code>absolute(-1)</code> positions the
1187 * cursor on the last row; calling the method <code>absolute(-2)</code>
1188 * moves the cursor to the next-to-last row, and so on.
1189 *
1190 * <p>An attempt to position the cursor beyond the first/last row in
1191 * the result set leaves the cursor before the first row or after
1192 * the last row.
1193 *
1194 * <p><B>Note:</B> Calling <code>absolute(1)</code> is the same
1195 * as calling <code>first()</code>. Calling <code>absolute(-1)</code>
1196 * is the same as calling <code>last()</code>.
1197 *
1198 * @param row the number of the row to which the cursor should move.
1199 * A positive number indicates the row number counting from the
1200 * beginning of the result set; a negative number indicates the
1201 * row number counting from the end of the result set
1202 * @return <code>true</code> if the cursor is moved to a position in this
1203 * <code>ResultSet</code> object;
1204 * <code>false</code> if the cursor is before the first row or after the
1205 * last row
1206 * @exception SQLException if a database access error
1207 * occurs; this method is called on a closed result set
1208 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1209 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1210 * this method
1211 * @since 1.2
1212 */
1213 boolean absolute( int row ) throws SQLException;
1214
1215 /**
1216 * Moves the cursor a relative number of rows, either positive or negative.
1217 * Attempting to move beyond the first/last row in the
1218 * result set positions the cursor before/after the
1219 * the first/last row. Calling <code>relative(0)</code> is valid, but does
1220 * not change the cursor position.
1221 *
1222 * <p>Note: Calling the method <code>relative(1)</code>
1223 * is identical to calling the method <code>next()</code> and
1224 * calling the method <code>relative(-1)</code> is identical
1225 * to calling the method <code>previous()</code>.
1226 *
1227 * @param rows an <code>int</code> specifying the number of rows to
1228 * move from the current row; a positive number moves the cursor
1229 * forward; a negative number moves the cursor backward
1230 * @return <code>true</code> if the cursor is on a row;
1231 * <code>false</code> otherwise
1232 * @exception SQLException if a database access error occurs; this method
1233 * is called on a closed result set or the result set type is
1234 * <code>TYPE_FORWARD_ONLY</code>
1235 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1236 * this method
1237 * @since 1.2
1238 */
1239 boolean relative( int rows ) throws SQLException;
1240
1241 /**
1242 * Moves the cursor to the previous row in this
1243 * <code>ResultSet</code> object.
1244 *<p>
1245 * When a call to the <code>previous</code> method returns <code>false</code>,
1246 * the cursor is positioned before the first row. Any invocation of a
1247 * <code>ResultSet</code> method which requires a current row will result in a
1248 * <code>SQLException</code> being thrown.
1249 *<p>
1250 * If an input stream is open for the current row, a call to the method
1251 * <code>previous</code> will implicitly close it. A <code>ResultSet</code>
1252 * object's warning change is cleared when a new row is read.
1253 *<p>
1254 *
1255 * @return <code>true</code> if the cursor is now positioned on a valid row;
1256 * <code>false</code> if the cursor is positioned before the first row
1257 * @exception SQLException if a database access error
1258 * occurs; this method is called on a closed result set
1259 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1260 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1261 * this method
1262 * @since 1.2
1263 */
1264 boolean previous() throws SQLException;
1265
1266 //---------------------------------------------------------------------
1267 // Properties
1268 //---------------------------------------------------------------------
1269
1270 /**
1271 * The constant indicating that the rows in a result set will be
1272 * processed in a forward direction; first-to-last.
1273 * This constant is used by the method <code>setFetchDirection</code>
1274 * as a hint to the driver, which the driver may ignore.
1275 * @since 1.2
1276 */
1277 int FETCH_FORWARD = 1000;
1278
1279 /**
1280 * The constant indicating that the rows in a result set will be
1281 * processed in a reverse direction; last-to-first.
1282 * This constant is used by the method <code>setFetchDirection</code>
1283 * as a hint to the driver, which the driver may ignore.
1284 * @since 1.2
1285 */
1286 int FETCH_REVERSE = 1001;
1287
1288 /**
1289 * The constant indicating that the order in which rows in a
1290 * result set will be processed is unknown.
1291 * This constant is used by the method <code>setFetchDirection</code>
1292 * as a hint to the driver, which the driver may ignore.
1293 */
1294 int FETCH_UNKNOWN = 1002;
1295
1296 /**
1297 * Gives a hint as to the direction in which the rows in this
1298 * <code>ResultSet</code> object will be processed.
1299 * The initial value is determined by the
1300 * <code>Statement</code> object
1301 * that produced this <code>ResultSet</code> object.
1302 * The fetch direction may be changed at any time.
1303 *
1304 * @param direction an <code>int</code> specifying the suggested
1305 * fetch direction; one of <code>ResultSet.FETCH_FORWARD</code>,
1306 * <code>ResultSet.FETCH_REVERSE</code>, or
1307 * <code>ResultSet.FETCH_UNKNOWN</code>
1308 * @exception SQLException if a database access error occurs; this
1309 * method is called on a closed result set or
1310 * the result set type is <code>TYPE_FORWARD_ONLY</code> and the fetch
1311 * direction is not <code>FETCH_FORWARD</code>
1312 * @since 1.2
1313 * @see Statement#setFetchDirection
1314 * @see #getFetchDirection
1315 */
1316 void setFetchDirection(int direction) throws SQLException;
1317
1318 /**
1319 * Retrieves the fetch direction for this
1320 * <code>ResultSet</code> object.
1321 *
1322 * @return the current fetch direction for this <code>ResultSet</code> object
1323 * @exception SQLException if a database access error occurs
1324 * or this method is called on a closed result set
1325 * @since 1.2
1326 * @see #setFetchDirection
1327 */
1328 int getFetchDirection() throws SQLException;
1329
1330 /**
1331 * Gives the JDBC driver a hint as to the number of rows that should
1332 * be fetched from the database when more rows are needed for this
1333 * <code>ResultSet</code> object.
1334 * If the fetch size specified is zero, the JDBC driver
1335 * ignores the value and is free to make its own best guess as to what
1336 * the fetch size should be. The default value is set by the
1337 * <code>Statement</code> object
1338 * that created the result set. The fetch size may be changed at any time.
1339 *
1340 * @param rows the number of rows to fetch
1341 * @exception SQLException if a database access error occurs; this method
1342 * is called on a closed result set or the
1343 * condition <code>rows >= 0 </code> is not satisfied
1344 * @since 1.2
1345 * @see #getFetchSize
1346 */
1347 void setFetchSize(int rows) throws SQLException;
1348
1349 /**
1350 * Retrieves the fetch size for this
1351 * <code>ResultSet</code> object.
1352 *
1353 * @return the current fetch size for this <code>ResultSet</code> object
1354 * @exception SQLException if a database access error occurs
1355 * or this method is called on a closed result set
1356 * @since 1.2
1357 * @see #setFetchSize
1358 */
1359 int getFetchSize() throws SQLException;
1360
1361 /**
1362 * The constant indicating the type for a <code>ResultSet</code> object
1363 * whose cursor may move only forward.
1364 * @since 1.2
1365 */
1366 int TYPE_FORWARD_ONLY = 1003;
1367
1368 /**
1369 * The constant indicating the type for a <code>ResultSet</code> object
1370 * that is scrollable but generally not sensitive to changes to the data
1371 * that underlies the <code>ResultSet</code>.
1372 * @since 1.2
1373 */
1374 int TYPE_SCROLL_INSENSITIVE = 1004;
1375
1376 /**
1377 * The constant indicating the type for a <code>ResultSet</code> object
1378 * that is scrollable and generally sensitive to changes to the data
1379 * that underlies the <code>ResultSet</code>.
1380 * @since 1.2
1381 */
1382 int TYPE_SCROLL_SENSITIVE = 1005;
1383
1384 /**
1385 * Retrieves the type of this <code>ResultSet</code> object.
1386 * The type is determined by the <code>Statement</code> object
1387 * that created the result set.
1388 *
1389 * @return <code>ResultSet.TYPE_FORWARD_ONLY</code>,
1390 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>,
1391 * or <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
1392 * @exception SQLException if a database access error occurs
1393 * or this method is called on a closed result set
1394 * @since 1.2
1395 */
1396 int getType() throws SQLException;
1397
1398 /**
1399 * The constant indicating the concurrency mode for a
1400 * <code>ResultSet</code> object that may NOT be updated.
1401 * @since 1.2
1402 */
1403 int CONCUR_READ_ONLY = 1007;
1404
1405 /**
1406 * The constant indicating the concurrency mode for a
1407 * <code>ResultSet</code> object that may be updated.
1408 * @since 1.2
1409 */
1410 int CONCUR_UPDATABLE = 1008;
1411
1412 /**
1413 * Retrieves the concurrency mode of this <code>ResultSet</code> object.
1414 * The concurrency used is determined by the
1415 * <code>Statement</code> object that created the result set.
1416 *
1417 * @return the concurrency type, either
1418 * <code>ResultSet.CONCUR_READ_ONLY</code>
1419 * or <code>ResultSet.CONCUR_UPDATABLE</code>
1420 * @exception SQLException if a database access error occurs
1421 * or this method is called on a closed result set
1422 * @since 1.2
1423 */
1424 int getConcurrency() throws SQLException;
1425
1426 //---------------------------------------------------------------------
1427 // Updates
1428 //---------------------------------------------------------------------
1429
1430 /**
1431 * Retrieves whether the current row has been updated. The value returned
1432 * depends on whether or not the result set can detect updates.
1433 * <p>
1434 * <strong>Note:</strong> Support for the <code>rowUpdated</code> method is optional with a result set
1435 * concurrency of <code>CONCUR_READ_ONLY</code>
1436 * @return <code>true</code> if the current row is detected to
1437 * have been visibly updated by the owner or another; <code>false</code> otherwise
1438 * @exception SQLException if a database access error occurs
1439 * or this method is called on a closed result set
1440 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1441 * this method
1442 * @see DatabaseMetaData#updatesAreDetected
1443 * @since 1.2
1444 */
1445 boolean rowUpdated() throws SQLException;
1446
1447 /**
1448 * Retrieves whether the current row has had an insertion.
1449 * The value returned depends on whether or not this
1450 * <code>ResultSet</code> object can detect visible inserts.
1451 * <p>
1452 * <strong>Note:</strong> Support for the <code>rowInserted</code> method is optional with a result set
1453 * concurrency of <code>CONCUR_READ_ONLY</code>
1454 * @return <code>true</code> if the current row is detected to
1455 * have been inserted; <code>false</code> otherwise
1456 * @exception SQLException if a database access error occurs
1457 * or this method is called on a closed result set
1458 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1459 * this method
1460 *
1461 * @see DatabaseMetaData#insertsAreDetected
1462 * @since 1.2
1463 */
1464 boolean rowInserted() throws SQLException;
1465
1466 /**
1467 * Retrieves whether a row has been deleted. A deleted row may leave
1468 * a visible "hole" in a result set. This method can be used to
1469 * detect holes in a result set. The value returned depends on whether
1470 * or not this <code>ResultSet</code> object can detect deletions.
1471 * <p>
1472 * <strong>Note:</strong> Support for the <code>rowDeleted</code> method is optional with a result set
1473 * concurrency of <code>CONCUR_READ_ONLY</code>
1474 * @return <code>true</code> if the current row is detected to
1475 * have been deleted by the owner or another; <code>false</code> otherwise
1476 * @exception SQLException if a database access error occurs
1477 * or this method is called on a closed result set
1478 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1479 * this method
1480 *
1481 * @see DatabaseMetaData#deletesAreDetected
1482 * @since 1.2
1483 */
1484 boolean rowDeleted() throws SQLException;
1485
1486 /**
1487 * Updates the designated column with a <code>null</code> value.
1488 *
1489 * The updater methods are used to update column values in the
1490 * current row or the insert row. The updater methods do not
1491 * update the underlying database; instead the <code>updateRow</code>
1492 * or <code>insertRow</code> methods are called to update the database.
1493 *
1494 * @param columnIndex the first column is 1, the second is 2, ...
1495 * @exception SQLException if the columnIndex is not valid;
1496 * if a database access error occurs;
1497 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1498 * or this method is called on a closed result set
1499 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1500 * this method
1501 * @since 1.2
1502 */
1503 void updateNull(int columnIndex) throws SQLException;
1504
1505 /**
1506 * Updates the designated column with a <code>boolean</code> value.
1507 * The updater methods are used to update column values in the
1508 * current row or the insert row. The updater methods do not
1509 * update the underlying database; instead the <code>updateRow</code> or
1510 * <code>insertRow</code> methods are called to update the database.
1511 *
1512 * @param columnIndex the first column is 1, the second is 2, ...
1513 * @param x the new column value
1514 * @exception SQLException if the columnIndex is not valid;
1515 * if a database access error occurs;
1516 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1517 * or this method is called on a closed result set
1518 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1519 * this method
1520 * @since 1.2
1521 */
1522 void updateBoolean(int columnIndex, boolean x) throws SQLException;
1523
1524 /**
1525 * Updates the designated column with a <code>byte</code> value.
1526 * The updater methods are used to update column values in the
1527 * current row or the insert row. The updater methods do not
1528 * update the underlying database; instead the <code>updateRow</code> or
1529 * <code>insertRow</code> methods are called to update the database.
1530 *
1531 *
1532 * @param columnIndex the first column is 1, the second is 2, ...
1533 * @param x the new column value
1534 * @exception SQLException if the columnIndex is not valid;
1535 * if a database access error occurs;
1536 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1537 * or this method is called on a closed result set
1538 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1539 * this method
1540 * @since 1.2
1541 */
1542 void updateByte(int columnIndex, byte x) throws SQLException;
1543
1544 /**
1545 * Updates the designated column with a <code>short</code> value.
1546 * The updater methods are used to update column values in the
1547 * current row or the insert row. The updater methods do not
1548 * update the underlying database; instead the <code>updateRow</code> or
1549 * <code>insertRow</code> methods are called to update the database.
1550 *
1551 * @param columnIndex the first column is 1, the second is 2, ...
1552 * @param x the new column value
1553 * @exception SQLException if the columnIndex is not valid;
1554 * if a database access error occurs;
1555 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1556 * or this method is called on a closed result set
1557 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1558 * this method
1559 * @since 1.2
1560 */
1561 void updateShort(int columnIndex, short x) throws SQLException;
1562
1563 /**
1564 * Updates the designated column with an <code>int</code> value.
1565 * The updater methods are used to update column values in the
1566 * current row or the insert row. The updater methods do not
1567 * update the underlying database; instead the <code>updateRow</code> or
1568 * <code>insertRow</code> methods are called to update the database.
1569 *
1570 * @param columnIndex the first column is 1, the second is 2, ...
1571 * @param x the new column value
1572 * @exception SQLException if the columnIndex is not valid;
1573 * if a database access error occurs;
1574 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1575 * or this method is called on a closed result set
1576 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1577 * this method
1578 * @since 1.2
1579 */
1580 void updateInt(int columnIndex, int x) throws SQLException;
1581
1582 /**
1583 * Updates the designated column with a <code>long</code> value.
1584 * The updater methods are used to update column values in the
1585 * current row or the insert row. The updater methods do not
1586 * update the underlying database; instead the <code>updateRow</code> or
1587 * <code>insertRow</code> methods are called to update the database.
1588 *
1589 * @param columnIndex the first column is 1, the second is 2, ...
1590 * @param x the new column value
1591 * @exception SQLException if the columnIndex is not valid;
1592 * if a database access error occurs;
1593 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1594 * or this method is called on a closed result set
1595 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1596 * this method
1597 * @since 1.2
1598 */
1599 void updateLong(int columnIndex, long x) throws SQLException;
1600
1601 /**
1602 * Updates the designated column with a <code>float</code> value.
1603 * The updater methods are used to update column values in the
1604 * current row or the insert row. The updater methods do not
1605 * update the underlying database; instead the <code>updateRow</code> or
1606 * <code>insertRow</code> methods are called to update the database.
1607 *
1608 * @param columnIndex the first column is 1, the second is 2, ...
1609 * @param x the new column value
1610 * @exception SQLException if the columnIndex is not valid;
1611 * if a database access error occurs;
1612 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1613 * or this method is called on a closed result set
1614 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1615 * this method
1616 * @since 1.2
1617 */
1618 void updateFloat(int columnIndex, float x) throws SQLException;
1619
1620 /**
1621 * Updates the designated column with a <code>double</code> value.
1622 * The updater methods are used to update column values in the
1623 * current row or the insert row. The updater methods do not
1624 * update the underlying database; instead the <code>updateRow</code> or
1625 * <code>insertRow</code> methods are called to update the database.
1626 *
1627 * @param columnIndex the first column is 1, the second is 2, ...
1628 * @param x the new column value
1629 * @exception SQLException if the columnIndex is not valid;
1630 * if a database access error occurs;
1631 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1632 * or this method is called on a closed result set
1633 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1634 * this method
1635 * @since 1.2
1636 */
1637 void updateDouble(int columnIndex, double x) throws SQLException;
1638
1639 /**
1640 * Updates the designated column with a <code>java.math.BigDecimal</code>
1641 * value.
1642 * The updater methods are used to update column values in the
1643 * current row or the insert row. The updater methods do not
1644 * update the underlying database; instead the <code>updateRow</code> or
1645 * <code>insertRow</code> methods are called to update the database.
1646 *
1647 * @param columnIndex the first column is 1, the second is 2, ...
1648 * @param x the new column value
1649 * @exception SQLException if the columnIndex is not valid;
1650 * if a database access error occurs;
1651 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1652 * or this method is called on a closed result set
1653 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1654 * this method
1655 * @since 1.2
1656 */
1657 void updateBigDecimal(int columnIndex, BigDecimal x) throws SQLException;
1658
1659 /**
1660 * Updates the designated column with a <code>String</code> value.
1661 * The updater methods are used to update column values in the
1662 * current row or the insert row. The updater methods do not
1663 * update the underlying database; instead the <code>updateRow</code> or
1664 * <code>insertRow</code> methods are called to update the database.
1665 *
1666 * @param columnIndex the first column is 1, the second is 2, ...
1667 * @param x the new column value
1668 * @exception SQLException if the columnIndex is not valid;
1669 * if a database access error occurs;
1670 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1671 * or this method is called on a closed result set
1672 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1673 * this method
1674 * @since 1.2
1675 */
1676 void updateString(int columnIndex, String x) throws SQLException;
1677
1678 /**
1679 * Updates the designated column with a <code>byte</code> array value.
1680 * The updater methods are used to update column values in the
1681 * current row or the insert row. The updater methods do not
1682 * update the underlying database; instead the <code>updateRow</code> or
1683 * <code>insertRow</code> methods are called to update the database.
1684 *
1685 * @param columnIndex the first column is 1, the second is 2, ...
1686 * @param x the new column value
1687 * @exception SQLException if the columnIndex is not valid;
1688 * if a database access error occurs;
1689 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1690 * or this method is called on a closed result set
1691 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1692 * this method
1693 * @since 1.2
1694 */
1695 void updateBytes(int columnIndex, byte x[]) throws SQLException;
1696
1697 /**
1698 * Updates the designated column with a <code>java.sql.Date</code> value.
1699 * The updater methods are used to update column values in the
1700 * current row or the insert row. The updater methods do not
1701 * update the underlying database; instead the <code>updateRow</code> or
1702 * <code>insertRow</code> methods are called to update the database.
1703 *
1704 * @param columnIndex the first column is 1, the second is 2, ...
1705 * @param x the new column value
1706 * @exception SQLException if the columnIndex is not valid;
1707 * if a database access error occurs;
1708 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1709 * or this method is called on a closed result set
1710 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1711 * this method
1712 * @since 1.2
1713 */
1714 void updateDate(int columnIndex, java.sql.Date x) throws SQLException;
1715
1716 /**
1717 * Updates the designated column with a <code>java.sql.Time</code> value.
1718 * The updater methods are used to update column values in the
1719 * current row or the insert row. The updater methods do not
1720 * update the underlying database; instead the <code>updateRow</code> or
1721 * <code>insertRow</code> methods are called to update the database.
1722 *
1723 * @param columnIndex the first column is 1, the second is 2, ...
1724 * @param x the new column value
1725 * @exception SQLException if the columnIndex is not valid;
1726 * if a database access error occurs;
1727 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1728 * or this method is called on a closed result set
1729 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1730 * this method
1731 * @since 1.2
1732 */
1733 void updateTime(int columnIndex, java.sql.Time x) throws SQLException;
1734
1735 /**
1736 * Updates the designated column with a <code>java.sql.Timestamp</code>
1737 * value.
1738 * The updater methods are used to update column values in the
1739 * current row or the insert row. The updater methods do not
1740 * update the underlying database; instead the <code>updateRow</code> or
1741 * <code>insertRow</code> methods are called to update the database.
1742 *
1743 * @param columnIndex the first column is 1, the second is 2, ...
1744 * @param x the new column value
1745 * @exception SQLException if the columnIndex is not valid;
1746 * if a database access error occurs;
1747 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1748 * or this method is called on a closed result set
1749 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1750 * this method
1751 * @since 1.2
1752 */
1753 void updateTimestamp(int columnIndex, java.sql.Timestamp x)
1754 throws SQLException;
1755
1756 /**
1757 * Updates the designated column with an ascii stream value, which will have
1758 * the specified number of bytes.
1759 * The updater methods are used to update column values in the
1760 * current row or the insert row. The updater methods do not
1761 * update the underlying database; instead the <code>updateRow</code> or
1762 * <code>insertRow</code> methods are called to update the database.
1763 *
1764 * @param columnIndex the first column is 1, the second is 2, ...
1765 * @param x the new column value
1766 * @param length the length of the stream
1767 * @exception SQLException if the columnIndex is not valid;
1768 * if a database access error occurs;
1769 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1770 * or this method is called on a closed result set
1771 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1772 * this method
1773 * @since 1.2
1774 */
1775 void updateAsciiStream(int columnIndex,
1776 java.io.InputStream x,
1777 int length) throws SQLException;
1778
1779 /**
1780 * Updates the designated column with a binary stream value, which will have
1781 * the specified number of bytes.
1782 * The updater methods are used to update column values in the
1783 * current row or the insert row. The updater methods do not
1784 * update the underlying database; instead the <code>updateRow</code> or
1785 * <code>insertRow</code> methods are called to update the database.
1786 *
1787 * @param columnIndex the first column is 1, the second is 2, ...
1788 * @param x the new column value
1789 * @param length the length of the stream
1790 * @exception SQLException if the columnIndex is not valid;
1791 * if a database access error occurs;
1792 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1793 * or this method is called on a closed result set
1794 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1795 * this method
1796 * @since 1.2
1797 */
1798 void updateBinaryStream(int columnIndex,
1799 java.io.InputStream x,
1800 int length) throws SQLException;
1801
1802 /**
1803 * Updates the designated column with a character stream value, which will have
1804 * the specified number of bytes.
1805 * The updater methods are used to update column values in the
1806 * current row or the insert row. The updater methods do not
1807 * update the underlying database; instead the <code>updateRow</code> or
1808 * <code>insertRow</code> methods are called to update the database.
1809 *
1810 * @param columnIndex the first column is 1, the second is 2, ...
1811 * @param x the new column value
1812 * @param length the length of the stream
1813 * @exception SQLException if the columnIndex is not valid;
1814 * if a database access error occurs;
1815 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1816 * or this method is called on a closed result set
1817 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1818 * this method
1819 * @since 1.2
1820 */
1821 void updateCharacterStream(int columnIndex,
1822 java.io.Reader x,
1823 int length) throws SQLException;
1824
1825 /**
1826 * Updates the designated column with an <code>Object</code> value.
1827 * The updater methods are used to update column values in the
1828 * current row or the insert row. The updater methods do not
1829 * update the underlying database; instead the <code>updateRow</code> or
1830 * <code>insertRow</code> methods are called to update the database.
1831 *<p>
1832 * If the second argument is an <code>InputStream</code> then the stream must contain
1833 * the number of bytes specified by scaleOrLength. If the second argument is a
1834 * <code>Reader</code> then the reader must contain the number of characters specified
1835 * by scaleOrLength. If these conditions are not true the driver will generate a
1836 * <code>SQLException</code> when the statement is executed.
1837 *
1838 * @param columnIndex the first column is 1, the second is 2, ...
1839 * @param x the new column value
1840 * @param scaleOrLength for an object of <code>java.math.BigDecimal</code> ,
1841 * this is the number of digits after the decimal point. For
1842 * Java Object types <code>InputStream</code> and <code>Reader</code>,
1843 * this is the length
1844 * of the data in the stream or reader. For all other types,
1845 * this value will be ignored.
1846 * @exception SQLException if the columnIndex is not valid;
1847 * if a database access error occurs;
1848 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1849 * or this method is called on a closed result set
1850 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1851 * this method
1852 * @since 1.2
1853 */
1854 void updateObject(int columnIndex, Object x, int scaleOrLength)
1855 throws SQLException;
1856
1857 /**
1858 * Updates the designated column with an <code>Object</code> value.
1859 * The updater methods are used to update column values in the
1860 * current row or the insert row. The updater methods do not
1861 * update the underlying database; instead the <code>updateRow</code> or
1862 * <code>insertRow</code> methods are called to update the database.
1863 *
1864 * @param columnIndex the first column is 1, the second is 2, ...
1865 * @param x the new column value
1866 * @exception SQLException if the columnIndex is not valid;
1867 * if a database access error occurs;
1868 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1869 * or this method is called on a closed result set
1870 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1871 * this method
1872 * @since 1.2
1873 */
1874 void updateObject(int columnIndex, Object x) throws SQLException;
1875
1876 /**
1877 * Updates the designated column with a <code>null</code> value.
1878 * The updater methods are used to update column values in the
1879 * current row or the insert row. The updater methods do not
1880 * update the underlying database; instead the <code>updateRow</code> or
1881 * <code>insertRow</code> methods are called to update the database.
1882 *
1883 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
1884 * @exception SQLException if the columnLabel is not valid;
1885 * if a database access error occurs;
1886 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1887 * or this method is called on a closed result set
1888 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1889 * this method
1890 * @since 1.2
1891 */
1892 void updateNull(String columnLabel) throws SQLException;
1893
1894 /**
1895 * Updates the designated column with a <code>boolean</code> value.
1896 * The updater methods are used to update column values in the
1897 * current row or the insert row. The updater methods do not
1898 * update the underlying database; instead the <code>updateRow</code> or
1899 * <code>insertRow</code> methods are called to update the database.
1900 *
1901 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
1902 * @param x the new column value
1903 * @exception SQLException if the columnLabel is not valid;
1904 * if a database access error occurs;
1905 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1906 * or this method is called on a closed result set
1907 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1908 * this method
1909 * @since 1.2
1910 */
1911 void updateBoolean(String columnLabel, boolean x) throws SQLException;
1912
1913 /**
1914 * Updates the designated column with a <code>byte</code> value.
1915 * The updater methods are used to update column values in the
1916 * current row or the insert row. The updater methods do not
1917 * update the underlying database; instead the <code>updateRow</code> or
1918 * <code>insertRow</code> methods are called to update the database.
1919 *
1920 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
1921 * @param x the new column value
1922 * @exception SQLException if the columnLabel is not valid;
1923 * if a database access error occurs;
1924 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1925 * or this method is called on a closed result set
1926 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1927 * this method
1928 * @since 1.2
1929 */
1930 void updateByte(String columnLabel, byte x) throws SQLException;
1931
1932 /**
1933 * Updates the designated column with a <code>short</code> value.
1934 * The updater methods are used to update column values in the
1935 * current row or the insert row. The updater methods do not
1936 * update the underlying database; instead the <code>updateRow</code> or
1937 * <code>insertRow</code> methods are called to update the database.
1938 *
1939 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
1940 * @param x the new column value
1941 * @exception SQLException if the columnLabel is not valid;
1942 * if a database access error occurs;
1943 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1944 * or this method is called on a closed result set
1945 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1946 * this method
1947 * @since 1.2
1948 */
1949 void updateShort(String columnLabel, short x) throws SQLException;
1950
1951 /**
1952 * Updates the designated column with an <code>int</code> value.
1953 * The updater methods are used to update column values in the
1954 * current row or the insert row. The updater methods do not
1955 * update the underlying database; instead the <code>updateRow</code> or
1956 * <code>insertRow</code> methods are called to update the database.
1957 *
1958 * @param columnLabel the label for the column specified with the SQL AS clause. If the SQL AS clause was not specified, then the label is the name of the column
1959 * @param x the new column value
1960 * @exception SQLException if the columnLabel is not valid;
1961 * if a database access error occurs;
1962 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1963 * or this method is called on a closed result set
1964 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1965
Save This Page