1 /*
2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * 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>ResultSetMetaData</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, AutoCloseable {
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 Use {@code getBigDecimal(int columnIndex)}
360 * or {@code getBigDecimal(String columnLabel)}
361 */
362 @Deprecated
363 BigDecimal getBigDecimal(int columnIndex, int scale) throws SQLException;
364
365 /**
366 * Retrieves the value of the designated column in the current row
367 * of this <code>ResultSet</code> object as
368 * a <code>byte</code> array in the Java programming language.
369 * The bytes represent the raw values returned by the driver.
370 *
371 * @param columnIndex the first column is 1, the second is 2, ...
372 * @return the column value; if the value is SQL <code>NULL</code>, the
373 * value returned is <code>null</code>
374 * @exception SQLException if the columnIndex is not valid;
375 * if a database access error occurs or this method is
376 * called on a closed result set
377 */
378 byte[] getBytes(int columnIndex) throws SQLException;
379
380 /**
381 * Retrieves the value of the designated column in the current row
382 * of this <code>ResultSet</code> object as
383 * a <code>java.sql.Date</code> object in the Java programming language.
384 *
385 * @param columnIndex the first column is 1, the second is 2, ...
386 * @return the column value; if the value is SQL <code>NULL</code>, the
387 * value returned is <code>null</code>
388 * @exception SQLException if the columnIndex is not valid;
389 * if a database access error occurs or this method is
390 * called on a closed result set
391 */
392 java.sql.Date getDate(int columnIndex) throws SQLException;
393
394 /**
395 * Retrieves the value of the designated column in the current row
396 * of this <code>ResultSet</code> object as
397 * a <code>java.sql.Time</code> object in the Java programming language.
398 *
399 * @param columnIndex the first column is 1, the second is 2, ...
400 * @return the column value; if the value is SQL <code>NULL</code>, the
401 * value returned is <code>null</code>
402 * @exception SQLException if the columnIndex is not valid;
403 * if a database access error occurs or this method is
404 * called on a closed result set
405 */
406 java.sql.Time getTime(int columnIndex) throws SQLException;
407
408 /**
409 * Retrieves the value of the designated column in the current row
410 * of this <code>ResultSet</code> object as
411 * a <code>java.sql.Timestamp</code> object in the Java programming language.
412 *
413 * @param columnIndex the first column is 1, the second is 2, ...
414 * @return the column value; if the value is SQL <code>NULL</code>, the
415 * value returned is <code>null</code>
416 * @exception SQLException if the columnIndex is not valid;
417 * if a database access error occurs or this method is
418 * called on a closed result set
419 */
420 java.sql.Timestamp getTimestamp(int columnIndex) throws SQLException;
421
422 /**
423 * Retrieves the value of the designated column in the current row
424 * of this <code>ResultSet</code> object as
425 * a stream of ASCII characters. The value can then be read in chunks from the
426 * stream. This method is particularly
427 * suitable for retrieving large <code>LONGVARCHAR</code> values.
428 * The JDBC driver will
429 * do any necessary conversion from the database format into ASCII.
430 *
431 * <P><B>Note:</B> All the data in the returned stream must be
432 * read prior to getting the value of any other column. The next
433 * call to a getter method implicitly closes the stream. Also, a
434 * stream may return <code>0</code> when the method
435 * <code>InputStream.available</code>
436 * is called whether there is data available or not.
437 *
438 * @param columnIndex the first column is 1, the second is 2, ...
439 * @return a Java input stream that delivers the database column value
440 * as a stream of one-byte ASCII characters;
441 * if the value is SQL <code>NULL</code>, the
442 * value returned is <code>null</code>
443 * @exception SQLException if the columnIndex is not valid;
444 * if a database access error occurs or this method is
445 * called on a closed result set
446 */
447 java.io.InputStream getAsciiStream(int columnIndex) throws SQLException;
448
449 /**
450 * Retrieves the value of the designated column in the current row
451 * of this <code>ResultSet</code> object as
452 * as a stream of two-byte 3 characters. The first byte is
453 * the high byte; the second byte is the low byte.
454 *
455 * The value can then be read in chunks from the
456 * stream. This method is particularly
457 * suitable for retrieving large <code>LONGVARCHAR</code>values. The
458 * JDBC driver will do any necessary conversion from the database
459 * format into Unicode.
460 *
461 * <P><B>Note:</B> All the data in the returned stream must be
462 * read prior to getting the value of any other column. The next
463 * call to a getter method implicitly closes the stream.
464 * Also, a stream may return <code>0</code> when the method
465 * <code>InputStream.available</code>
466 * is called, whether there is data available or not.
467 *
468 * @param columnIndex the first column is 1, the second is 2, ...
469 * @return a Java input stream that delivers the database column value
470 * as a stream of two-byte Unicode characters;
471 * if the value is SQL <code>NULL</code>, the value returned is
472 * <code>null</code>
473 *
474 * @exception SQLException if the columnIndex is not valid;
475 * if a database access error occurs or this method is
476 * called on a closed result set
477 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
478 * this method
479 * @deprecated use <code>getCharacterStream</code> in place of
480 * <code>getUnicodeStream</code>
481 */
482 @Deprecated
483 java.io.InputStream getUnicodeStream(int columnIndex) throws SQLException;
484
485 /**
486 * Retrieves the value of the designated column in the current row
487 * of this <code>ResultSet</code> object as a stream of
488 * uninterpreted bytes. The value can then be read in chunks from the
489 * stream. This method is particularly
490 * suitable for retrieving large <code>LONGVARBINARY</code> values.
491 *
492 * <P><B>Note:</B> All the data in the returned stream must be
493 * read prior to getting the value of any other column. The next
494 * call to a getter method implicitly closes the stream. Also, a
495 * stream may return <code>0</code> when the method
496 * <code>InputStream.available</code>
497 * is called whether there is data available or not.
498 *
499 * @param columnIndex the first column is 1, the second is 2, ...
500 * @return a Java input stream that delivers the database column value
501 * as a stream of uninterpreted bytes;
502 * if the value is SQL <code>NULL</code>, the value returned is
503 * <code>null</code>
504 * @exception SQLException if the columnIndex is not valid;
505 * if a database access error occurs or this method is
506 * called on a closed result set
507 */
508 java.io.InputStream getBinaryStream(int columnIndex)
509 throws SQLException;
510
511
512 // Methods for accessing results by column label
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>String</code> in the Java programming language.
518 *
519 * @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
520 * @return the column value; if the value is SQL <code>NULL</code>, the
521 * value returned is <code>null</code>
522 * @exception SQLException if the columnLabel is not valid;
523 * if a database access error occurs or this method is
524 * called on a closed result set
525 */
526 String getString(String columnLabel) throws SQLException;
527
528 /**
529 * Retrieves the value of the designated column in the current row
530 * of this <code>ResultSet</code> object as
531 * a <code>boolean</code> in the Java programming language.
532 *
533 * <P>If the designated column has a datatype of CHAR or VARCHAR
534 * and contains a "0" or has a datatype of BIT, TINYINT, SMALLINT, INTEGER or BIGINT
535 * and contains a 0, a value of <code>false</code> is returned. If the designated column has a datatype
536 * of CHAR or VARCHAR
537 * and contains a "1" or has a datatype of BIT, TINYINT, SMALLINT, INTEGER or BIGINT
538 * and contains a 1, a value of <code>true</code> is returned.
539 *
540 * @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
541 * @return the column value; if the value is SQL <code>NULL</code>, the
542 * value returned is <code>false</code>
543 * @exception SQLException if the columnLabel is not valid;
544 * if a database access error occurs or this method is
545 * called on a closed result set
546 */
547 boolean getBoolean(String columnLabel) throws SQLException;
548
549 /**
550 * Retrieves the value of the designated column in the current row
551 * of this <code>ResultSet</code> object as
552 * a <code>byte</code> in the Java programming language.
553 *
554 * @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
555 * @return the column value; if the value is SQL <code>NULL</code>, the
556 * value returned is <code>0</code>
557 * @exception SQLException if the columnLabel is not valid;
558 * if a database access error occurs or this method is
559 * called on a closed result set
560 */
561 byte getByte(String columnLabel) throws SQLException;
562
563 /**
564 * Retrieves the value of the designated column in the current row
565 * of this <code>ResultSet</code> object as
566 * a <code>short</code> in the Java programming language.
567 *
568 * @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
569 * @return the column value; if the value is SQL <code>NULL</code>, the
570 * value returned is <code>0</code>
571 * @exception SQLException if the columnLabel is not valid;
572 * if a database access error occurs or this method is
573 * called on a closed result set
574 */
575 short getShort(String columnLabel) throws SQLException;
576
577 /**
578 * Retrieves the value of the designated column in the current row
579 * of this <code>ResultSet</code> object as
580 * an <code>int</code> in the Java programming language.
581 *
582 * @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
583 * @return the column value; if the value is SQL <code>NULL</code>, the
584 * value returned is <code>0</code>
585 * @exception SQLException if the columnLabel is not valid;
586 * if a database access error occurs or this method is
587 * called on a closed result set
588 */
589 int getInt(String columnLabel) throws SQLException;
590
591 /**
592 * Retrieves the value of the designated column in the current row
593 * of this <code>ResultSet</code> object as
594 * a <code>long</code> in the Java programming language.
595 *
596 * @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
597 * @return the column value; if the value is SQL <code>NULL</code>, the
598 * value returned is <code>0</code>
599 * @exception SQLException if the columnLabel is not valid;
600 * if a database access error occurs or this method is
601 * called on a closed result set
602 */
603 long getLong(String columnLabel) throws SQLException;
604
605 /**
606 * Retrieves the value of the designated column in the current row
607 * of this <code>ResultSet</code> object as
608 * a <code>float</code> in the Java programming language.
609 *
610 * @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
611 * @return the column value; if the value is SQL <code>NULL</code>, the
612 * value returned is <code>0</code>
613 * @exception SQLException if the columnLabel is not valid;
614 * if a database access error occurs or this method is
615 * called on a closed result set
616 */
617 float getFloat(String columnLabel) throws SQLException;
618
619 /**
620 * Retrieves the value of the designated column in the current row
621 * of this <code>ResultSet</code> object as
622 * a <code>double</code> in the Java programming language.
623 *
624 * @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
625 * @return the column value; if the value is SQL <code>NULL</code>, the
626 * value returned is <code>0</code>
627 * @exception SQLException if the columnLabel is not valid;
628 * if a database access error occurs or this method is
629 * called on a closed result set
630 */
631 double getDouble(String columnLabel) throws SQLException;
632
633 /**
634 * Retrieves the value of the designated column in the current row
635 * of this <code>ResultSet</code> object as
636 * a <code>java.math.BigDecimal</code> in the Java programming language.
637 *
638 * @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
639 * @param scale the number of digits to the right of the decimal point
640 * @return the column value; if the value is SQL <code>NULL</code>, the
641 * value returned is <code>null</code>
642 * @exception SQLException if the columnLabel is not valid;
643 * if a database access error occurs or this method is
644 * called on a closed result set
645 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
646 * this method
647 * @deprecated Use {@code getBigDecimal(int columnIndex)}
648 * or {@code getBigDecimal(String columnLabel)}
649 */
650 @Deprecated
651 BigDecimal getBigDecimal(String columnLabel, int scale) throws SQLException;
652
653 /**
654 * Retrieves the value of the designated column in the current row
655 * of this <code>ResultSet</code> object as
656 * a <code>byte</code> array in the Java programming language.
657 * The bytes represent the raw values returned by the driver.
658 *
659 * @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
660 * @return the column value; if the value is SQL <code>NULL</code>, the
661 * value returned is <code>null</code>
662 * @exception SQLException if the columnLabel is not valid;
663 * if a database access error occurs or this method is
664 * called on a closed result set
665 */
666 byte[] getBytes(String columnLabel) throws SQLException;
667
668 /**
669 * Retrieves the value of the designated column in the current row
670 * of this <code>ResultSet</code> object as
671 * a <code>java.sql.Date</code> object in the Java programming language.
672 *
673 * @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
674 * @return the column value; if the value is SQL <code>NULL</code>, the
675 * value returned is <code>null</code>
676 * @exception SQLException if the columnLabel is not valid;
677 * if a database access error occurs or this method is
678 * called on a closed result set
679 */
680 java.sql.Date getDate(String columnLabel) throws SQLException;
681
682 /**
683 * Retrieves the value of the designated column in the current row
684 * of this <code>ResultSet</code> object as
685 * a <code>java.sql.Time</code> object in the Java programming language.
686 *
687 * @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
688 * @return the column value;
689 * if the value is SQL <code>NULL</code>,
690 * the value returned is <code>null</code>
691 * @exception SQLException if the columnLabel is not valid;
692 * if a database access error occurs or this method is
693 * called on a closed result set
694 */
695 java.sql.Time getTime(String columnLabel) throws SQLException;
696
697 /**
698 * Retrieves the value of the designated column in the current row
699 * of this <code>ResultSet</code> object as
700 * a <code>java.sql.Timestamp</code> object in the Java programming language.
701 *
702 * @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
703 * @return the column value; if the value is SQL <code>NULL</code>, the
704 * value returned is <code>null</code>
705 * @exception SQLException if the columnLabel is not valid;
706 * if a database access error occurs or this method is
707 * called on a closed result set
708 */
709 java.sql.Timestamp getTimestamp(String columnLabel) throws SQLException;
710
711 /**
712 * Retrieves the value of the designated column in the current row
713 * of this <code>ResultSet</code> object as a stream of
714 * ASCII characters. The value can then be read in chunks from the
715 * stream. This method is particularly
716 * suitable for retrieving large <code>LONGVARCHAR</code> values.
717 * The JDBC driver will
718 * do any necessary conversion from the database format into ASCII.
719 *
720 * <P><B>Note:</B> All the data in the returned stream must be
721 * read prior to getting the value of any other column. The next
722 * call to a getter method implicitly closes the stream. Also, a
723 * stream may return <code>0</code> when the method <code>available</code>
724 * is called whether there is data available or not.
725 *
726 * @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
727 * @return a Java input stream that delivers the database column value
728 * as a stream of one-byte ASCII characters.
729 * If the value is SQL <code>NULL</code>,
730 * the value returned is <code>null</code>.
731 * @exception SQLException if the columnLabel is not valid;
732 * if a database access error occurs or this method is
733 * called on a closed result set
734 */
735 java.io.InputStream getAsciiStream(String columnLabel) throws SQLException;
736
737 /**
738 * Retrieves the value of the designated column in the current row
739 * of this <code>ResultSet</code> object as a stream of two-byte
740 * Unicode characters. The first byte is the high byte; the second
741 * byte is the low byte.
742 *
743 * The value can then be read in chunks from the
744 * stream. This method is particularly
745 * suitable for retrieving large <code>LONGVARCHAR</code> values.
746 * The JDBC technology-enabled driver will
747 * do any necessary conversion from the database format into Unicode.
748 *
749 * <P><B>Note:</B> All the data in the returned stream must be
750 * read prior to getting the value of any other column. The next
751 * call to a getter method implicitly closes the stream.
752 * Also, a stream may return <code>0</code> when the method
753 * <code>InputStream.available</code> is called, whether there
754 * is data available or not.
755 *
756 * @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
757 * @return a Java input stream that delivers the database column value
758 * as a stream of two-byte Unicode characters.
759 * If the value is SQL <code>NULL</code>, the value returned
760 * is <code>null</code>.
761 * @exception SQLException if the columnLabel is not valid;
762 * if a database access error occurs or this method is
763 * called on a closed result set
764 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
765 * this method
766 * @deprecated use <code>getCharacterStream</code> instead
767 */
768 @Deprecated
769 java.io.InputStream getUnicodeStream(String columnLabel) throws SQLException;
770
771 /**
772 * Retrieves the value of the designated column in the current row
773 * of this <code>ResultSet</code> object as a stream of uninterpreted
774 * <code>byte</code>s.
775 * The value can then be read in chunks from the
776 * stream. This method is particularly
777 * suitable for retrieving large <code>LONGVARBINARY</code>
778 * values.
779 *
780 * <P><B>Note:</B> All the data in the returned stream must be
781 * read prior to getting the value of any other column. The next
782 * call to a getter method implicitly closes the stream. Also, a
783 * stream may return <code>0</code> when the method <code>available</code>
784 * is called whether there is data available or not.
785 *
786 * @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
787 * @return a Java input stream that delivers the database column value
788 * as a stream of uninterpreted bytes;
789 * if the value is SQL <code>NULL</code>, the result is <code>null</code>
790 * @exception SQLException if the columnLabel is not valid;
791 * if a database access error occurs or this method is
792 * called on a closed result set
793 */
794 java.io.InputStream getBinaryStream(String columnLabel)
795 throws SQLException;
796
797
798 // Advanced features:
799
800 /**
801 * Retrieves the first warning reported by calls on this
802 * <code>ResultSet</code> object.
803 * Subsequent warnings on this <code>ResultSet</code> object
804 * will be chained to the <code>SQLWarning</code> object that
805 * this method returns.
806 *
807 * <P>The warning chain is automatically cleared each time a new
808 * row is read. This method may not be called on a <code>ResultSet</code>
809 * object that has been closed; doing so will cause an
810 * <code>SQLException</code> to be thrown.
811 * <P>
812 * <B>Note:</B> This warning chain only covers warnings caused
813 * by <code>ResultSet</code> methods. Any warning caused by
814 * <code>Statement</code> methods
815 * (such as reading OUT parameters) will be chained on the
816 * <code>Statement</code> object.
817 *
818 * @return the first <code>SQLWarning</code> object reported or
819 * <code>null</code> if there are none
820 * @exception SQLException if a database access error occurs or this method is
821 * called on a closed result set
822 */
823 SQLWarning getWarnings() throws SQLException;
824
825 /**
826 * Clears all warnings reported on this <code>ResultSet</code> object.
827 * After this method is called, the method <code>getWarnings</code>
828 * returns <code>null</code> until a new warning is
829 * reported for this <code>ResultSet</code> object.
830 *
831 * @exception SQLException if a database access error occurs or this method is
832 * called on a closed result set
833 */
834 void clearWarnings() throws SQLException;
835
836 /**
837 * Retrieves the name of the SQL cursor used by this <code>ResultSet</code>
838 * object.
839 *
840 * <P>In SQL, a result table is retrieved through a cursor that is
841 * named. The current row of a result set can be updated or deleted
842 * using a positioned update/delete statement that references the
843 * cursor name. To insure that the cursor has the proper isolation
844 * level to support update, the cursor's <code>SELECT</code> statement
845 * should be of the form <code>SELECT FOR UPDATE</code>. If
846 * <code>FOR UPDATE</code> is omitted, the positioned updates may fail.
847 *
848 * <P>The JDBC API supports this SQL feature by providing the name of the
849 * SQL cursor used by a <code>ResultSet</code> object.
850 * The current row of a <code>ResultSet</code> object
851 * is also the current row of this SQL cursor.
852 *
853 * @return the SQL name for this <code>ResultSet</code> object's cursor
854 * @exception SQLException if a database access error occurs or this method is called on a closed result set
855 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
856 * this method
857 */
858 String getCursorName() throws SQLException;
859
860 /**
861 * Retrieves the number, types and properties of
862 * this <code>ResultSet</code> object's columns.
863 *
864 * @return the description of this <code>ResultSet</code> object's columns
865 * @exception SQLException if a database access error occurs or this method is
866 * called on a closed result set
867 */
868 ResultSetMetaData getMetaData() throws SQLException;
869
870 /**
871 * <p>Gets the value of the designated column in the current row
872 * of this <code>ResultSet</code> object as
873 * an <code>Object</code> in the Java programming language.
874 *
875 * <p>This method will return the value of the given column as a
876 * Java object. The type of the Java object will be the default
877 * Java object type corresponding to the column's SQL type,
878 * following the mapping for built-in types specified in the JDBC
879 * specification. If the value is an SQL <code>NULL</code>,
880 * the driver returns a Java <code>null</code>.
881 *
882 * <p>This method may also be used to read database-specific
883 * abstract data types.
884 *
885 * In the JDBC 2.0 API, the behavior of method
886 * <code>getObject</code> is extended to materialize
887 * data of SQL user-defined types.
888 * <p>
889 * If <code>Connection.getTypeMap</code> does not throw a
890 * <code>SQLFeatureNotSupportedException</code>,
891 * then when a column contains a structured or distinct value,
892 * the behavior of this method is as
893 * if it were a call to: <code>getObject(columnIndex,
894 * this.getStatement().getConnection().getTypeMap())</code>.
895 *
896 * If <code>Connection.getTypeMap</code> does throw a
897 * <code>SQLFeatureNotSupportedException</code>,
898 * then structured values are not supported, and distinct values
899 * are mapped to the default Java class as determined by the
900 * underlying SQL type of the DISTINCT type.
901 *
902 * @param columnIndex the first column is 1, the second is 2, ...
903 * @return a <code>java.lang.Object</code> holding the column value
904 * @exception SQLException if the columnIndex is not valid;
905 * if a database access error occurs or this method is
906 * called on a closed result set
907 */
908 Object getObject(int columnIndex) throws SQLException;
909
910 /**
911 * <p>Gets the value of the designated column in the current row
912 * of this <code>ResultSet</code> object as
913 * an <code>Object</code> in the Java programming language.
914 *
915 * <p>This method will return the value of the given column as a
916 * Java object. The type of the Java object will be the default
917 * Java object type corresponding to the column's SQL type,
918 * following the mapping for built-in types specified in the JDBC
919 * specification. If the value is an SQL <code>NULL</code>,
920 * the driver returns a Java <code>null</code>.
921 * <P>
922 * This method may also be used to read database-specific
923 * abstract data types.
924 * <P>
925 * In the JDBC 2.0 API, the behavior of the method
926 * <code>getObject</code> is extended to materialize
927 * data of SQL user-defined types. When a column contains
928 * a structured or distinct value, the behavior of this method is as
929 * if it were a call to: <code>getObject(columnIndex,
930 * this.getStatement().getConnection().getTypeMap())</code>.
931 *
932 * @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
933 * @return a <code>java.lang.Object</code> holding the column value
934 * @exception SQLException if the columnLabel is not valid;
935 * if a database access error occurs or this method is
936 * called on a closed result set
937 */
938 Object getObject(String columnLabel) throws SQLException;
939
940 //----------------------------------------------------------------
941
942 /**
943 * Maps the given <code>ResultSet</code> column label to its
944 * <code>ResultSet</code> column index.
945 *
946 * @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
947 * @return the column index of the given column name
948 * @exception SQLException if the <code>ResultSet</code> object
949 * does not contain a column labeled <code>columnLabel</code>, a database access error occurs
950 * or this method is called on a closed result set
951 */
952 int findColumn(String columnLabel) throws SQLException;
953
954
955 //--------------------------JDBC 2.0-----------------------------------
956
957 //---------------------------------------------------------------------
958 // Getters and Setters
959 //---------------------------------------------------------------------
960
961 /**
962 * Retrieves the value of the designated column in the current row
963 * of this <code>ResultSet</code> object as a
964 * <code>java.io.Reader</code> object.
965 * @return a <code>java.io.Reader</code> object that contains the column
966 * value; if the value is SQL <code>NULL</code>, the value returned is
967 * <code>null</code> in the Java programming language.
968 * @param columnIndex the first column is 1, the second is 2, ...
969 * @exception SQLException if the columnIndex is not valid;
970 * if a database access error occurs or this method is
971 * called on a closed result set
972 * @since 1.2
973 */
974 java.io.Reader getCharacterStream(int columnIndex) throws SQLException;
975
976 /**
977 * Retrieves the value of the designated column in the current row
978 * of this <code>ResultSet</code> object as a
979 * <code>java.io.Reader</code> object.
980 *
981 * @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
982 * @return a <code>java.io.Reader</code> object that contains the column
983 * value; if the value is SQL <code>NULL</code>, the value returned is
984 * <code>null</code> in the Java programming language
985 * @exception SQLException if the columnLabel is not valid;
986 * if a database access error occurs or this method is
987 * called on a closed result set
988 * @since 1.2
989 */
990 java.io.Reader getCharacterStream(String columnLabel) throws SQLException;
991
992 /**
993 * Retrieves the value of the designated column in the current row
994 * of this <code>ResultSet</code> object as a
995 * <code>java.math.BigDecimal</code> with full precision.
996 *
997 * @param columnIndex the first column is 1, the second is 2, ...
998 * @return the column value (full precision);
999 * if the value is SQL <code>NULL</code>, the value returned is
1000 * <code>null</code> in the Java programming language.
1001 * @exception SQLException if the columnIndex is not valid;
1002 * if a database access error occurs or this method is
1003 * called on a closed result set
1004 * @since 1.2
1005 */
1006 BigDecimal getBigDecimal(int columnIndex) throws SQLException;
1007
1008 /**
1009 * Retrieves the value of the designated column in the current row
1010 * of this <code>ResultSet</code> object as a
1011 * <code>java.math.BigDecimal</code> with full precision.
1012 *
1013 * @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
1014 * @return the column value (full precision);
1015 * if the value is SQL <code>NULL</code>, the value returned is
1016 * <code>null</code> in the Java programming language.
1017 * @exception SQLException if the columnLabel is not valid;
1018 * if a database access error occurs or this method is
1019 * called on a closed result set
1020 * @since 1.2
1021 *
1022 */
1023 BigDecimal getBigDecimal(String columnLabel) throws SQLException;
1024
1025 //---------------------------------------------------------------------
1026 // Traversal/Positioning
1027 //---------------------------------------------------------------------
1028
1029 /**
1030 * Retrieves whether the cursor is before the first row in
1031 * this <code>ResultSet</code> object.
1032 * <p>
1033 * <strong>Note:</strong>Support for the <code>isBeforeFirst</code> method
1034 * is optional for <code>ResultSet</code>s with a result
1035 * set type of <code>TYPE_FORWARD_ONLY</code>
1036 *
1037 * @return <code>true</code> if the cursor is before the first row;
1038 * <code>false</code> if the cursor is at any other position or the
1039 * result set contains no rows
1040 * @exception SQLException if a database access error occurs or this method is
1041 * called on a closed result set
1042 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1043 * this method
1044 * @since 1.2
1045 */
1046 boolean isBeforeFirst() throws SQLException;
1047
1048 /**
1049 * Retrieves whether the cursor is after the last row in
1050 * this <code>ResultSet</code> object.
1051 * <p>
1052 * <strong>Note:</strong>Support for the <code>isAfterLast</code> method
1053 * is optional for <code>ResultSet</code>s with a result
1054 * set type of <code>TYPE_FORWARD_ONLY</code>
1055 *
1056 * @return <code>true</code> if the cursor is after the last row;
1057 * <code>false</code> if the cursor is at any other position or the
1058 * result set contains no rows
1059 * @exception SQLException if a database access error occurs or this method is
1060 * called on a closed result set
1061 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1062 * this method
1063 * @since 1.2
1064 */
1065 boolean isAfterLast() throws SQLException;
1066
1067 /**
1068 * Retrieves whether the cursor is on the first row of
1069 * this <code>ResultSet</code> object.
1070 * <p>
1071 * <strong>Note:</strong>Support for the <code>isFirst</code> method
1072 * is optional for <code>ResultSet</code>s with a result
1073 * set type of <code>TYPE_FORWARD_ONLY</code>
1074 *
1075 * @return <code>true</code> if the cursor is on the first row;
1076 * <code>false</code> otherwise
1077 * @exception SQLException if a database access error occurs or this method is
1078 * called on a closed result set
1079 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1080 * this method
1081 * @since 1.2
1082 */
1083 boolean isFirst() throws SQLException;
1084
1085 /**
1086 * Retrieves whether the cursor is on the last row of
1087 * this <code>ResultSet</code> object.
1088 * <strong>Note:</strong> Calling the method <code>isLast</code> may be expensive
1089 * because the JDBC driver
1090 * might need to fetch ahead one row in order to determine
1091 * whether the current row is the last row in the result set.
1092 * <p>
1093 * <strong>Note:</strong> Support for the <code>isLast</code> method
1094 * is optional for <code>ResultSet</code>s with a result
1095 * set type of <code>TYPE_FORWARD_ONLY</code>
1096 * @return <code>true</code> if the cursor is on the last row;
1097 * <code>false</code> otherwise
1098 * @exception SQLException if a database access error occurs or this method is
1099 * called on a closed result set
1100 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1101 * this method
1102 * @since 1.2
1103 */
1104 boolean isLast() throws SQLException;
1105
1106 /**
1107 * Moves the cursor to the front of
1108 * this <code>ResultSet</code> object, just before the
1109 * first row. This method has no effect if the result set contains no rows.
1110 *
1111 * @exception SQLException if a database access error
1112 * occurs; this method is called on a closed result set or the
1113 * result set type is <code>TYPE_FORWARD_ONLY</code>
1114 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1115 * this method
1116 * @since 1.2
1117 */
1118 void beforeFirst() throws SQLException;
1119
1120 /**
1121 * Moves the cursor to the end of
1122 * this <code>ResultSet</code> object, just after the
1123 * last row. This method has no effect if the result set contains no rows.
1124 * @exception SQLException if a database access error
1125 * occurs; this method is called on a closed result set
1126 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1127 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1128 * this method
1129 * @since 1.2
1130 */
1131 void afterLast() throws SQLException;
1132
1133 /**
1134 * Moves the cursor to the first row in
1135 * this <code>ResultSet</code> object.
1136 *
1137 * @return <code>true</code> if the cursor is on a valid row;
1138 * <code>false</code> if there are no rows in the result set
1139 * @exception SQLException if a database access error
1140 * occurs; this method is called on a closed result set
1141 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1142 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1143 * this method
1144 * @since 1.2
1145 */
1146 boolean first() throws SQLException;
1147
1148 /**
1149 * Moves the cursor to the last row in
1150 * this <code>ResultSet</code> object.
1151 *
1152 * @return <code>true</code> if the cursor is on a valid row;
1153 * <code>false</code> if there are no rows in the result set
1154 * @exception SQLException if a database access error
1155 * occurs; this method is called on a closed result set
1156 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1157 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1158 * this method
1159 * @since 1.2
1160 */
1161 boolean last() throws SQLException;
1162
1163 /**
1164 * Retrieves the current row number. The first row is number 1, the
1165 * second number 2, and so on.
1166 * <p>
1167 * <strong>Note:</strong>Support for the <code>getRow</code> method
1168 * is optional for <code>ResultSet</code>s with a result
1169 * set type of <code>TYPE_FORWARD_ONLY</code>
1170 *
1171 * @return the current row number; <code>0</code> if there is no current row
1172 * @exception SQLException if a database access error occurs
1173 * or this method is called on a closed result set
1174 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1175 * this method
1176 * @since 1.2
1177 */
1178 int getRow() throws SQLException;
1179
1180 /**
1181 * Moves the cursor to the given row number in
1182 * this <code>ResultSet</code> object.
1183 *
1184 * <p>If the row number is positive, the cursor moves to
1185 * the given row number with respect to the
1186 * beginning of the result set. The first row is row 1, the second
1187 * is row 2, and so on.
1188 *
1189 * <p>If the given row number is negative, the cursor moves to
1190 * an absolute row position with respect to
1191 * the end of the result set. For example, calling the method
1192 * <code>absolute(-1)</code> positions the
1193 * cursor on the last row; calling the method <code>absolute(-2)</code>
1194 * moves the cursor to the next-to-last row, and so on.
1195 *
1196 * <p>If the row number specified is zero, the cursor is moved to
1197 * before the first row.
1198 *
1199 * <p>An attempt to position the cursor beyond the first/last row in
1200 * the result set leaves the cursor before the first row or after
1201 * the last row.
1202 *
1203 * <p><B>Note:</B> Calling <code>absolute(1)</code> is the same
1204 * as calling <code>first()</code>. Calling <code>absolute(-1)</code>
1205 * is the same as calling <code>last()</code>.
1206 *
1207 * @param row the number of the row to which the cursor should move.
1208 * A value of zero indicates that the cursor will be positioned
1209 * before the first row; a positive number indicates the row number
1210 * counting from the beginning of the result set; a negative number
1211 * indicates the row number counting from the end of the result set
1212 * @return <code>true</code> if the cursor is moved to a position in this
1213 * <code>ResultSet</code> object;
1214 * <code>false</code> if the cursor is before the first row or after the
1215 * last row
1216 * @exception SQLException if a database access error
1217 * occurs; this method is called on a closed result set
1218 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1219 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1220 * this method
1221 * @since 1.2
1222 */
1223 boolean absolute( int row ) throws SQLException;
1224
1225 /**
1226 * Moves the cursor a relative number of rows, either positive or negative.
1227 * Attempting to move beyond the first/last row in the
1228 * result set positions the cursor before/after the
1229 * the first/last row. Calling <code>relative(0)</code> is valid, but does
1230 * not change the cursor position.
1231 *
1232 * <p>Note: Calling the method <code>relative(1)</code>
1233 * is identical to calling the method <code>next()</code> and
1234 * calling the method <code>relative(-1)</code> is identical
1235 * to calling the method <code>previous()</code>.
1236 *
1237 * @param rows an <code>int</code> specifying the number of rows to
1238 * move from the current row; a positive number moves the cursor
1239 * forward; a negative number moves the cursor backward
1240 * @return <code>true</code> if the cursor is on a row;
1241 * <code>false</code> otherwise
1242 * @exception SQLException if a database access error occurs; this method
1243 * is called on a closed result set or the result set type is
1244 * <code>TYPE_FORWARD_ONLY</code>
1245 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1246 * this method
1247 * @since 1.2
1248 */
1249 boolean relative( int rows ) throws SQLException;
1250
1251 /**
1252 * Moves the cursor to the previous row in this
1253 * <code>ResultSet</code> object.
1254 *<p>
1255 * When a call to the <code>previous</code> method returns <code>false</code>,
1256 * the cursor is positioned before the first row. Any invocation of a
1257 * <code>ResultSet</code> method which requires a current row will result in a
1258 * <code>SQLException</code> being thrown.
1259 *<p>
1260 * If an input stream is open for the current row, a call to the method
1261 * <code>previous</code> will implicitly close it. A <code>ResultSet</code>
1262 * object's warning change is cleared when a new row is read.
1263 *<p>
1264 *
1265 * @return <code>true</code> if the cursor is now positioned on a valid row;
1266 * <code>false</code> if the cursor is positioned before the first row
1267 * @exception SQLException if a database access error
1268 * occurs; this method is called on a closed result set
1269 * or the result set type is <code>TYPE_FORWARD_ONLY</code>
1270 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1271 * this method
1272 * @since 1.2
1273 */
1274 boolean previous() throws SQLException;
1275
1276 //---------------------------------------------------------------------
1277 // Properties
1278 //---------------------------------------------------------------------
1279
1280 /**
1281 * The constant indicating that the rows in a result set will be
1282 * processed in a forward direction; first-to-last.
1283 * This constant is used by the method <code>setFetchDirection</code>
1284 * as a hint to the driver, which the driver may ignore.
1285 * @since 1.2
1286 */
1287 int FETCH_FORWARD = 1000;
1288
1289 /**
1290 * The constant indicating that the rows in a result set will be
1291 * processed in a reverse direction; last-to-first.
1292 * This constant is used by the method <code>setFetchDirection</code>
1293 * as a hint to the driver, which the driver may ignore.
1294 * @since 1.2
1295 */
1296 int FETCH_REVERSE = 1001;
1297
1298 /**
1299 * The constant indicating that the order in which rows in a
1300 * result set will be processed is unknown.
1301 * This constant is used by the method <code>setFetchDirection</code>
1302 * as a hint to the driver, which the driver may ignore.
1303 */
1304 int FETCH_UNKNOWN = 1002;
1305
1306 /**
1307 * Gives a hint as to the direction in which the rows in this
1308 * <code>ResultSet</code> object will be processed.
1309 * The initial value is determined by the
1310 * <code>Statement</code> object
1311 * that produced this <code>ResultSet</code> object.
1312 * The fetch direction may be changed at any time.
1313 *
1314 * @param direction an <code>int</code> specifying the suggested
1315 * fetch direction; one of <code>ResultSet.FETCH_FORWARD</code>,
1316 * <code>ResultSet.FETCH_REVERSE</code>, or
1317 * <code>ResultSet.FETCH_UNKNOWN</code>
1318 * @exception SQLException if a database access error occurs; this
1319 * method is called on a closed result set or
1320 * the result set type is <code>TYPE_FORWARD_ONLY</code> and the fetch
1321 * direction is not <code>FETCH_FORWARD</code>
1322 * @since 1.2
1323 * @see Statement#setFetchDirection
1324 * @see #getFetchDirection
1325 */
1326 void setFetchDirection(int direction) throws SQLException;
1327
1328 /**
1329 * Retrieves the fetch direction for this
1330 * <code>ResultSet</code> object.
1331 *
1332 * @return the current fetch direction for this <code>ResultSet</code> object
1333 * @exception SQLException if a database access error occurs
1334 * or this method is called on a closed result set
1335 * @since 1.2
1336 * @see #setFetchDirection
1337 */
1338 int getFetchDirection() throws SQLException;
1339
1340 /**
1341 * Gives the JDBC driver a hint as to the number of rows that should
1342 * be fetched from the database when more rows are needed for this
1343 * <code>ResultSet</code> object.
1344 * If the fetch size specified is zero, the JDBC driver
1345 * ignores the value and is free to make its own best guess as to what
1346 * the fetch size should be. The default value is set by the
1347 * <code>Statement</code> object
1348 * that created the result set. The fetch size may be changed at any time.
1349 *
1350 * @param rows the number of rows to fetch
1351 * @exception SQLException if a database access error occurs; this method
1352 * is called on a closed result set or the
1353 * condition {@code rows >= 0} is not satisfied
1354 * @since 1.2
1355 * @see #getFetchSize
1356 */
1357 void setFetchSize(int rows) throws SQLException;
1358
1359 /**
1360 * Retrieves the fetch size for this
1361 * <code>ResultSet</code> object.
1362 *
1363 * @return the current fetch size for this <code>ResultSet</code> object
1364 * @exception SQLException if a database access error occurs
1365 * or this method is called on a closed result set
1366 * @since 1.2
1367 * @see #setFetchSize
1368 */
1369 int getFetchSize() throws SQLException;
1370
1371 /**
1372 * The constant indicating the type for a <code>ResultSet</code> object
1373 * whose cursor may move only forward.
1374 * @since 1.2
1375 */
1376 int TYPE_FORWARD_ONLY = 1003;
1377
1378 /**
1379 * The constant indicating the type for a <code>ResultSet</code> object
1380 * that is scrollable but generally not sensitive to changes to the data
1381 * that underlies the <code>ResultSet</code>.
1382 * @since 1.2
1383 */
1384 int TYPE_SCROLL_INSENSITIVE = 1004;
1385
1386 /**
1387 * The constant indicating the type for a <code>ResultSet</code> object
1388 * that is scrollable and generally sensitive to changes to the data
1389 * that underlies the <code>ResultSet</code>.
1390 * @since 1.2
1391 */
1392 int TYPE_SCROLL_SENSITIVE = 1005;
1393
1394 /**
1395 * Retrieves the type of this <code>ResultSet</code> object.
1396 * The type is determined by the <code>Statement</code> object
1397 * that created the result set.
1398 *
1399 * @return <code>ResultSet.TYPE_FORWARD_ONLY</code>,
1400 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>,
1401 * or <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
1402 * @exception SQLException if a database access error occurs
1403 * or this method is called on a closed result set
1404 * @since 1.2
1405 */
1406 int getType() throws SQLException;
1407
1408 /**
1409 * The constant indicating the concurrency mode for a
1410 * <code>ResultSet</code> object that may NOT be updated.
1411 * @since 1.2
1412 */
1413 int CONCUR_READ_ONLY = 1007;
1414
1415 /**
1416 * The constant indicating the concurrency mode for a
1417 * <code>ResultSet</code> object that may be updated.
1418 * @since 1.2
1419 */
1420 int CONCUR_UPDATABLE = 1008;
1421
1422 /**
1423 * Retrieves the concurrency mode of this <code>ResultSet</code> object.
1424 * The concurrency used is determined by the
1425 * <code>Statement</code> object that created the result set.
1426 *
1427 * @return the concurrency type, either
1428 * <code>ResultSet.CONCUR_READ_ONLY</code>
1429 * or <code>ResultSet.CONCUR_UPDATABLE</code>
1430 * @exception SQLException if a database access error occurs
1431 * or this method is called on a closed result set
1432 * @since 1.2
1433 */
1434 int getConcurrency() throws SQLException;
1435
1436 //---------------------------------------------------------------------
1437 // Updates
1438 //---------------------------------------------------------------------
1439
1440 /**
1441 * Retrieves whether the current row has been updated. The value returned
1442 * depends on whether or not the result set can detect updates.
1443 * <p>
1444 * <strong>Note:</strong> Support for the <code>rowUpdated</code> method is optional with a result set
1445 * concurrency of <code>CONCUR_READ_ONLY</code>
1446 * @return <code>true</code> if the current row is detected to
1447 * have been visibly updated by the owner or another; <code>false</code> otherwise
1448 * @exception SQLException if a database access error occurs
1449 * or this method is called on a closed result set
1450 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1451 * this method
1452 * @see DatabaseMetaData#updatesAreDetected
1453 * @since 1.2
1454 */
1455 boolean rowUpdated() throws SQLException;
1456
1457 /**
1458 * Retrieves whether the current row has had an insertion.
1459 * The value returned depends on whether or not this
1460 * <code>ResultSet</code> object can detect visible inserts.
1461 * <p>
1462 * <strong>Note:</strong> Support for the <code>rowInserted</code> method is optional with a result set
1463 * concurrency of <code>CONCUR_READ_ONLY</code>
1464 * @return <code>true</code> if the current row is detected to
1465 * have been inserted; <code>false</code> otherwise
1466 * @exception SQLException if a database access error occurs
1467 * or this method is called on a closed result set
1468 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1469 * this method
1470 *
1471 * @see DatabaseMetaData#insertsAreDetected
1472 * @since 1.2
1473 */
1474 boolean rowInserted() throws SQLException;
1475
1476 /**
1477 * Retrieves whether a row has been deleted. A deleted row may leave
1478 * a visible "hole" in a result set. This method can be used to
1479 * detect holes in a result set. The value returned depends on whether
1480 * or not this <code>ResultSet</code> object can detect deletions.
1481 * <p>
1482 * <strong>Note:</strong> Support for the <code>rowDeleted</code> method is optional with a result set
1483 * concurrency of <code>CONCUR_READ_ONLY</code>
1484 * @return <code>true</code> if the current row is detected to
1485 * have been deleted by the owner or another; <code>false</code> otherwise
1486 * @exception SQLException if a database access error occurs
1487 * or this method is called on a closed result set
1488 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1489 * this method
1490 *
1491 * @see DatabaseMetaData#deletesAreDetected
1492 * @since 1.2
1493 */
1494 boolean rowDeleted() throws SQLException;
1495
1496 /**
1497 * Updates the designated column with a <code>null</code> value.
1498 *
1499 * The updater methods are used to update column values in the
1500 * current row or the insert row. The updater methods do not
1501 * update the underlying database; instead the <code>updateRow</code>
1502 * or <code>insertRow</code> methods are called to update the database.
1503 *
1504 * @param columnIndex the first column is 1, the second is 2, ...
1505 * @exception SQLException if the columnIndex is not valid;
1506 * if a database access error occurs;
1507 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1508 * or this method is called on a closed result set
1509 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1510 * this method
1511 * @since 1.2
1512 */
1513 void updateNull(int columnIndex) throws SQLException;
1514
1515 /**
1516 * Updates the designated column with a <code>boolean</code> value.
1517 * The updater methods are used to update column values in the
1518 * current row or the insert row. The updater methods do not
1519 * update the underlying database; instead the <code>updateRow</code> or
1520 * <code>insertRow</code> methods are called to update the database.
1521 *
1522 * @param columnIndex the first column is 1, the second is 2, ...
1523 * @param x the new column value
1524 * @exception SQLException if the columnIndex is not valid;
1525 * if a database access error occurs;
1526 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1527 * or this method is called on a closed result set
1528 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1529 * this method
1530 * @since 1.2
1531 */
1532 void updateBoolean(int columnIndex, boolean x) throws SQLException;
1533
1534 /**
1535 * Updates the designated column with a <code>byte</code> value.
1536 * The updater methods are used to update column values in the
1537 * current row or the insert row. The updater methods do not
1538 * update the underlying database; instead the <code>updateRow</code> or
1539 * <code>insertRow</code> methods are called to update the database.
1540 *
1541 *
1542 * @param columnIndex the first column is 1, the second is 2, ...
1543 * @param x the new column value
1544 * @exception SQLException if the columnIndex is not valid;
1545 * if a database access error occurs;
1546 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1547 * or this method is called on a closed result set
1548 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1549 * this method
1550 * @since 1.2
1551 */
1552 void updateByte(int columnIndex, byte x) throws SQLException;
1553
1554 /**
1555 * Updates the designated column with a <code>short</code> value.
1556 * The updater methods are used to update column values in the
1557 * current row or the insert row. The updater methods do not
1558 * update the underlying database; instead the <code>updateRow</code> or
1559 * <code>insertRow</code> methods are called to update the database.
1560 *
1561 * @param columnIndex the first column is 1, the second is 2, ...
1562 * @param x the new column value
1563 * @exception SQLException if the columnIndex is not valid;
1564 * if a database access error occurs;
1565 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1566 * or this method is called on a closed result set
1567 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1568 * this method
1569 * @since 1.2
1570 */
1571 void updateShort(int columnIndex, short x) throws SQLException;
1572
1573 /**
1574 * Updates the designated column with an <code>int</code> value.
1575 * The updater methods are used to update column values in the
1576 * current row or the insert row. The updater methods do not
1577 * update the underlying database; instead the <code>updateRow</code> or
1578 * <code>insertRow</code> methods are called to update the database.
1579 *
1580 * @param columnIndex the first column is 1, the second is 2, ...
1581 * @param x the new column value
1582 * @exception SQLException if the columnIndex is not valid;
1583 * if a database access error occurs;
1584 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1585 * or this method is called on a closed result set
1586 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1587 * this method
1588 * @since 1.2
1589 */
1590 void updateInt(int columnIndex, int x) throws SQLException;
1591
1592 /**
1593 * Updates the designated column with a <code>long</code> value.
1594 * The updater methods are used to update column values in the
1595 * current row or the insert row. The updater methods do not
1596 * update the underlying database; instead the <code>updateRow</code> or
1597 * <code>insertRow</code> methods are called to update the database.
1598 *
1599 * @param columnIndex the first column is 1, the second is 2, ...
1600 * @param x the new column value
1601 * @exception SQLException if the columnIndex is not valid;
1602 * if a database access error occurs;
1603 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1604 * or this method is called on a closed result set
1605 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1606 * this method
1607 * @since 1.2
1608 */
1609 void updateLong(int columnIndex, long x) throws SQLException;
1610
1611 /**
1612 * Updates the designated column with a <code>float</code> value.
1613 * The updater methods are used to update column values in the
1614 * current row or the insert row. The updater methods do not
1615 * update the underlying database; instead the <code>updateRow</code> or
1616 * <code>insertRow</code> methods are called to update the database.
1617 *
1618 * @param columnIndex the first column is 1, the second is 2, ...
1619 * @param x the new column value
1620 * @exception SQLException if the columnIndex is not valid;
1621 * if a database access error occurs;
1622 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1623 * or this method is called on a closed result set
1624 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1625 * this method
1626 * @since 1.2
1627 */
1628 void updateFloat(int columnIndex, float x) throws SQLException;
1629
1630 /**
1631 * Updates the designated column with a <code>double</code> value.
1632 * The updater methods are used to update column values in the
1633 * current row or the insert row. The updater methods do not
1634 * update the underlying database; instead the <code>updateRow</code> or
1635 * <code>insertRow</code> methods are called to update the database.
1636 *
1637 * @param columnIndex the first column is 1, the second is 2, ...
1638 * @param x the new column value
1639 * @exception SQLException if the columnIndex is not valid;
1640 * if a database access error occurs;
1641 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1642 * or this method is called on a closed result set
1643 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1644 * this method
1645 * @since 1.2
1646 */
1647 void updateDouble(int columnIndex, double x) throws SQLException;
1648
1649 /**
1650 * Updates the designated column with a <code>java.math.BigDecimal</code>
1651 * value.
1652 * The updater methods are used to update column values in the
1653 * current row or the insert row. The updater methods do not
1654 * update the underlying database; instead the <code>updateRow</code> or
1655 * <code>insertRow</code> methods are called to update the database.
1656 *
1657 * @param columnIndex the first column is 1, the second is 2, ...
1658 * @param x the new column value
1659 * @exception SQLException if the columnIndex is not valid;
1660 * if a database access error occurs;
1661 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1662 * or this method is called on a closed result set
1663 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1664 * this method
1665 * @since 1.2
1666 */
1667 void updateBigDecimal(int columnIndex, BigDecimal x) throws SQLException;
1668
1669 /**
1670 * Updates the designated column with a <code>String</code> value.
1671 * The updater methods are used to update column values in the
1672 * current row or the insert row. The updater methods do not
1673 * update the underlying database; instead the <code>updateRow</code> or
1674 * <code>insertRow</code> methods are called to update the database.
1675 *
1676 * @param columnIndex the first column is 1, the second is 2, ...
1677 * @param x the new column value
1678 * @exception SQLException if the columnIndex is not valid;
1679 * if a database access error occurs;
1680 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1681 * or this method is called on a closed result set
1682 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1683 * this method
1684 * @since 1.2
1685 */
1686 void updateString(int columnIndex, String x) throws SQLException;
1687
1688 /**
1689 * Updates the designated column with a <code>byte</code> array value.
1690 * The updater methods are used to update column values in the
1691 * current row or the insert row. The updater methods do not
1692 * update the underlying database; instead the <code>updateRow</code> or
1693 * <code>insertRow</code> methods are called to update the database.
1694 *
1695 * @param columnIndex the first column is 1, the second is 2, ...
1696 * @param x the new column value
1697 * @exception SQLException if the columnIndex is not valid;
1698 * if a database access error occurs;
1699 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1700 * or this method is called on a closed result set
1701 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1702 * this method
1703 * @since 1.2
1704 */
1705 void updateBytes(int columnIndex, byte x[]) throws SQLException;
1706
1707 /**
1708 * Updates the designated column with a <code>java.sql.Date</code> value.
1709 * The updater methods are used to update column values in the
1710 * current row or the insert row. The updater methods do not
1711 * update the underlying database; instead the <code>updateRow</code> or
1712 * <code>insertRow</code> methods are called to update the database.
1713 *
1714 * @param columnIndex the first column is 1, the second is 2, ...
1715 * @param x the new column value
1716 * @exception SQLException if the columnIndex is not valid;
1717 * if a database access error occurs;
1718 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1719 * or this method is called on a closed result set
1720 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1721 * this method
1722 * @since 1.2
1723 */
1724 void updateDate(int columnIndex, java.sql.Date x) throws SQLException;
1725
1726 /**
1727 * Updates the designated column with a <code>java.sql.Time</code> value.
1728 * The updater methods are used to update column values in the
1729 * current row or the insert row. The updater methods do not
1730 * update the underlying database; instead the <code>updateRow</code> or
1731 * <code>insertRow</code> methods are called to update the database.
1732 *
1733 * @param columnIndex the first column is 1, the second is 2, ...
1734 * @param x the new column value
1735 * @exception SQLException if the columnIndex is not valid;
1736 * if a database access error occurs;
1737 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1738 * or this method is called on a closed result set
1739 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1740 * this method
1741 * @since 1.2
1742 */
1743 void updateTime(int columnIndex, java.sql.Time x) throws SQLException;
1744
1745 /**
1746 * Updates the designated column with a <code>java.sql.Timestamp</code>
1747 * value.
1748 * The updater methods are used to update column values in the
1749 * current row or the insert row. The updater methods do not
1750 * update the underlying database; instead the <code>updateRow</code> or
1751 * <code>insertRow</code> methods are called to update the database.
1752 *
1753 * @param columnIndex the first column is 1, the second is 2, ...
1754 * @param x the new column value
1755 * @exception SQLException if the columnIndex is not valid;
1756 * if a database access error occurs;
1757 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1758 * or this method is called on a closed result set
1759 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1760 * this method
1761 * @since 1.2
1762 */
1763 void updateTimestamp(int columnIndex, java.sql.Timestamp x)
1764 throws SQLException;
1765
1766 /**
1767 * Updates the designated column with an ascii stream value, which will have
1768 * the specified number of bytes.
1769 * The updater methods are used to update column values in the
1770 * current row or the insert row. The updater methods do not
1771 * update the underlying database; instead the <code>updateRow</code> or
1772 * <code>insertRow</code> methods are called to update the database.
1773 *
1774 * @param columnIndex the first column is 1, the second is 2, ...
1775 * @param x the new column value
1776 * @param length the length of the stream
1777 * @exception SQLException if the columnIndex is not valid;
1778 * if a database access error occurs;
1779 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1780 * or this method is called on a closed result set
1781 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1782 * this method
1783 * @since 1.2
1784 */
1785 void updateAsciiStream(int columnIndex,
1786 java.io.InputStream x,
1787 int length) throws SQLException;
1788
1789 /**
1790 * Updates the designated column with a binary stream value, which will have
1791 * the specified number of bytes.
1792 * The updater methods are used to update column values in the
1793 * current row or the insert row. The updater methods do not
1794 * update the underlying database; instead the <code>updateRow</code> or
1795 * <code>insertRow</code> methods are called to update the database.
1796 *
1797 * @param columnIndex the first column is 1, the second is 2, ...
1798 * @param x the new column value
1799 * @param length the length of the stream
1800 * @exception SQLException if the columnIndex is not valid;
1801 * if a database access error occurs;
1802 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1803 * or this method is called on a closed result set
1804 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1805 * this method
1806 * @since 1.2
1807 */
1808 void updateBinaryStream(int columnIndex,
1809 java.io.InputStream x,
1810 int length) throws SQLException;
1811
1812 /**
1813 * Updates the designated column with a character stream value, which will have
1814 * the specified number of bytes.
1815 * The updater methods are used to update column values in the
1816 * current row or the insert row. The updater methods do not
1817 * update the underlying database; instead the <code>updateRow</code> or
1818 * <code>insertRow</code> methods are called to update the database.
1819 *
1820 * @param columnIndex the first column is 1, the second is 2, ...
1821 * @param x the new column value
1822 * @param length the length of the stream
1823 * @exception SQLException if the columnIndex is not valid;
1824 * if a database access error occurs;
1825 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1826 * or this method is called on a closed result set
1827 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1828 * this method
1829 * @since 1.2
1830 */
1831 void updateCharacterStream(int columnIndex,
1832 java.io.Reader x,
1833 int length) throws SQLException;
1834
1835 /**
1836 * Updates the designated column with an <code>Object</code> value.
1837 *
1838 * The updater methods are used to update column values in the
1839 * current row or the insert row. The updater methods do not
1840 * update the underlying database; instead the <code>updateRow</code> or
1841 * <code>insertRow</code> methods are called to update the database.
1842 *<p>
1843 * If the second argument is an <code>InputStream</code> then the stream must contain
1844 * the number of bytes specified by scaleOrLength. If the second argument is a
1845 * <code>Reader</code> then the reader must contain the number of characters specified
1846 * by scaleOrLength. If these conditions are not true the driver will generate a
1847 * <code>SQLException</code> when the statement is executed.
1848 *
1849 * @param columnIndex the first column is 1, the second is 2, ...
1850 * @param x the new column value
1851 * @param scaleOrLength for an object of <code>java.math.BigDecimal</code> ,
1852 * this is the number of digits after the decimal point. For
1853 * Java Object types <code>InputStream</code> and <code>Reader</code>,
1854 * this is the length
1855 * of the data in the stream or reader. For all other types,
1856 * this value will be ignored.
1857 * @exception SQLException if the columnIndex is not valid;
1858 * if a database access error occurs;
1859 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1860 * or this method is called on a closed result set
1861 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1862 * this method
1863 * @since 1.2
1864 */
1865 void updateObject(int columnIndex, Object x, int scaleOrLength)
1866 throws SQLException;
1867
1868 /**
1869 * Updates the designated column with an <code>Object</code> value.
1870 *
1871 * The updater methods are used to update column values in the
1872 * current row or the insert row. The updater methods do not
1873 * update the underlying database; instead the <code>updateRow</code> or
1874 * <code>insertRow</code> methods are called to update the database.
1875 *
1876 * @param columnIndex the first column is 1, the second is 2, ...
1877 * @param x the new column value
1878 * @exception SQLException if the columnIndex is not valid;
1879 * if a database access error occurs;
1880 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1881 * or this method is called on a closed result set
1882 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1883 * this method
1884 * @since 1.2
1885 */
1886 void updateObject(int columnIndex, Object x) throws SQLException;
1887
1888 /**
1889 * Updates the designated column with a <code>null</code> value.
1890 * The updater methods are used to update column values in the
1891 * current row or the insert row. The updater methods do not
1892 * update the underlying database; instead the <code>updateRow</code> or
1893 * <code>insertRow</code> methods are called to update the database.
1894 *
1895 * @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
1896 * @exception SQLException if the columnLabel is not valid;
1897 * if a database access error occurs;
1898 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1899 * or this method is called on a closed result set
1900 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1901 * this method
1902 * @since 1.2
1903 */
1904 void updateNull(String columnLabel) throws SQLException;
1905
1906 /**
1907 * Updates the designated column with a <code>boolean</code> value.
1908 * The updater methods are used to update column values in the
1909 * current row or the insert row. The updater methods do not
1910 * update the underlying database; instead the <code>updateRow</code> or
1911 * <code>insertRow</code> methods are called to update the database.
1912 *
1913 * @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
1914 * @param x the new column value
1915 * @exception SQLException if the columnLabel is not valid;
1916 * if a database access error occurs;
1917 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1918 * or this method is called on a closed result set
1919 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1920 * this method
1921 * @since 1.2
1922 */
1923 void updateBoolean(String columnLabel, boolean x) throws SQLException;
1924
1925 /**
1926 * Updates the designated column with a <code>byte</code> value.
1927 * The updater methods are used to update column values in the
1928 * current row or the insert row. The updater methods do not
1929 * update the underlying database; instead the <code>updateRow</code> or
1930 * <code>insertRow</code> methods are called to update the database.
1931 *
1932 * @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
1933 * @param x the new column value
1934 * @exception SQLException if the columnLabel is not valid;
1935 * if a database access error occurs;
1936 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1937 * or this method is called on a closed result set
1938 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1939 * this method
1940 * @since 1.2
1941 */
1942 void updateByte(String columnLabel, byte x) throws SQLException;
1943
1944 /**
1945 * Updates the designated column with a <code>short</code> value.
1946 * The updater methods are used to update column values in the
1947 * current row or the insert row. The updater methods do not
1948 * update the underlying database; instead the <code>updateRow</code> or
1949 * <code>insertRow</code> methods are called to update the database.
1950 *
1951 * @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
1952 * @param x the new column value
1953 * @exception SQLException if the columnLabel is not valid;
1954 * if a database access error occurs;
1955 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1956 * or this method is called on a closed result set
1957 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1958 * this method
1959 * @since 1.2
1960 */
1961 void updateShort(String columnLabel, short x) throws SQLException;
1962
1963 /**
1964 * Updates the designated column with an <code>int</code> value.
1965 * The updater methods are used to update column values in the
1966 * current row or the insert row. The updater methods do not
1967 * update the underlying database; instead the <code>updateRow</code> or
1968 * <code>insertRow</code> methods are called to update the database.
1969 *
1970 * @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
1971 * @param x the new column value
1972 * @exception SQLException if the columnLabel is not valid;
1973 * if a database access error occurs;
1974 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1975 * or this method is called on a closed result set
1976 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1977 * this method
1978 * @since 1.2
1979 */
1980 void updateInt(String columnLabel, int x) throws SQLException;
1981
1982 /**
1983 * Updates the designated column with a <code>long</code> value.
1984 * The updater methods are used to update column values in the
1985 * current row or the insert row. The updater methods do not
1986 * update the underlying database; instead the <code>updateRow</code> or
1987 * <code>insertRow</code> methods are called to update the database.
1988 *
1989 * @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
1990 * @param x the new column value
1991 * @exception SQLException if the columnLabel is not valid;
1992 * if a database access error occurs;
1993 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
1994 * or this method is called on a closed result set
1995 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1996 * this method
1997 * @since 1.2
1998 */
1999 void updateLong(String columnLabel, long x) throws SQLException;
2000
2001 /**
2002 * Updates the designated column with a <code>float </code> value.
2003 * The updater methods are used to update column values in the
2004 * current row or the insert row. The updater methods do not
2005 * update the underlying database; instead the <code>updateRow</code> or
2006 * <code>insertRow</code> methods are called to update the database.
2007 *
2008 * @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
2009 * @param x the new column value
2010 * @exception SQLException if the columnLabel is not valid;
2011 * if a database access error occurs;
2012 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2013 * or this method is called on a closed result set
2014 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2015 * this method
2016 * @since 1.2
2017 */
2018 void updateFloat(String columnLabel, float x) throws SQLException;
2019
2020 /**
2021 * Updates the designated column with a <code>double</code> value.
2022 * The updater methods are used to update column values in the
2023 * current row or the insert row. The updater methods do not
2024 * update the underlying database; instead the <code>updateRow</code> or
2025 * <code>insertRow</code> methods are called to update the database.
2026 *
2027 * @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
2028 * @param x the new column value
2029 * @exception SQLException if the columnLabel is not valid;
2030 * if a database access error occurs;
2031 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2032 * or this method is called on a closed result set
2033 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2034 * this method
2035 * @since 1.2
2036 */
2037 void updateDouble(String columnLabel, double x) throws SQLException;
2038
2039 /**
2040 * Updates the designated column with a <code>java.sql.BigDecimal</code>
2041 * value.
2042 * The updater methods are used to update column values in the
2043 * current row or the insert row. The updater methods do not
2044 * update the underlying database; instead the <code>updateRow</code> or
2045 * <code>insertRow</code> methods are called to update the database.
2046 *
2047 * @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
2048 * @param x the new column value
2049 * @exception SQLException if the columnLabel is not valid;
2050 * if a database access error occurs;
2051 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2052 * or this method is called on a closed result set
2053 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2054 * this method
2055 * @since 1.2
2056 */
2057 void updateBigDecimal(String columnLabel, BigDecimal x) throws SQLException;
2058
2059 /**
2060 * Updates the designated column with a <code>String</code> value.
2061 * The updater methods are used to update column values in the
2062 * current row or the insert row. The updater methods do not
2063 * update the underlying database; instead the <code>updateRow</code> or
2064 * <code>insertRow</code> methods are called to update the database.
2065 *
2066 * @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
2067 * @param x the new column value
2068 * @exception SQLException if the columnLabel is not valid;
2069 * if a database access error occurs;
2070 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2071 * or this method is called on a closed result set
2072 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2073 * this method
2074 * @since 1.2
2075 */
2076 void updateString(String columnLabel, String x) throws SQLException;
2077
2078 /**
2079 * Updates the designated column with a byte array value.
2080 *
2081 * The updater methods are used to update column values in the
2082 * current row or the insert row. The updater methods do not
2083 * update the underlying database; instead the <code>updateRow</code>
2084 * or <code>insertRow</code> methods are called to update the database.
2085 *
2086 * @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
2087 * @param x the new column value
2088 * @exception SQLException if the columnLabel is not valid;
2089 * if a database access error occurs;
2090 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2091 * or this method is called on a closed result set
2092 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2093 * this method
2094 * @since 1.2
2095 */
2096 void updateBytes(String columnLabel, byte x[]) throws SQLException;
2097
2098 /**
2099 * Updates the designated column with a <code>java.sql.Date</code> value.
2100 * The updater methods are used to update column values in the
2101 * current row or the insert row. The updater methods do not
2102 * update the underlying database; instead the <code>updateRow</code> or
2103 * <code>insertRow</code> methods are called to update the database.
2104 *
2105 * @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
2106 * @param x the new column value
2107 * @exception SQLException if the columnLabel is not valid;
2108 * if a database access error occurs;
2109 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2110 * or this method is called on a closed result set
2111 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2112 * this method
2113 * @since 1.2
2114 */
2115 void updateDate(String columnLabel, java.sql.Date x) throws SQLException;
2116
2117 /**
2118 * Updates the designated column with a <code>java.sql.Time</code> value.
2119 * The updater methods are used to update column values in the
2120 * current row or the insert row. The updater methods do not
2121 * update the underlying database; instead the <code>updateRow</code> or
2122 * <code>insertRow</code> methods are called to update the database.
2123 *
2124 * @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
2125 * @param x the new column value
2126 * @exception SQLException if the columnLabel is not valid;
2127 * if a database access error occurs;
2128 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2129 * or this method is called on a closed result set
2130 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2131 * this method
2132 * @since 1.2
2133 */
2134 void updateTime(String columnLabel, java.sql.Time x) throws SQLException;
2135
2136 /**
2137 * Updates the designated column with a <code>java.sql.Timestamp</code>
2138 * value.
2139 * The updater methods are used to update column values in the
2140 * current row or the insert row. The updater methods do not
2141 * update the underlying database; instead the <code>updateRow</code> or
2142 * <code>insertRow</code> methods are called to update the database.
2143 *
2144 * @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
2145 * @param x the new column value
2146 * @exception SQLException if the columnLabel is not valid;
2147 * if a database access error occurs;
2148 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2149 * or this method is called on a closed result set
2150 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2151 * this method
2152 * @since 1.2
2153 */
2154 void updateTimestamp(String columnLabel, java.sql.Timestamp x)
2155 throws SQLException;
2156
2157 /**
2158 * Updates the designated column with an ascii stream value, which will have
2159 * the specified number of bytes.
2160 * The updater methods are used to update column values in the
2161 * current row or the insert row. The updater methods do not
2162 * update the underlying database; instead the <code>updateRow</code> or
2163 * <code>insertRow</code> methods are called to update the database.
2164 *
2165 * @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
2166 * @param x the new column value
2167 * @param length the length of the stream
2168 * @exception SQLException if the columnLabel is not valid;
2169 * if a database access error occurs;
2170 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2171 * or this method is called on a closed result set
2172 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2173 * this method
2174 * @since 1.2
2175 */
2176 void updateAsciiStream(String columnLabel,
2177 java.io.InputStream x,
2178 int length) throws SQLException;
2179
2180 /**
2181 * Updates the designated column with a binary stream value, which will have
2182 * the specified number of bytes.
2183 * The updater methods are used to update column values in the
2184 * current row or the insert row. The updater methods do not
2185 * update the underlying database; instead the <code>updateRow</code> or
2186 * <code>insertRow</code> methods are called to update the database.
2187 *
2188 * @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
2189 * @param x the new column value
2190 * @param length the length of the stream
2191 * @exception SQLException if the columnLabel is not valid;
2192 * if a database access error occurs;
2193 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2194 * or this method is called on a closed result set
2195 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2196 * this method
2197 * @since 1.2
2198 */
2199 void updateBinaryStream(String columnLabel,
2200 java.io.InputStream x,
2201 int length) throws SQLException;
2202
2203 /**
2204 * Updates the designated column with a character stream value, which will have
2205 * the specified number of bytes.
2206 * The updater methods are used to update column values in the
2207 * current row or the insert row. The updater methods do not
2208 * update the underlying database; instead the <code>updateRow</code> or
2209 * <code>insertRow</code> methods are called to update the database.
2210 *
2211 * @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
2212 * @param reader the <code>java.io.Reader</code> object containing
2213 * the new column value
2214 * @param length the length of the stream
2215 * @exception SQLException if the columnLabel is not valid;
2216 * if a database access error occurs;
2217 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2218 * or this method is called on a closed result set
2219 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2220 * this method
2221 * @since 1.2
2222 */
2223 void updateCharacterStream(String columnLabel,
2224 java.io.Reader reader,
2225 int length) throws SQLException;
2226
2227 /**
2228 * Updates the designated column with an <code>Object</code> value.
2229 *
2230 * The updater methods are used to update column values in the
2231 * current row or the insert row. The updater methods do not
2232 * update the underlying database; instead the <code>updateRow</code> or
2233 * <code>insertRow</code> methods are called to update the database.
2234 *<p>
2235 * If the second argument is an <code>InputStream</code> then the stream must contain
2236 * the number of bytes specified by scaleOrLength. If the second argument is a
2237 * <code>Reader</code> then the reader must contain the number of characters specified
2238 * by scaleOrLength. If these conditions are not true the driver will generate a
2239 * <code>SQLException</code> when the statement is executed.
2240 *
2241 * @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
2242 * @param x the new column value
2243 * @param scaleOrLength for an object of <code>java.math.BigDecimal</code> ,
2244 * this is the number of digits after the decimal point. For
2245 * Java Object types <code>InputStream</code> and <code>Reader</code>,
2246 * this is the length
2247 * of the data in the stream or reader. For all other types,
2248 * this value will be ignored.
2249 * @exception SQLException if the columnLabel is not valid;
2250 * if a database access error occurs;
2251 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2252 * or this method is called on a closed result set
2253 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2254 * this method
2255 * @since 1.2
2256 */
2257 void updateObject(String columnLabel, Object x, int scaleOrLength)
2258 throws SQLException;
2259
2260 /**
2261 * Updates the designated column with an <code>Object</code> value.
2262 *
2263 * The updater methods are used to update column values in the
2264 * current row or the insert row. The updater methods do not
2265 * update the underlying database; instead the <code>updateRow</code> or
2266 * <code>insertRow</code> methods are called to update the database.
2267 *
2268 * @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
2269 * @param x the new column value
2270 * @exception SQLException if the columnLabel is not valid;
2271 * if a database access error occurs;
2272 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2273 * or this method is called on a closed result set
2274 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2275 * this method
2276 * @since 1.2
2277 */
2278 void updateObject(String columnLabel, Object x) throws SQLException;
2279
2280 /**
2281 * Inserts the contents of the insert row into this
2282 * <code>ResultSet</code> object and into the database.
2283 * The cursor must be on the insert row when this method is called.
2284 *
2285 * @exception SQLException if a database access error occurs;
2286 * the result set concurrency is <code>CONCUR_READ_ONLY</code>,
2287 * this method is called on a closed result set,
2288 * if this method is called when the cursor is not on the insert row,
2289 * or if not all of non-nullable columns in
2290 * the insert row have been given a non-null value
2291 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2292 * this method
2293 * @since 1.2
2294 */
2295 void insertRow() throws SQLException;
2296
2297 /**
2298 * Updates the underlying database with the new contents of the
2299 * current row of this <code>ResultSet</code> object.
2300 * This method cannot be called when the cursor is on the insert row.
2301 *
2302 * @exception SQLException if a database access error occurs;
2303 * the result set concurrency is <code>CONCUR_READ_ONLY</code>;
2304 * this method is called on a closed result set or
2305 * if this method is called when the cursor is on the insert row
2306 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2307 * this method
2308 * @since 1.2
2309 */
2310 void updateRow() throws SQLException;
2311
2312 /**
2313 * Deletes the current row from this <code>ResultSet</code> object
2314 * and from the underlying database. This method cannot be called when
2315 * the cursor is on the insert row.
2316 *
2317 * @exception SQLException if a database access error occurs;
2318 * the result set concurrency is <code>CONCUR_READ_ONLY</code>;
2319 * this method is called on a closed result set
2320 * or if this method is called when the cursor is on the insert row
2321 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2322 * this method
2323 * @since 1.2
2324 */
2325 void deleteRow() throws SQLException;
2326
2327 /**
2328 * Refreshes the current row with its most recent value in
2329 * the database. This method cannot be called when
2330 * the cursor is on the insert row.
2331 *
2332 * <P>The <code>refreshRow</code> method provides a way for an
2333 * application to
2334 * explicitly tell the JDBC driver to refetch a row(s) from the
2335 * database. An application may want to call <code>refreshRow</code> when
2336 * caching or prefetching is being done by the JDBC driver to
2337 * fetch the latest value of a row from the database. The JDBC driver
2338 * may actually refresh multiple rows at once if the fetch size is
2339 * greater than one.
2340 *
2341 * <P> All values are refetched subject to the transaction isolation
2342 * level and cursor sensitivity. If <code>refreshRow</code> is called after
2343 * calling an updater method, but before calling
2344 * the method <code>updateRow</code>, then the
2345 * updates made to the row are lost. Calling the method
2346 * <code>refreshRow</code> frequently will likely slow performance.
2347 *
2348 * @exception SQLException if a database access error
2349 * occurs; this method is called on a closed result set;
2350 * the result set type is <code>TYPE_FORWARD_ONLY</code> or if this
2351 * method is called when the cursor is on the insert row
2352 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2353 * this method or this method is not supported for the specified result
2354 * set type and result set concurrency.
2355 * @since 1.2
2356 */
2357 void refreshRow() throws SQLException;
2358
2359 /**
2360 * Cancels the updates made to the current row in this
2361 * <code>ResultSet</code> object.
2362 * This method may be called after calling an
2363 * updater method(s) and before calling
2364 * the method <code>updateRow</code> to roll back
2365 * the updates made to a row. If no updates have been made or
2366 * <code>updateRow</code> has already been called, this method has no
2367 * effect.
2368 *
2369 * @exception SQLException if a database access error
2370 * occurs; this method is called on a closed result set;
2371 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2372 * or if this method is called when the cursor is
2373 * on the insert row
2374 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2375 * this method
2376 * @since 1.2
2377 */
2378 void cancelRowUpdates() throws SQLException;
2379
2380 /**
2381 * Moves the cursor to the insert row. The current cursor position is
2382 * remembered while the cursor is positioned on the insert row.
2383 *
2384 * The insert row is a special row associated with an updatable
2385 * result set. It is essentially a buffer where a new row may
2386 * be constructed by calling the updater methods prior to
2387 * inserting the row into the result set.
2388 *
2389 * Only the updater, getter,
2390 * and <code>insertRow</code> methods may be
2391 * called when the cursor is on the insert row. All of the columns in
2392 * a result set must be given a value each time this method is
2393 * called before calling <code>insertRow</code>.
2394 * An updater method must be called before a
2395 * getter method can be called on a column value.
2396 *
2397 * @exception SQLException if a database access error occurs; this
2398 * method is called on a closed result set
2399 * or the result set concurrency is <code>CONCUR_READ_ONLY</code>
2400 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2401 * this method
2402 * @since 1.2
2403 */
2404 void moveToInsertRow() throws SQLException;
2405
2406 /**
2407 * Moves the cursor to the remembered cursor position, usually the
2408 * current row. This method has no effect if the cursor is not on
2409 * the insert row.
2410 *
2411 * @exception SQLException if a database access error occurs; this
2412 * method is called on a closed result set
2413 * or the result set concurrency is <code>CONCUR_READ_ONLY</code>
2414 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2415 * this method
2416 * @since 1.2
2417 */
2418 void moveToCurrentRow() throws SQLException;
2419
2420 /**
2421 * Retrieves the <code>Statement</code> object that produced this
2422 * <code>ResultSet</code> object.
2423 * If the result set was generated some other way, such as by a
2424 * <code>DatabaseMetaData</code> method, this method may return
2425 * <code>null</code>.
2426 *
2427 * @return the <code>Statment</code> object that produced
2428 * this <code>ResultSet</code> object or <code>null</code>
2429 * if the result set was produced some other way
2430 * @exception SQLException if a database access error occurs
2431 * or this method is called on a closed result set
2432 * @since 1.2
2433 */
2434 Statement getStatement() throws SQLException;
2435
2436 /**
2437 * Retrieves the value of the designated column in the current row
2438 * of this <code>ResultSet</code> object as an <code>Object</code>
2439 * in the Java programming language.
2440 * If the value is an SQL <code>NULL</code>,
2441 * the driver returns a Java <code>null</code>.
2442 * This method uses the given <code>Map</code> object
2443 * for the custom mapping of the
2444 * SQL structured or distinct type that is being retrieved.
2445 *
2446 * @param columnIndex the first column is 1, the second is 2, ...
2447 * @param map a <code>java.util.Map</code> object that contains the mapping
2448 * from SQL type names to classes in the Java programming language
2449 * @return an <code>Object</code> in the Java programming language
2450 * representing the SQL value
2451 * @exception SQLException if the columnIndex is not valid;
2452 * if a database access error occurs
2453 * or this method is called on a closed result set
2454 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2455 * this method
2456 * @since 1.2
2457 */
2458 Object getObject(int columnIndex, java.util.Map<String,Class<?>> map)
2459 throws SQLException;
2460
2461 /**
2462 * Retrieves the value of the designated column in the current row
2463 * of this <code>ResultSet</code> object as a <code>Ref</code> object
2464 * in the Java programming language.
2465 *
2466 * @param columnIndex the first column is 1, the second is 2, ...
2467 * @return a <code>Ref</code> object representing an SQL <code>REF</code>
2468 * value
2469 * @exception SQLException if the columnIndex is not valid;
2470 * if a database access error occurs
2471 * or this method is called on a closed result set
2472 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2473 * this method
2474 * @since 1.2
2475 */
2476 Ref getRef(int columnIndex) throws SQLException;
2477
2478 /**
2479 * Retrieves the value of the designated column in the current row
2480 * of this <code>ResultSet</code> object as a <code>Blob</code> object
2481 * in the Java programming language.
2482 *
2483 * @param columnIndex the first column is 1, the second is 2, ...
2484 * @return a <code>Blob</code> object representing the SQL
2485 * <code>BLOB</code> value in the specified column
2486 * @exception SQLException if the columnIndex is not valid;
2487 * if a database access error occurs
2488 * or this method is called on a closed result set
2489 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2490 * this method
2491 * @since 1.2
2492 */
2493 Blob getBlob(int columnIndex) throws SQLException;
2494
2495 /**
2496 * Retrieves the value of the designated column in the current row
2497 * of this <code>ResultSet</code> object as a <code>Clob</code> object
2498 * in the Java programming language.
2499 *
2500 * @param columnIndex the first column is 1, the second is 2, ...
2501 * @return a <code>Clob</code> object representing the SQL
2502 * <code>CLOB</code> value in the specified column
2503 * @exception SQLException if the columnIndex is not valid;
2504 * if a database access error occurs
2505 * or this method is called on a closed result set
2506 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2507 * this method
2508 * @since 1.2
2509 */
2510 Clob getClob(int columnIndex) throws SQLException;
2511
2512 /**
2513 * Retrieves the value of the designated column in the current row
2514 * of this <code>ResultSet</code> object as an <code>Array</code> object
2515 * in the Java programming language.
2516 *
2517 * @param columnIndex the first column is 1, the second is 2, ...
2518 * @return an <code>Array</code> object representing the SQL
2519 * <code>ARRAY</code> value in the specified column
2520 * @exception SQLException if the columnIndex is not valid;
2521 * if a database access error occurs
2522 * or this method is called on a closed result set
2523 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2524 * this method
2525 * @since 1.2
2526 */
2527 Array getArray(int columnIndex) throws SQLException;
2528
2529 /**
2530 * Retrieves the value of the designated column in the current row
2531 * of this <code>ResultSet</code> object as an <code>Object</code>
2532 * in the Java programming language.
2533 * If the value is an SQL <code>NULL</code>,
2534 * the driver returns a Java <code>null</code>.
2535 * This method uses the specified <code>Map</code> object for
2536 * custom mapping if appropriate.
2537 *
2538 * @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
2539 * @param map a <code>java.util.Map</code> object that contains the mapping
2540 * from SQL type names to classes in the Java programming language
2541 * @return an <code>Object</code> representing the SQL value in the
2542 * specified column
2543 * @exception SQLException if the columnLabel is not valid;
2544 * if a database access error occurs
2545 * or this method is called on a closed result set
2546 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2547 * this method
2548 * @since 1.2
2549 */
2550 Object getObject(String columnLabel, java.util.Map<String,Class<?>> map)
2551 throws SQLException;
2552
2553 /**
2554 * Retrieves the value of the designated column in the current row
2555 * of this <code>ResultSet</code> object as a <code>Ref</code> object
2556 * in the Java programming language.
2557 *
2558 * @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
2559 * @return a <code>Ref</code> object representing the SQL <code>REF</code>
2560 * value in the specified column
2561 * @exception SQLException if the columnLabel is not valid;
2562 * if a database access error occurs
2563 * or this method is called on a closed result set
2564 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2565 * this method
2566 * @since 1.2
2567 */
2568 Ref getRef(String columnLabel) throws SQLException;
2569
2570 /**
2571 * Retrieves the value of the designated column in the current row
2572 * of this <code>ResultSet</code> object as a <code>Blob</code> object
2573 * in the Java programming language.
2574 *
2575 * @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
2576 * @return a <code>Blob</code> object representing the SQL <code>BLOB</code>
2577 * value in the specified column
2578 * @exception SQLException if the columnLabel is not valid;
2579 * if a database access error occurs
2580 * or this method is called on a closed result set
2581 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2582 * this method
2583 * @since 1.2
2584 */
2585 Blob getBlob(String columnLabel) throws SQLException;
2586
2587 /**
2588 * Retrieves the value of the designated column in the current row
2589 * of this <code>ResultSet</code> object as a <code>Clob</code> object
2590 * in the Java programming language.
2591 *
2592 * @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
2593 * @return a <code>Clob</code> object representing the SQL <code>CLOB</code>
2594 * value in the specified column
2595 * @exception SQLException if the columnLabel is not valid;
2596 * if a database access error occurs
2597 * or this method is called on a closed result set
2598 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2599 * this method
2600 * @since 1.2
2601 */
2602 Clob getClob(String columnLabel) throws SQLException;
2603
2604 /**
2605 * Retrieves the value of the designated column in the current row
2606 * of this <code>ResultSet</code> object as an <code>Array</code> object
2607 * in the Java programming language.
2608 *
2609 * @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
2610 * @return an <code>Array</code> object representing the SQL <code>ARRAY</code> value in
2611 * the specified column
2612 * @exception SQLException if the columnLabel is not valid;
2613 * if a database access error occurs
2614 * or this method is called on a closed result set
2615 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2616 * this method
2617 * @since 1.2
2618 */
2619 Array getArray(String columnLabel) throws SQLException;
2620
2621 /**
2622 * Retrieves the value of the designated column in the current row
2623 * of this <code>ResultSet</code> object as a <code>java.sql.Date</code> object
2624 * in the Java programming language.
2625 * This method uses the given calendar to construct an appropriate millisecond
2626 * value for the date if the underlying database does not store
2627 * timezone information.
2628 *
2629 * @param columnIndex the first column is 1, the second is 2, ...
2630 * @param cal the <code>java.util.Calendar</code> object
2631 * to use in constructing the date
2632 * @return the column value as a <code>java.sql.Date</code> object;
2633 * if the value is SQL <code>NULL</code>,
2634 * the value returned is <code>null</code> in the Java programming language
2635 * @exception SQLException if the columnIndex is not valid;
2636 * if a database access error occurs
2637 * or this method is called on a closed result set
2638 * @since 1.2
2639 */
2640 java.sql.Date getDate(int columnIndex, Calendar cal) throws SQLException;
2641
2642 /**
2643 * Retrieves the value of the designated column in the current row
2644 * of this <code>ResultSet</code> object as a <code>java.sql.Date</code> object
2645 * in the Java programming language.
2646 * This method uses the given calendar to construct an appropriate millisecond
2647 * value for the date if the underlying database does not store
2648 * timezone information.
2649 *
2650 * @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
2651 * @param cal the <code>java.util.Calendar</code> object
2652 * to use in constructing the date
2653 * @return the column value as a <code>java.sql.Date</code> object;
2654 * if the value is SQL <code>NULL</code>,
2655 * the value returned is <code>null</code> in the Java programming language
2656 * @exception SQLException if the columnLabel is not valid;
2657 * if a database access error occurs
2658 * or this method is called on a closed result set
2659 * @since 1.2
2660 */
2661 java.sql.Date getDate(String columnLabel, Calendar cal) throws SQLException;
2662
2663 /**
2664 * Retrieves the value of the designated column in the current row
2665 * of this <code>ResultSet</code> object as a <code>java.sql.Time</code> object
2666 * in the Java programming language.
2667 * This method uses the given calendar to construct an appropriate millisecond
2668 * value for the time if the underlying database does not store
2669 * timezone information.
2670 *
2671 * @param columnIndex the first column is 1, the second is 2, ...
2672 * @param cal the <code>java.util.Calendar</code> object
2673 * to use in constructing the time
2674 * @return the column value as a <code>java.sql.Time</code> object;
2675 * if the value is SQL <code>NULL</code>,
2676 * the value returned is <code>null</code> in the Java programming language
2677 * @exception SQLException if the columnIndex is not valid;
2678 * if a database access error occurs
2679 * or this method is called on a closed result set
2680 * @since 1.2
2681 */
2682 java.sql.Time getTime(int columnIndex, Calendar cal) throws SQLException;
2683
2684 /**
2685 * Retrieves the value of the designated column in the current row
2686 * of this <code>ResultSet</code> object as a <code>java.sql.Time</code> object
2687 * in the Java programming language.
2688 * This method uses the given calendar to construct an appropriate millisecond
2689 * value for the time if the underlying database does not store
2690 * timezone information.
2691 *
2692 * @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
2693 * @param cal the <code>java.util.Calendar</code> object
2694 * to use in constructing the time
2695 * @return the column value as a <code>java.sql.Time</code> object;
2696 * if the value is SQL <code>NULL</code>,
2697 * the value returned is <code>null</code> in the Java programming language
2698 * @exception SQLException if the columnLabel is not valid;
2699 * if a database access error occurs
2700 * or this method is called on a closed result set
2701 * @since 1.2
2702 */
2703 java.sql.Time getTime(String columnLabel, Calendar cal) throws SQLException;
2704
2705 /**
2706 * Retrieves the value of the designated column in the current row
2707 * of this <code>ResultSet</code> object as a <code>java.sql.Timestamp</code> object
2708 * in the Java programming language.
2709 * This method uses the given calendar to construct an appropriate millisecond
2710 * value for the timestamp if the underlying database does not store
2711 * timezone information.
2712 *
2713 * @param columnIndex the first column is 1, the second is 2, ...
2714 * @param cal the <code>java.util.Calendar</code> object
2715 * to use in constructing the timestamp
2716 * @return the column value as a <code>java.sql.Timestamp</code> object;
2717 * if the value is SQL <code>NULL</code>,
2718 * the value returned is <code>null</code> in the Java programming language
2719 * @exception SQLException if the columnIndex is not valid;
2720 * if a database access error occurs
2721 * or this method is called on a closed result set
2722 * @since 1.2
2723 */
2724 java.sql.Timestamp getTimestamp(int columnIndex, Calendar cal)
2725 throws SQLException;
2726
2727 /**
2728 * Retrieves the value of the designated column in the current row
2729 * of this <code>ResultSet</code> object as a <code>java.sql.Timestamp</code> object
2730 * in the Java programming language.
2731 * This method uses the given calendar to construct an appropriate millisecond
2732 * value for the timestamp if the underlying database does not store
2733 * timezone information.
2734 *
2735 * @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
2736 * @param cal the <code>java.util.Calendar</code> object
2737 * to use in constructing the date
2738 * @return the column value as a <code>java.sql.Timestamp</code> object;
2739 * if the value is SQL <code>NULL</code>,
2740 * the value returned is <code>null</code> in the Java programming language
2741 * @exception SQLException if the columnLabel is not valid or
2742 * if a database access error occurs
2743 * or this method is called on a closed result set
2744 * @since 1.2
2745 */
2746 java.sql.Timestamp getTimestamp(String columnLabel, Calendar cal)
2747 throws SQLException;
2748
2749 //-------------------------- JDBC 3.0 ----------------------------------------
2750
2751 /**
2752 * The constant indicating that open <code>ResultSet</code> objects with this
2753 * holdability will remain open when the current transaction is commited.
2754 *
2755 * @since 1.4
2756 */
2757 int HOLD_CURSORS_OVER_COMMIT = 1;
2758
2759 /**
2760 * The constant indicating that open <code>ResultSet</code> objects with this
2761 * holdability will be closed when the current transaction is commited.
2762 *
2763 * @since 1.4
2764 */
2765 int CLOSE_CURSORS_AT_COMMIT = 2;
2766
2767 /**
2768 * Retrieves the value of the designated column in the current row
2769 * of this <code>ResultSet</code> object as a <code>java.net.URL</code>
2770 * object in the Java programming language.
2771 *
2772 * @param columnIndex the index of the column 1 is the first, 2 is the second,...
2773 * @return the column value as a <code>java.net.URL</code> object;
2774 * if the value is SQL <code>NULL</code>,
2775 * the value returned is <code>null</code> in the Java programming language
2776 * @exception SQLException if the columnIndex is not valid;
2777 * if a database access error occurs; this method
2778 * is called on a closed result set or if a URL is malformed
2779 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2780 * this method
2781 * @since 1.4
2782 */
2783 java.net.URL getURL(int columnIndex) throws SQLException;
2784
2785 /**
2786 * Retrieves the value of the designated column in the current row
2787 * of this <code>ResultSet</code> object as a <code>java.net.URL</code>
2788 * object in the Java programming language.
2789 *
2790 * @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
2791 * @return the column value as a <code>java.net.URL</code> object;
2792 * if the value is SQL <code>NULL</code>,
2793 * the value returned is <code>null</code> in the Java programming language
2794 * @exception SQLException if the columnLabel is not valid;
2795 * if a database access error occurs; this method
2796 * is called on a closed result set or if a URL is malformed
2797 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2798 * this method
2799 * @since 1.4
2800 */
2801 java.net.URL getURL(String columnLabel) throws SQLException;
2802
2803 /**
2804 * Updates the designated column with a <code>java.sql.Ref</code> value.
2805 * The updater methods are used to update column values in the
2806 * current row or the insert row. The updater methods do not
2807 * update the underlying database; instead the <code>updateRow</code> or
2808 * <code>insertRow</code> methods are called to update the database.
2809 *
2810 * @param columnIndex the first column is 1, the second is 2, ...
2811 * @param x the new column value
2812 * @exception SQLException if the columnIndex is not valid;
2813 * if a database access error occurs;
2814 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2815 * or this method is called on a closed result set
2816 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2817 * this method
2818 * @since 1.4
2819 */
2820 void updateRef(int columnIndex, java.sql.Ref x) throws SQLException;
2821
2822 /**
2823 * Updates the designated column with a <code>java.sql.Ref</code> value.
2824 * The updater methods are used to update column values in the
2825 * current row or the insert row. The updater methods do not
2826 * update the underlying database; instead the <code>updateRow</code> or
2827 * <code>insertRow</code> methods are called to update the database.
2828 *
2829 * @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
2830 * @param x the new column value
2831 * @exception SQLException if the columnLabel is not valid;
2832 * if a database access error occurs;
2833 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2834 * or this method is called on a closed result set
2835 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2836 * this method
2837 * @since 1.4
2838 */
2839 void updateRef(String columnLabel, java.sql.Ref x) throws SQLException;
2840
2841 /**
2842 * Updates the designated column with a <code>java.sql.Blob</code> value.
2843 * The updater methods are used to update column values in the
2844 * current row or the insert row. The updater methods do not
2845 * update the underlying database; instead the <code>updateRow</code> or
2846 * <code>insertRow</code> methods are called to update the database.
2847 *
2848 * @param columnIndex the first column is 1, the second is 2, ...
2849 * @param x the new column value
2850 * @exception SQLException if the columnIndex is not valid;
2851 * if a database access error occurs;
2852 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2853 * or this method is called on a closed result set
2854 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2855 * this method
2856 * @since 1.4
2857 */
2858 void updateBlob(int columnIndex, java.sql.Blob x) throws SQLException;
2859
2860 /**
2861 * Updates the designated column with a <code>java.sql.Blob</code> value.
2862 * The updater methods are used to update column values in the
2863 * current row or the insert row. The updater methods do not
2864 * update the underlying database; instead the <code>updateRow</code> or
2865 * <code>insertRow</code> methods are called to update the database.
2866 *
2867 * @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
2868 * @param x the new column value
2869 * @exception SQLException if the columnLabel is not valid;
2870 * if a database access error occurs;
2871 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2872 * or this method is called on a closed result set
2873 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2874 * this method
2875 * @since 1.4
2876 */
2877 void updateBlob(String columnLabel, java.sql.Blob x) throws SQLException;
2878
2879 /**
2880 * Updates the designated column with a <code>java.sql.Clob</code> value.
2881 * The updater methods are used to update column values in the
2882 * current row or the insert row. The updater methods do not
2883 * update the underlying database; instead the <code>updateRow</code> or
2884 * <code>insertRow</code> methods are called to update the database.
2885 *
2886 * @param columnIndex the first column is 1, the second is 2, ...
2887 * @param x the new column value
2888 * @exception SQLException if the columnIndex is not valid;
2889 * if a database access error occurs;
2890 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2891 * or this method is called on a closed result set
2892 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2893 * this method
2894 * @since 1.4
2895 */
2896 void updateClob(int columnIndex, java.sql.Clob x) throws SQLException;
2897
2898 /**
2899 * Updates the designated column with a <code>java.sql.Clob</code> value.
2900 * The updater methods are used to update column values in the
2901 * current row or the insert row. The updater methods do not
2902 * update the underlying database; instead the <code>updateRow</code> or
2903 * <code>insertRow</code> methods are called to update the database.
2904 *
2905 * @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
2906 * @param x the new column value
2907 * @exception SQLException if the columnLabel is not valid;
2908 * if a database access error occurs;
2909 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2910 * or this method is called on a closed result set
2911 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2912 * this method
2913 * @since 1.4
2914 */
2915 void updateClob(String columnLabel, java.sql.Clob x) throws SQLException;
2916
2917 /**
2918 * Updates the designated column with a <code>java.sql.Array</code> value.
2919 * The updater methods are used to update column values in the
2920 * current row or the insert row. The updater methods do not
2921 * update the underlying database; instead the <code>updateRow</code> or
2922 * <code>insertRow</code> methods are called to update the database.
2923 *
2924 * @param columnIndex the first column is 1, the second is 2, ...
2925 * @param x the new column value
2926 * @exception SQLException if the columnIndex is not valid;
2927 * if a database access error occurs;
2928 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2929 * or this method is called on a closed result set
2930 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2931 * this method
2932 * @since 1.4
2933 */
2934 void updateArray(int columnIndex, java.sql.Array x) throws SQLException;
2935
2936 /**
2937 * Updates the designated column with a <code>java.sql.Array</code> value.
2938 * The updater methods are used to update column values in the
2939 * current row or the insert row. The updater methods do not
2940 * update the underlying database; instead the <code>updateRow</code> or
2941 * <code>insertRow</code> methods are called to update the database.
2942 *
2943 * @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
2944 * @param x the new column value
2945 * @exception SQLException if the columnLabel is not valid;
2946 * if a database access error occurs;
2947 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
2948 * or this method is called on a closed result set
2949 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2950 * this method
2951 * @since 1.4
2952 */
2953 void updateArray(String columnLabel, java.sql.Array x) throws SQLException;
2954
2955 //------------------------- JDBC 4.0 -----------------------------------
2956
2957 /**
2958 * Retrieves the value of the designated column in the current row of this
2959 * <code>ResultSet</code> object as a <code>java.sql.RowId</code> object in the Java
2960 * programming language.
2961 *
2962 * @param columnIndex the first column is 1, the second 2, ...
2963 * @return the column value; if the value is a SQL <code>NULL</code> the
2964 * value returned is <code>null</code>
2965 * @throws SQLException if the columnIndex is not valid;
2966 * if a database access error occurs
2967 * or this method is called on a closed result set
2968 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2969 * this method
2970 * @since 1.6
2971 */
2972 RowId getRowId(int columnIndex) throws SQLException;
2973
2974 /**
2975 * Retrieves the value of the designated column in the current row of this
2976 * <code>ResultSet</code> object as a <code>java.sql.RowId</code> object in the Java
2977 * programming language.
2978 *
2979 * @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
2980 * @return the column value ; if the value is a SQL <code>NULL</code> the
2981 * value returned is <code>null</code>
2982 * @throws SQLException if the columnLabel is not valid;
2983 * if a database access error occurs
2984 * or this method is called on a closed result set
2985 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
2986 * this method
2987 * @since 1.6
2988 */
2989 RowId getRowId(String columnLabel) throws SQLException;
2990
2991 /**
2992 * Updates the designated column with a <code>RowId</code> value. The updater
2993 * methods are used to update column values in the current row or the insert
2994 * row. The updater methods do not update the underlying database; instead
2995 * the <code>updateRow</code> or <code>insertRow</code> methods are called
2996 * to update the database.
2997 *
2998 * @param columnIndex the first column is 1, the second 2, ...
2999 * @param x the column value
3000 * @exception SQLException if the columnIndex is not valid;
3001 * if a database access error occurs;
3002 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3003 * or this method is called on a closed result set
3004 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3005 * this method
3006 * @since 1.6
3007 */
3008 void updateRowId(int columnIndex, RowId x) throws SQLException;
3009
3010 /**
3011 * Updates the designated column with a <code>RowId</code> value. The updater
3012 * methods are used to update column values in the current row or the insert
3013 * row. The updater methods do not update the underlying database; instead
3014 * the <code>updateRow</code> or <code>insertRow</code> methods are called
3015 * to update the database.
3016 *
3017 * @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
3018 * @param x the column value
3019 * @exception SQLException if the columnLabel is not valid;
3020 * if a database access error occurs;
3021 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3022 * or this method is called on a closed result set
3023 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3024 * this method
3025 * @since 1.6
3026 */
3027 void updateRowId(String columnLabel, RowId x) throws SQLException;
3028
3029 /**
3030 * Retrieves the holdability of this <code>ResultSet</code> object
3031 * @return either <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
3032 * @throws SQLException if a database access error occurs
3033 * or this method is called on a closed result set
3034 * @since 1.6
3035 */
3036 int getHoldability() throws SQLException;
3037
3038 /**
3039 * Retrieves whether this <code>ResultSet</code> object has been closed. A <code>ResultSet</code> is closed if the
3040 * method close has been called on it, or if it is automatically closed.
3041 *
3042 * @return true if this <code>ResultSet</code> object is closed; false if it is still open
3043 * @throws SQLException if a database access error occurs
3044 * @since 1.6
3045 */
3046 boolean isClosed() throws SQLException;
3047
3048 /**
3049 * Updates the designated column with a <code>String</code> value.
3050 * It is intended for use when updating <code>NCHAR</code>,<code>NVARCHAR</code>
3051 * and <code>LONGNVARCHAR</code> columns.
3052 * The updater methods are used to update column values in the
3053 * current row or the insert row. The updater methods do not
3054 * update the underlying database; instead the <code>updateRow</code> or
3055 * <code>insertRow</code> methods are called to update the database.
3056 *
3057 * @param columnIndex the first column is 1, the second 2, ...
3058 * @param nString the value for the column to be updated
3059 * @throws SQLException if the columnIndex is not valid;
3060 * if the driver does not support national
3061 * character sets; if the driver can detect that a data conversion
3062 * error could occur; this method is called on a closed result set;
3063 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3064 * or if a database access error occurs
3065 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3066 * this method
3067 * @since 1.6
3068 */
3069 void updateNString(int columnIndex, String nString) throws SQLException;
3070
3071 /**
3072 * Updates the designated column with a <code>String</code> value.
3073 * It is intended for use when updating <code>NCHAR</code>,<code>NVARCHAR</code>
3074 * and <code>LONGNVARCHAR</code> columns.
3075 * The updater methods are used to update column values in the
3076 * current row or the insert row. The updater methods do not
3077 * update the underlying database; instead the <code>updateRow</code> or
3078 * <code>insertRow</code> methods are called to update the database.
3079 *
3080 * @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
3081 * @param nString the value for the column to be updated
3082 * @throws SQLException if the columnLabel is not valid;
3083 * if the driver does not support national
3084 * character sets; if the driver can detect that a data conversion
3085 * error could occur; this method is called on a closed result set;
3086 * the result set concurrency is <CODE>CONCUR_READ_ONLY</code>
3087 * or if a database access error occurs
3088 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3089 * this method
3090 * @since 1.6
3091 */
3092 void updateNString(String columnLabel, String nString) throws SQLException;
3093
3094 /**
3095 * Updates the designated column with a <code>java.sql.NClob</code> value.
3096 * The updater methods are used to update column values in the
3097 * current row or the insert row. The updater methods do not
3098 * update the underlying database; instead the <code>updateRow</code> or
3099 * <code>insertRow</code> methods are called to update the database.
3100 *
3101 * @param columnIndex the first column is 1, the second 2, ...
3102 * @param nClob the value for the column to be updated
3103 * @throws SQLException if the columnIndex is not valid;
3104 * if the driver does not support national
3105 * character sets; if the driver can detect that a data conversion
3106 * error could occur; this method is called on a closed result set;
3107 * if a database access error occurs or
3108 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3109 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3110 * this method
3111 * @since 1.6
3112 */
3113 void updateNClob(int columnIndex, NClob nClob) throws SQLException;
3114
3115 /**
3116 * Updates the designated column with a <code>java.sql.NClob</code> value.
3117 * The updater methods are used to update column values in the
3118 * current row or the insert row. The updater methods do not
3119 * update the underlying database; instead the <code>updateRow</code> or
3120 * <code>insertRow</code> methods are called to update the database.
3121 *
3122 * @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
3123 * @param nClob the value for the column to be updated
3124 * @throws SQLException if the columnLabel is not valid;
3125 * if the driver does not support national
3126 * character sets; if the driver can detect that a data conversion
3127 * error could occur; this method is called on a closed result set;
3128 * if a database access error occurs or
3129 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3130 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3131 * this method
3132 * @since 1.6
3133 */
3134 void updateNClob(String columnLabel, NClob nClob) throws SQLException;
3135
3136 /**
3137 * Retrieves the value of the designated column in the current row
3138 * of this <code>ResultSet</code> object as a <code>NClob</code> object
3139 * in the Java programming language.
3140 *
3141 * @param columnIndex the first column is 1, the second is 2, ...
3142 * @return a <code>NClob</code> object representing the SQL
3143 * <code>NCLOB</code> value in the specified column
3144 * @exception SQLException if the columnIndex is not valid;
3145 * if the driver does not support national
3146 * character sets; if the driver can detect that a data conversion
3147 * error could occur; this method is called on a closed result set
3148 * or if a database access error occurs
3149 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3150 * this method
3151 * @since 1.6
3152 */
3153 NClob getNClob(int columnIndex) throws SQLException;
3154
3155 /**
3156 * Retrieves the value of the designated column in the current row
3157 * of this <code>ResultSet</code> object as a <code>NClob</code> object
3158 * in the Java programming language.
3159 *
3160 * @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
3161 * @return a <code>NClob</code> object representing the SQL <code>NCLOB</code>
3162 * value in the specified column
3163 * @exception SQLException if the columnLabel is not valid;
3164 * if the driver does not support national
3165 * character sets; if the driver can detect that a data conversion
3166 * error could occur; this method is called on a closed result set
3167 * or if a database access error occurs
3168 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3169 * this method
3170 * @since 1.6
3171 */
3172 NClob getNClob(String columnLabel) throws SQLException;
3173
3174 /**
3175 * Retrieves the value of the designated column in the current row of
3176 * this <code>ResultSet</code> as a
3177 * <code>java.sql.SQLXML</code> object in the Java programming language.
3178 * @param columnIndex the first column is 1, the second is 2, ...
3179 * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
3180 * @throws SQLException if the columnIndex is not valid;
3181 * if a database access error occurs
3182 * or this method is called on a closed result set
3183 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3184 * this method
3185 * @since 1.6
3186 */
3187 SQLXML getSQLXML(int columnIndex) throws SQLException;
3188
3189 /**
3190 * Retrieves the value of the designated column in the current row of
3191 * this <code>ResultSet</code> as a
3192 * <code>java.sql.SQLXML</code> object in the Java programming language.
3193 * @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
3194 * @return a <code>SQLXML</code> object that maps an <code>SQL XML</code> value
3195 * @throws SQLException if the columnLabel is not valid;
3196 * if a database access error occurs
3197 * or this method is called on a closed result set
3198 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3199 * this method
3200 * @since 1.6
3201 */
3202 SQLXML getSQLXML(String columnLabel) throws SQLException;
3203 /**
3204 * Updates the designated column with a <code>java.sql.SQLXML</code> value.
3205 * The updater
3206 * methods are used to update column values in the current row or the insert
3207 * row. The updater methods do not update the underlying database; instead
3208 * the <code>updateRow</code> or <code>insertRow</code> methods are called
3209 * to update the database.
3210 * <p>
3211 *
3212 * @param columnIndex the first column is 1, the second 2, ...
3213 * @param xmlObject the value for the column to be updated
3214 * @throws SQLException if the columnIndex is not valid;
3215 * if a database access error occurs; this method
3216 * is called on a closed result set;
3217 * the <code>java.xml.transform.Result</code>,
3218 * <code>Writer</code> or <code>OutputStream</code> has not been closed
3219 * for the <code>SQLXML</code> object;
3220 * if there is an error processing the XML value or
3221 * the result set concurrency is <code>CONCUR_READ_ONLY</code>. The <code>getCause</code> method
3222 * of the exception may provide a more detailed exception, for example, if the
3223 * stream does not contain valid XML.
3224 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3225 * this method
3226 * @since 1.6
3227 */
3228 void updateSQLXML(int columnIndex, SQLXML xmlObject) throws SQLException;
3229 /**
3230 * Updates the designated column with a <code>java.sql.SQLXML</code> value.
3231 * The updater
3232 * methods are used to update column values in the current row or the insert
3233 * row. The updater methods do not update the underlying database; instead
3234 * the <code>updateRow</code> or <code>insertRow</code> methods are called
3235 * to update the database.
3236 * <p>
3237 *
3238 * @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
3239 * @param xmlObject the column value
3240 * @throws SQLException if the columnLabel is not valid;
3241 * if a database access error occurs; this method
3242 * is called on a closed result set;
3243 * the <code>java.xml.transform.Result</code>,
3244 * <code>Writer</code> or <code>OutputStream</code> has not been closed
3245 * for the <code>SQLXML</code> object;
3246 * if there is an error processing the XML value or
3247 * the result set concurrency is <code>CONCUR_READ_ONLY</code>. The <code>getCause</code> method
3248 * of the exception may provide a more detailed exception, for example, if the
3249 * stream does not contain valid XML.
3250 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3251 * this method
3252 * @since 1.6
3253 */
3254 void updateSQLXML(String columnLabel, SQLXML xmlObject) throws SQLException;
3255
3256 /**
3257 * Retrieves the value of the designated column in the current row
3258 * of this <code>ResultSet</code> object as
3259 * a <code>String</code> in the Java programming language.
3260 * It is intended for use when
3261 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
3262 * and <code>LONGNVARCHAR</code> columns.
3263 *
3264 * @param columnIndex the first column is 1, the second is 2, ...
3265 * @return the column value; if the value is SQL <code>NULL</code>, the
3266 * value returned is <code>null</code>
3267 * @exception SQLException if the columnIndex is not valid;
3268 * if a database access error occurs
3269 * or this method is called on a closed result set
3270 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3271 * this method
3272 * @since 1.6
3273 */
3274 String getNString(int columnIndex) throws SQLException;
3275
3276
3277 /**
3278 * Retrieves the value of the designated column in the current row
3279 * of this <code>ResultSet</code> object as
3280 * a <code>String</code> in the Java programming language.
3281 * It is intended for use when
3282 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
3283 * and <code>LONGNVARCHAR</code> columns.
3284 *
3285 * @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
3286 * @return the column value; if the value is SQL <code>NULL</code>, the
3287 * value returned is <code>null</code>
3288 * @exception SQLException if the columnLabel is not valid;
3289 * if a database access error occurs
3290 * or this method is called on a closed result set
3291 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3292 * this method
3293 * @since 1.6
3294 */
3295 String getNString(String columnLabel) throws SQLException;
3296
3297
3298 /**
3299 * Retrieves the value of the designated column in the current row
3300 * of this <code>ResultSet</code> object as a
3301 * <code>java.io.Reader</code> object.
3302 * It is intended for use when
3303 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
3304 * and <code>LONGNVARCHAR</code> columns.
3305 *
3306 * @return a <code>java.io.Reader</code> object that contains the column
3307 * value; if the value is SQL <code>NULL</code>, the value returned is
3308 * <code>null</code> in the Java programming language.
3309 * @param columnIndex the first column is 1, the second is 2, ...
3310 * @exception SQLException if the columnIndex is not valid;
3311 * if a database access error occurs
3312 * or this method is called on a closed result set
3313 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3314 * this method
3315 * @since 1.6
3316 */
3317 java.io.Reader getNCharacterStream(int columnIndex) throws SQLException;
3318
3319 /**
3320 * Retrieves the value of the designated column in the current row
3321 * of this <code>ResultSet</code> object as a
3322 * <code>java.io.Reader</code> object.
3323 * It is intended for use when
3324 * accessing <code>NCHAR</code>,<code>NVARCHAR</code>
3325 * and <code>LONGNVARCHAR</code> columns.
3326 *
3327 * @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
3328 * @return a <code>java.io.Reader</code> object that contains the column
3329 * value; if the value is SQL <code>NULL</code>, the value returned is
3330 * <code>null</code> in the Java programming language
3331 * @exception SQLException if the columnLabel is not valid;
3332 * if a database access error occurs
3333 * or this method is called on a closed result set
3334 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3335 * this method
3336 * @since 1.6
3337 */
3338 java.io.Reader getNCharacterStream(String columnLabel) throws SQLException;
3339
3340 /**
3341 * Updates the designated column with a character stream value, which will have
3342 * the specified number of bytes. The
3343 * driver does the necessary conversion from Java character format to
3344 * the national character set in the database.
3345 * It is intended for use when
3346 * updating <code>NCHAR</code>,<code>NVARCHAR</code>
3347 * and <code>LONGNVARCHAR</code> columns.
3348 * <p>
3349 * The updater methods are used to update column values in the
3350 * current row or the insert row. The updater methods do not
3351 * update the underlying database; instead the <code>updateRow</code> or
3352 * <code>insertRow</code> methods are called to update the database.
3353 *
3354 * @param columnIndex the first column is 1, the second is 2, ...
3355 * @param x the new column value
3356 * @param length the length of the stream
3357 * @exception SQLException if the columnIndex is not valid;
3358 * if a database access error occurs;
3359 * the result set concurrency is <code>CONCUR_READ_ONLY</code> or this method is called on a closed result set
3360 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3361 * this method
3362 * @since 1.6
3363 */
3364 void updateNCharacterStream(int columnIndex,
3365 java.io.Reader x,
3366 long length) throws SQLException;
3367
3368 /**
3369 * Updates the designated column with a character stream value, which will have
3370 * the specified number of bytes. The
3371 * driver does the necessary conversion from Java character format to
3372 * the national character set in the database.
3373 * It is intended for use when
3374 * updating <code>NCHAR</code>,<code>NVARCHAR</code>
3375 * and <code>LONGNVARCHAR</code> columns.
3376 * <p>
3377 * The updater methods are used to update column values in the
3378 * current row or the insert row. The updater methods do not
3379 * update the underlying database; instead the <code>updateRow</code> or
3380 * <code>insertRow</code> methods are called to update the database.
3381 *
3382 * @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
3383 * @param reader the <code>java.io.Reader</code> object containing
3384 * the new column value
3385 * @param length the length of the stream
3386 * @exception SQLException if the columnLabel is not valid;
3387 * if a database access error occurs;
3388 * the result set concurrency is <code>CONCUR_READ_ONLY</code> or this method is called on a closed result set
3389 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3390 * this method
3391 * @since 1.6
3392 */
3393 void updateNCharacterStream(String columnLabel,
3394 java.io.Reader reader,
3395 long length) throws SQLException;
3396 /**
3397 * Updates the designated column with an ascii stream value, which will have
3398 * the specified number of bytes.
3399 * <p>
3400 * The updater methods are used to update column values in the
3401 * current row or the insert row. The updater methods do not
3402 * update the underlying database; instead the <code>updateRow</code> or
3403 * <code>insertRow</code> methods are called to update the database.
3404 *
3405 * @param columnIndex the first column is 1, the second is 2, ...
3406 * @param x the new column value
3407 * @param length the length of the stream
3408 * @exception SQLException if the columnIndex is not valid;
3409 * if a database access error occurs;
3410 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3411 * or this method is called on a closed result set
3412 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3413 * this method
3414 * @since 1.6
3415 */
3416 void updateAsciiStream(int columnIndex,
3417 java.io.InputStream x,
3418 long length) throws SQLException;
3419
3420 /**
3421 * Updates the designated column with a binary stream value, which will have
3422 * the specified number of bytes.
3423 * <p>
3424 * The updater methods are used to update column values in the
3425 * current row or the insert row. The updater methods do not
3426 * update the underlying database; instead the <code>updateRow</code> or
3427 * <code>insertRow</code> methods are called to update the database.
3428 *
3429 * @param columnIndex the first column is 1, the second is 2, ...
3430 * @param x the new column value
3431 * @param length the length of the stream
3432 * @exception SQLException if the columnIndex is not valid;
3433 * if a database access error occurs;
3434 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3435 * or this method is called on a closed result set
3436 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3437 * this method
3438 * @since 1.6
3439 */
3440 void updateBinaryStream(int columnIndex,
3441 java.io.InputStream x,
3442 long length) throws SQLException;
3443
3444 /**
3445 * Updates the designated column with a character stream value, which will have
3446 * the specified number of bytes.
3447 * <p>
3448 * The updater methods are used to update column values in the
3449 * current row or the insert row. The updater methods do not
3450 * update the underlying database; instead the <code>updateRow</code> or
3451 * <code>insertRow</code> methods are called to update the database.
3452 *
3453 * @param columnIndex the first column is 1, the second is 2, ...
3454 * @param x the new column value
3455 * @param length the length of the stream
3456 * @exception SQLException if the columnIndex is not valid;
3457 * if a database access error occurs;
3458 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3459 * or this method is called on a closed result set
3460 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3461 * this method
3462 * @since 1.6
3463 */
3464 void updateCharacterStream(int columnIndex,
3465 java.io.Reader x,
3466 long length) throws SQLException;
3467 /**
3468 * Updates the designated column with an ascii stream value, which will have
3469 * the specified number of bytes.
3470 * <p>
3471 * The updater methods are used to update column values in the
3472 * current row or the insert row. The updater methods do not
3473 * update the underlying database; instead the <code>updateRow</code> or
3474 * <code>insertRow</code> methods are called to update the database.
3475 *
3476 * @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
3477 * @param x the new column value
3478 * @param length the length of the stream
3479 * @exception SQLException if the columnLabel is not valid;
3480 * if a database access error occurs;
3481 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3482 * or this method is called on a closed result set
3483 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3484 * this method
3485 * @since 1.6
3486 */
3487 void updateAsciiStream(String columnLabel,
3488 java.io.InputStream x,
3489 long length) throws SQLException;
3490
3491 /**
3492 * Updates the designated column with a binary stream value, which will have
3493 * the specified number of bytes.
3494 * <p>
3495 * The updater methods are used to update column values in the
3496 * current row or the insert row. The updater methods do not
3497 * update the underlying database; instead the <code>updateRow</code> or
3498 * <code>insertRow</code> methods are called to update the database.
3499 *
3500 * @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
3501 * @param x the new column value
3502 * @param length the length of the stream
3503 * @exception SQLException if the columnLabel is not valid;
3504 * if a database access error occurs;
3505 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3506 * or this method is called on a closed result set
3507 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3508 * this method
3509 * @since 1.6
3510 */
3511 void updateBinaryStream(String columnLabel,
3512 java.io.InputStream x,
3513 long length) throws SQLException;
3514
3515 /**
3516 * Updates the designated column with a character stream value, which will have
3517 * the specified number of bytes.
3518 * <p>
3519 * The updater methods are used to update column values in the
3520 * current row or the insert row. The updater methods do not
3521 * update the underlying database; instead the <code>updateRow</code> or
3522 * <code>insertRow</code> methods are called to update the database.
3523 *
3524 * @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
3525 * @param reader the <code>java.io.Reader</code> object containing
3526 * the new column value
3527 * @param length the length of the stream
3528 * @exception SQLException if the columnLabel is not valid;
3529 * if a database access error occurs;
3530 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3531 * or this method is called on a closed result set
3532 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3533 * this method
3534 * @since 1.6
3535 */
3536 void updateCharacterStream(String columnLabel,
3537 java.io.Reader reader,
3538 long length) throws SQLException;
3539 /**
3540 * Updates the designated column using the given input stream, which
3541 * will have the specified number of bytes.
3542 *
3543 * <p>
3544 * The updater methods are used to update column values in the
3545 * current row or the insert row. The updater methods do not
3546 * update the underlying database; instead the <code>updateRow</code> or
3547 * <code>insertRow</code> methods are called to update the database.
3548 *
3549 * @param columnIndex the first column is 1, the second is 2, ...
3550 * @param inputStream An object that contains the data to set the parameter
3551 * value to.
3552 * @param length the number of bytes in the parameter data.
3553 * @exception SQLException if the columnIndex is not valid;
3554 * if a database access error occurs;
3555 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3556 * or this method is called on a closed result set
3557 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3558 * this method
3559 * @since 1.6
3560 */
3561 void updateBlob(int columnIndex, InputStream inputStream, long length) throws SQLException;
3562
3563 /**
3564 * Updates the designated column using the given input stream, which
3565 * will have the specified number of bytes.
3566 *
3567 * <p>
3568 * The updater methods are used to update column values in the
3569 * current row or the insert row. The updater methods do not
3570 * update the underlying database; instead the <code>updateRow</code> or
3571 * <code>insertRow</code> methods are called to update the database.
3572 *
3573 * @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
3574 * @param inputStream An object that contains the data to set the parameter
3575 * value to.
3576 * @param length the number of bytes in the parameter data.
3577 * @exception SQLException if the columnLabel is not valid;
3578 * if a database access error occurs;
3579 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3580 * or this method is called on a closed result set
3581 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3582 * this method
3583 * @since 1.6
3584 */
3585 void updateBlob(String columnLabel, InputStream inputStream, long length) throws SQLException;
3586
3587 /**
3588 * Updates the designated column using the given <code>Reader</code>
3589 * object, which is the given number of characters long.
3590 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
3591 * parameter, it may be more practical to send it via a
3592 * <code>java.io.Reader</code> object. The JDBC driver will
3593 * do any necessary conversion from UNICODE to the database char format.
3594 *
3595 * <p>
3596 * The updater methods are used to update column values in the
3597 * current row or the insert row. The updater methods do not
3598 * update the underlying database; instead the <code>updateRow</code> or
3599 * <code>insertRow</code> methods are called to update the database.
3600 *
3601 * @param columnIndex the first column is 1, the second is 2, ...
3602 * @param reader An object that contains the data to set the parameter value to.
3603 * @param length the number of characters in the parameter data.
3604 * @exception SQLException if the columnIndex is not valid;
3605 * if a database access error occurs;
3606 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3607 * or this method is called on a closed result set
3608 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3609 * this method
3610 * @since 1.6
3611 */
3612 void updateClob(int columnIndex, Reader reader, long length) throws SQLException;
3613
3614 /**
3615 * Updates the designated column using the given <code>Reader</code>
3616 * object, which is the given number of characters long.
3617 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
3618 * parameter, it may be more practical to send it via a
3619 * <code>java.io.Reader</code> object. The JDBC driver will
3620 * do any necessary conversion from UNICODE to the database char format.
3621 *
3622 * <p>
3623 * The updater methods are used to update column values in the
3624 * current row or the insert row. The updater methods do not
3625 * update the underlying database; instead the <code>updateRow</code> or
3626 * <code>insertRow</code> methods are called to update the database.
3627 *
3628 * @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
3629 * @param reader An object that contains the data to set the parameter value to.
3630 * @param length the number of characters in the parameter data.
3631 * @exception SQLException if the columnLabel is not valid;
3632 * if a database access error occurs;
3633 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3634 * or this method is called on a closed result set
3635 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3636 * this method
3637 * @since 1.6
3638 */
3639 void updateClob(String columnLabel, Reader reader, long length) throws SQLException;
3640 /**
3641 * Updates the designated column using the given <code>Reader</code>
3642 * object, which is the given number of characters long.
3643 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
3644 * parameter, it may be more practical to send it via a
3645 * <code>java.io.Reader</code> object. The JDBC driver will
3646 * do any necessary conversion from UNICODE to the database char format.
3647 *
3648 * <p>
3649 * The updater methods are used to update column values in the
3650 * current row or the insert row. The updater methods do not
3651 * update the underlying database; instead the <code>updateRow</code> or
3652 * <code>insertRow</code> methods are called to update the database.
3653 *
3654 * @param columnIndex the first column is 1, the second 2, ...
3655 * @param reader An object that contains the data to set the parameter value to.
3656 * @param length the number of characters in the parameter data.
3657 * @throws SQLException if the columnIndex is not valid;
3658 * if the driver does not support national
3659 * character sets; if the driver can detect that a data conversion
3660 * error could occur; this method is called on a closed result set,
3661 * if a database access error occurs or
3662 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3663 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3664 * this method
3665 * @since 1.6
3666 */
3667 void updateNClob(int columnIndex, Reader reader, long length) throws SQLException;
3668
3669 /**
3670 * Updates the designated column using the given <code>Reader</code>
3671 * object, which is the given number of characters long.
3672 * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>
3673 * parameter, it may be more practical to send it via a
3674 * <code>java.io.Reader</code> object. The JDBC driver will
3675 * do any necessary conversion from UNICODE to the database char format.
3676 *
3677 * <p>
3678 * The updater methods are used to update column values in the
3679 * current row or the insert row. The updater methods do not
3680 * update the underlying database; instead the <code>updateRow</code> or
3681 * <code>insertRow</code> methods are called to update the database.
3682 *
3683 * @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
3684 * @param reader An object that contains the data to set the parameter value to.
3685 * @param length the number of characters in the parameter data.
3686 * @throws SQLException if the columnLabel is not valid;
3687 * if the driver does not support national
3688 * character sets; if the driver can detect that a data conversion
3689 * error could occur; this method is called on a closed result set;
3690 * if a database access error occurs or
3691 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3692 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3693 * this method
3694 * @since 1.6
3695 */
3696 void updateNClob(String columnLabel, Reader reader, long length) throws SQLException;
3697
3698 //---
3699
3700 /**
3701 * Updates the designated column with a character stream value.
3702 * The data will be read from the stream
3703 * as needed until end-of-stream is reached. The
3704 * driver does the necessary conversion from Java character format to
3705 * the national character set in the database.
3706 * It is intended for use when
3707 * updating <code>NCHAR</code>,<code>NVARCHAR</code>
3708 * and <code>LONGNVARCHAR</code> columns.
3709 * <p>
3710 * The updater methods are used to update column values in the
3711 * current row or the insert row. The updater methods do not
3712 * update the underlying database; instead the <code>updateRow</code> or
3713 * <code>insertRow</code> methods are called to update the database.
3714 *
3715 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3716 * it might be more efficient to use a version of
3717 * <code>updateNCharacterStream</code> which takes a length parameter.
3718 *
3719 * @param columnIndex the first column is 1, the second is 2, ...
3720 * @param x the new column value
3721 * @exception SQLException if the columnIndex is not valid;
3722 * if a database access error occurs;
3723 * the result set concurrency is <code>CONCUR_READ_ONLY</code> or this method is called on a closed result set
3724 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3725 * this method
3726 * @since 1.6
3727 */
3728 void updateNCharacterStream(int columnIndex,
3729 java.io.Reader x) throws SQLException;
3730
3731 /**
3732 * Updates the designated column with a character stream value.
3733 * The data will be read from the stream
3734 * as needed until end-of-stream is reached. The
3735 * driver does the necessary conversion from Java character format to
3736 * the national character set in the database.
3737 * It is intended for use when
3738 * updating <code>NCHAR</code>,<code>NVARCHAR</code>
3739 * and <code>LONGNVARCHAR</code> columns.
3740 * <p>
3741 * The updater methods are used to update column values in the
3742 * current row or the insert row. The updater methods do not
3743 * update the underlying database; instead the <code>updateRow</code> or
3744 * <code>insertRow</code> methods are called to update the database.
3745 *
3746 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3747 * it might be more efficient to use a version of
3748 * <code>updateNCharacterStream</code> which takes a length parameter.
3749 *
3750 * @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
3751 * @param reader the <code>java.io.Reader</code> object containing
3752 * the new column value
3753 * @exception SQLException if the columnLabel is not valid;
3754 * if a database access error occurs;
3755 * the result set concurrency is <code>CONCUR_READ_ONLY</code> or this method is called on a closed result set
3756 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3757 * this method
3758 * @since 1.6
3759 */
3760 void updateNCharacterStream(String columnLabel,
3761 java.io.Reader reader) throws SQLException;
3762 /**
3763 * Updates the designated column with an ascii stream value.
3764 * The data will be read from the stream
3765 * as needed until end-of-stream is reached.
3766 * <p>
3767 * The updater methods are used to update column values in the
3768 * current row or the insert row. The updater methods do not
3769 * update the underlying database; instead the <code>updateRow</code> or
3770 * <code>insertRow</code> methods are called to update the database.
3771 *
3772 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3773 * it might be more efficient to use a version of
3774 * <code>updateAsciiStream</code> which takes a length parameter.
3775 *
3776 * @param columnIndex the first column is 1, the second is 2, ...
3777 * @param x the new column value
3778 * @exception SQLException if the columnIndex is not valid;
3779 * if a database access error occurs;
3780 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3781 * or this method is called on a closed result set
3782 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3783 * this method
3784 * @since 1.6
3785 */
3786 void updateAsciiStream(int columnIndex,
3787 java.io.InputStream x) throws SQLException;
3788
3789 /**
3790 * Updates the designated column with a binary stream value.
3791 * The data will be read from the stream
3792 * as needed until end-of-stream is reached.
3793 * <p>
3794 * The updater methods are used to update column values in the
3795 * current row or the insert row. The updater methods do not
3796 * update the underlying database; instead the <code>updateRow</code> or
3797 * <code>insertRow</code> methods are called to update the database.
3798 *
3799 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3800 * it might be more efficient to use a version of
3801 * <code>updateBinaryStream</code> which takes a length parameter.
3802 *
3803 * @param columnIndex the first column is 1, the second is 2, ...
3804 * @param x the new column value
3805 * @exception SQLException if the columnIndex is not valid;
3806 * if a database access error occurs;
3807 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3808 * or this method is called on a closed result set
3809 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3810 * this method
3811 * @since 1.6
3812 */
3813 void updateBinaryStream(int columnIndex,
3814 java.io.InputStream x) throws SQLException;
3815
3816 /**
3817 * Updates the designated column with a character stream value.
3818 * The data will be read from the stream
3819 * as needed until end-of-stream is reached.
3820 * <p>
3821 * The updater methods are used to update column values in the
3822 * current row or the insert row. The updater methods do not
3823 * update the underlying database; instead the <code>updateRow</code> or
3824 * <code>insertRow</code> methods are called to update the database.
3825 *
3826 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3827 * it might be more efficient to use a version of
3828 * <code>updateCharacterStream</code> which takes a length parameter.
3829 *
3830 * @param columnIndex the first column is 1, the second is 2, ...
3831 * @param x the new column value
3832 * @exception SQLException if the columnIndex is not valid;
3833 * if a database access error occurs;
3834 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3835 * or this method is called on a closed result set
3836 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3837 * this method
3838 * @since 1.6
3839 */
3840 void updateCharacterStream(int columnIndex,
3841 java.io.Reader x) throws SQLException;
3842 /**
3843 * Updates the designated column with an ascii stream value.
3844 * The data will be read from the stream
3845 * as needed until end-of-stream is reached.
3846 * <p>
3847 * The updater methods are used to update column values in the
3848 * current row or the insert row. The updater methods do not
3849 * update the underlying database; instead the <code>updateRow</code> or
3850 * <code>insertRow</code> methods are called to update the database.
3851 *
3852 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3853 * it might be more efficient to use a version of
3854 * <code>updateAsciiStream</code> which takes a length parameter.
3855 *
3856 * @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
3857 * @param x the new column value
3858 * @exception SQLException if the columnLabel is not valid;
3859 * if a database access error occurs;
3860 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3861 * or this method is called on a closed result set
3862 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3863 * this method
3864 * @since 1.6
3865 */
3866 void updateAsciiStream(String columnLabel,
3867 java.io.InputStream x) throws SQLException;
3868
3869 /**
3870 * Updates the designated column with a binary stream value.
3871 * The data will be read from the stream
3872 * as needed until end-of-stream is reached.
3873 * <p>
3874 * The updater methods are used to update column values in the
3875 * current row or the insert row. The updater methods do not
3876 * update the underlying database; instead the <code>updateRow</code> or
3877 * <code>insertRow</code> methods are called to update the database.
3878 *
3879 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3880 * it might be more efficient to use a version of
3881 * <code>updateBinaryStream</code> which takes a length parameter.
3882 *
3883 * @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
3884 * @param x the new column value
3885 * @exception SQLException if the columnLabel is not valid;
3886 * if a database access error occurs;
3887 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3888 * or this method is called on a closed result set
3889 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3890 * this method
3891 * @since 1.6
3892 */
3893 void updateBinaryStream(String columnLabel,
3894 java.io.InputStream x) throws SQLException;
3895
3896 /**
3897 * Updates the designated column with a character stream value.
3898 * The data will be read from the stream
3899 * as needed until end-of-stream is reached.
3900 * <p>
3901 * The updater methods are used to update column values in the
3902 * current row or the insert row. The updater methods do not
3903 * update the underlying database; instead the <code>updateRow</code> or
3904 * <code>insertRow</code> methods are called to update the database.
3905 *
3906 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3907 * it might be more efficient to use a version of
3908 * <code>updateCharacterStream</code> which takes a length parameter.
3909 *
3910 * @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
3911 * @param reader the <code>java.io.Reader</code> object containing
3912 * the new column value
3913 * @exception SQLException if the columnLabel is not valid; if a database access error occurs;
3914 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3915 * or this method is called on a closed result set
3916 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3917 * this method
3918 * @since 1.6
3919 */
3920 void updateCharacterStream(String columnLabel,
3921 java.io.Reader reader) throws SQLException;
3922 /**
3923 * Updates the designated column using the given input stream. The data will be read from the stream
3924 * as needed until end-of-stream is reached.
3925 * <p>
3926 * The updater methods are used to update column values in the
3927 * current row or the insert row. The updater methods do not
3928 * update the underlying database; instead the <code>updateRow</code> or
3929 * <code>insertRow</code> methods are called to update the database.
3930 *
3931 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3932 * it might be more efficient to use a version of
3933 * <code>updateBlob</code> which takes a length parameter.
3934 *
3935 * @param columnIndex the first column is 1, the second is 2, ...
3936 * @param inputStream An object that contains the data to set the parameter
3937 * value to.
3938 * @exception SQLException if the columnIndex is not valid; if a database access error occurs;
3939 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3940 * or this method is called on a closed result set
3941 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3942 * this method
3943 * @since 1.6
3944 */
3945 void updateBlob(int columnIndex, InputStream inputStream) throws SQLException;
3946
3947 /**
3948 * Updates the designated column using the given input stream. The data will be read from the stream
3949 * as needed until end-of-stream is reached.
3950 * <p>
3951 * The updater methods are used to update column values in the
3952 * current row or the insert row. The updater methods do not
3953 * update the underlying database; instead the <code>updateRow</code> or
3954 * <code>insertRow</code> methods are called to update the database.
3955 *
3956 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3957 * it might be more efficient to use a version of
3958 * <code>updateBlob</code> which takes a length parameter.
3959 *
3960 * @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
3961 * @param inputStream An object that contains the data to set the parameter
3962 * value to.
3963 * @exception SQLException if the columnLabel is not valid; if a database access error occurs;
3964 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3965 * or this method is called on a closed result set
3966 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3967 * this method
3968 * @since 1.6
3969 */
3970 void updateBlob(String columnLabel, InputStream inputStream) throws SQLException;
3971
3972 /**
3973 * Updates the designated column using the given <code>Reader</code>
3974 * object.
3975 * The data will be read from the stream
3976 * as needed until end-of-stream is reached. The JDBC driver will
3977 * do any necessary conversion from UNICODE to the database char format.
3978 *
3979 * <p>
3980 * The updater methods are used to update column values in the
3981 * current row or the insert row. The updater methods do not
3982 * update the underlying database; instead the <code>updateRow</code> or
3983 * <code>insertRow</code> methods are called to update the database.
3984 *
3985 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
3986 * it might be more efficient to use a version of
3987 * <code>updateClob</code> which takes a length parameter.
3988 *
3989 * @param columnIndex the first column is 1, the second is 2, ...
3990 * @param reader An object that contains the data to set the parameter value to.
3991 * @exception SQLException if the columnIndex is not valid;
3992 * if a database access error occurs;
3993 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
3994 * or this method is called on a closed result set
3995 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
3996 * this method
3997 * @since 1.6
3998 */
3999 void updateClob(int columnIndex, Reader reader) throws SQLException;
4000
4001 /**
4002 * Updates the designated column using the given <code>Reader</code>
4003 * object.
4004 * The data will be read from the stream
4005 * as needed until end-of-stream is reached. The JDBC driver will
4006 * do any necessary conversion from UNICODE to the database char format.
4007 *
4008 * <p>
4009 * The updater methods are used to update column values in the
4010 * current row or the insert row. The updater methods do not
4011 * update the underlying database; instead the <code>updateRow</code> or
4012 * <code>insertRow</code> methods are called to update the database.
4013 *
4014 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
4015 * it might be more efficient to use a version of
4016 * <code>updateClob</code> which takes a length parameter.
4017 *
4018 * @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
4019 * @param reader An object that contains the data to set the parameter value to.
4020 * @exception SQLException if the columnLabel is not valid; if a database access error occurs;
4021 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
4022 * or this method is called on a closed result set
4023 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4024 * this method
4025 * @since 1.6
4026 */
4027 void updateClob(String columnLabel, Reader reader) throws SQLException;
4028 /**
4029 * Updates the designated column using the given <code>Reader</code>
4030 *
4031 * The data will be read from the stream
4032 * as needed until end-of-stream is reached. The JDBC driver will
4033 * do any necessary conversion from UNICODE to the database char format.
4034 *
4035 * <p>
4036 * The updater methods are used to update column values in the
4037 * current row or the insert row. The updater methods do not
4038 * update the underlying database; instead the <code>updateRow</code> or
4039 * <code>insertRow</code> methods are called to update the database.
4040 *
4041 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
4042 * it might be more efficient to use a version of
4043 * <code>updateNClob</code> which takes a length parameter.
4044 *
4045 * @param columnIndex the first column is 1, the second 2, ...
4046 * @param reader An object that contains the data to set the parameter value to.
4047 * @throws SQLException if the columnIndex is not valid;
4048 * if the driver does not support national
4049 * character sets; if the driver can detect that a data conversion
4050 * error could occur; this method is called on a closed result set,
4051 * if a database access error occurs or
4052 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
4053 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4054 * this method
4055 * @since 1.6
4056 */
4057 void updateNClob(int columnIndex, Reader reader) throws SQLException;
4058
4059 /**
4060 * Updates the designated column using the given <code>Reader</code>
4061 * object.
4062 * The data will be read from the stream
4063 * as needed until end-of-stream is reached. The JDBC driver will
4064 * do any necessary conversion from UNICODE to the database char format.
4065 *
4066 * <p>
4067 * The updater methods are used to update column values in the
4068 * current row or the insert row. The updater methods do not
4069 * update the underlying database; instead the <code>updateRow</code> or
4070 * <code>insertRow</code> methods are called to update the database.
4071 *
4072 * <P><B>Note:</B> Consult your JDBC driver documentation to determine if
4073 * it might be more efficient to use a version of
4074 * <code>updateNClob</code> which takes a length parameter.
4075 *
4076 * @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
4077 * @param reader An object that contains the data to set the parameter value to.
4078 * @throws SQLException if the columnLabel is not valid; if the driver does not support national
4079 * character sets; if the driver can detect that a data conversion
4080 * error could occur; this method is called on a closed result set;
4081 * if a database access error occurs or
4082 * the result set concurrency is <code>CONCUR_READ_ONLY</code>
4083 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
4084 * this method
4085 * @since 1.6
4086 */
4087 void updateNClob(String columnLabel, Reader reader) throws SQLException;
4088
4089 //------------------------- JDBC 4.1 -----------------------------------
4090
4091
4092 /**
4093 *<p>Retrieves the value of the designated column in the current row
4094 * of this <code>ResultSet</code> object and will convert from the
4095 * SQL type of the column to the requested Java data type, if the
4096 * conversion is supported. If the conversion is not
4097 * supported or null is specified for the type, a
4098 * <code>SQLException</code> is thrown.
4099 *<p>
4100 * At a minimum, an implementation must support the conversions defined in
4101 * Appendix B, Table B-3 and conversion of appropriate user defined SQL
4102 * types to a Java type which implements {@code SQLData}, or {@code Struct}.
4103 * Additional conversions may be supported and are vendor defined.
4104 *
4105 * @param columnIndex the first column is 1, the second is 2, ...
4106 * @param type Class representing the Java data type to convert the designated
4107 * column to.
4108 * @return an instance of {@code type} holding the column value
4109 * @throws SQLException if conversion is not supported, type is null or
4110 * another error occurs. The getCause() method of the
4111 * exception may provide a more detailed exception, for example, if
4112 * a conversion error occurs
4113 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support
4114 * this method
4115 * @since 1.7
4116 */
4117 public <T> T getObject(int columnIndex, Class<T> type) throws SQLException;
4118
4119
4120 /**
4121 *<p>Retrieves the value of the designated column in the current row
4122 * of this <code>ResultSet</code> object and will convert from the
4123 * SQL type of the column to the requested Java data type, if the
4124 * conversion is supported. If the conversion is not
4125 * supported or null is specified for the type, a
4126 * <code>SQLException</code> is thrown.
4127 *<p>
4128 * At a minimum, an implementation must support the conversions defined in
4129 * Appendix B, Table B-3 and conversion of appropriate user defined SQL
4130 * types to a Java type which implements {@code SQLData}, or {@code Struct}.
4131 * Additional conversions may be supported and are vendor defined.
4132 *
4133 * @param columnLabel the label for the column specified with the SQL AS clause.
4134 * If the SQL AS clause was not specified, then the label is the name
4135 * of the column
4136 * @param type Class representing the Java data type to convert the designated
4137 * column to.
4138 * @return an instance of {@code type} holding the column value
4139 * @throws SQLException if conversion is not supported, type is null or
4140 * another error occurs. The getCause() method of the
4141 * exception may provide a more detailed exception, for example, if
4142 * a conversion error occurs
4143 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support
4144 * this method
4145 * @since 1.7
4146 */
4147 public <T> T getObject(String columnLabel, Class<T> type) throws SQLException;
4148
4149 //------------------------- JDBC 4.2 -----------------------------------
4150
4151 /**
4152 * Updates the designated column with an {@code Object} value.
4153 *
4154 * The updater methods are used to update column values in the
4155 * current row or the insert row. The updater methods do not
4156 * update the underlying database; instead the {@code updateRow} or
4157 * {@code insertRow} methods are called to update the database.
4158 *<p>
4159 * If the second argument is an {@code InputStream} then the stream must contain
4160 * the number of bytes specified by scaleOrLength. If the second argument is a
4161 * {@code Reader} then the reader must contain the number of characters specified
4162 * by scaleOrLength. If these conditions are not true the driver will generate a
4163 * {@code SQLException} when the statement is executed.
4164 *<p>
4165 * The default implementation will throw {@code SQLFeatureNotSupportedException}
4166 *
4167 * @param columnIndex the first column is 1, the second is 2, ...
4168 * @param x the new column value
4169 * @param targetSqlType the SQL type to be sent to the database
4170 * @param scaleOrLength for an object of {@code java.math.BigDecimal} ,
4171 * this is the number of digits after the decimal point. For
4172 * Java Object types {@code InputStream} and {@code Reader},
4173 * this is the length
4174 * of the data in the stream or reader. For all other types,
4175 * this value will be ignored.
4176 * @exception SQLException if the columnIndex is not valid;
4177 * if a database access error occurs;
4178 * the result set concurrency is {@code CONCUR_READ_ONLY}
4179 * or this method is called on a closed result set
4180 * @exception SQLFeatureNotSupportedException if the JDBC driver does not
4181 * support this method; if the JDBC driver does not support this data type
4182 * @see JDBCType
4183 * @see SQLType
4184 * @since 1.8
4185 */
4186 default void updateObject(int columnIndex, Object x,
4187 SQLType targetSqlType, int scaleOrLength) throws SQLException {
4188 throw new SQLFeatureNotSupportedException("updateObject not implemented");
4189 }
4190
4191 /**
4192 * Updates the designated column with an {@code Object} value.
4193 *
4194 * The updater methods are used to update column values in the
4195 * current row or the insert row. The updater methods do not
4196 * update the underlying database; instead the {@code updateRow} or
4197 * {@code insertRow} methods are called to update the database.
4198 *<p>
4199 * If the second argument is an {@code InputStream} then the stream must
4200 * contain number of bytes specified by scaleOrLength. If the second
4201 * argument is a {@code Reader} then the reader must contain the number
4202 * of characters specified by scaleOrLength. If these conditions are not
4203 * true the driver will generate a
4204 * {@code SQLException} when the statement is executed.
4205 *<p>
4206 * The default implementation will throw {@code SQLFeatureNotSupportedException}
4207 *
4208 * @param columnLabel the label for the column specified with the SQL AS
4209 * clause. If the SQL AS clause was not specified, then the label is
4210 * the name of the column
4211 * @param targetSqlType the SQL type to be sent to the database
4212 * @param scaleOrLength for an object of {@code java.math.BigDecimal} ,
4213 * this is the number of digits after the decimal point. For
4214 * Java Object types {@code InputStream} and {@code Reader},
4215 * this is the length
4216 * of the data in the stream or reader. For all other types,
4217 * this value will be ignored.
4218 * @exception SQLException if the columnLabel is not valid;
4219 * if a database access error occurs;
4220 * the result set concurrency is {@code CONCUR_READ_ONLY}
4221 * or this method is called on a closed result set
4222 * @exception SQLFeatureNotSupportedException if the JDBC driver does not
4223 * support this method; if the JDBC driver does not support this data type
4224 * @see JDBCType
4225 * @see SQLType
4226 * @since 1.8
4227 */
4228 default void updateObject(String columnLabel, Object x,
4229 SQLType targetSqlType, int scaleOrLength) throws SQLException {
4230 throw new SQLFeatureNotSupportedException("updateObject not implemented");
4231 }
4232
4233 /**
4234 * Updates the designated column with an {@code Object} value.
4235 *
4236 * The updater methods are used to update column values in the
4237 * current row or the insert row. The updater methods do not
4238 * update the underlying database; instead the {@code updateRow} or
4239 * {@code insertRow} methods are called to update the database.
4240 *<p>
4241 * The default implementation will throw {@code SQLFeatureNotSupportedException}
4242 *
4243 * @param columnIndex the first column is 1, the second is 2, ...
4244 * @param x the new column value
4245 * @param targetSqlType the SQL type to be sent to the database
4246 * @exception SQLException if the columnIndex is not valid;
4247 * if a database access error occurs;
4248 * the result set concurrency is {@code CONCUR_READ_ONLY}
4249 * or this method is called on a closed result set
4250 * @exception SQLFeatureNotSupportedException if the JDBC driver does not
4251 * support this method; if the JDBC driver does not support this data type
4252 * @see JDBCType
4253 * @see SQLType
4254 * @since 1.8
4255 */
4256 default void updateObject(int columnIndex, Object x, SQLType targetSqlType)
4257 throws SQLException {
4258 throw new SQLFeatureNotSupportedException("updateObject not implemented");
4259 }
4260
4261 /**
4262 * Updates the designated column with an {@code Object} value.
4263 *
4264 * The updater methods are used to update column values in the
4265 * current row or the insert row. The updater methods do not
4266 * update the underlying database; instead the {@code updateRow} or
4267 * {@code insertRow} methods are called to update the database.
4268 *<p>
4269 * The default implementation will throw {@code SQLFeatureNotSupportedException}
4270 *
4271 * @param columnLabel the label for the column specified with the SQL AS
4272 * clause. If the SQL AS clause was not specified, then the label is
4273 * the name of the column
4274 * @param x the new column value
4275 * @param targetSqlType the SQL type to be sent to the database
4276 * @exception SQLException if the columnLabel is not valid;
4277 * if a database access error occurs;
4278 * the result set concurrency is {@code CONCUR_READ_ONLY}
4279 * or this method is called on a closed result set
4280 * @exception SQLFeatureNotSupportedException if the JDBC driver does not
4281 * support this method; if the JDBC driver does not support this data type
4282 * @see JDBCType
4283 * @see SQLType
4284 * @since 1.8
4285 */
4286 default void updateObject(String columnLabel, Object x,
4287 SQLType targetSqlType) throws SQLException {
4288 throw new SQLFeatureNotSupportedException("updateObject not implemented");
4289 }
4290 }