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