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