1 /*
2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.sql;
27
28 /**
29 * <P>The object used for executing a static SQL statement
30 * and returning the results it produces.
31 * <P>
32 * By default, only one <code>ResultSet</code> object per <code>Statement</code>
33 * object can be open at the same time. Therefore, if the reading of one
34 * <code>ResultSet</code> object is interleaved
35 * with the reading of another, each must have been generated by
36 * different <code>Statement</code> objects. All execution methods in the
37 * <code>Statement</code> interface implicitly close a statment's current
38 * <code>ResultSet</code> object if an open one exists.
39 *
40 * @see Connection#createStatement
41 * @see ResultSet
42 */
43 public interface Statement extends Wrapper, AutoCloseable {
44
45 /**
46 * Executes the given SQL statement, which returns a single
47 * <code>ResultSet</code> object.
48 *<p>
49 * <strong>Note:</strong>This method cannot be called on a
50 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
51 * @param sql an SQL statement to be sent to the database, typically a
52 * static SQL <code>SELECT</code> statement
53 * @return a <code>ResultSet</code> object that contains the data produced
54 * by the given query; never <code>null</code>
55 * @exception SQLException if a database access error occurs,
56 * this method is called on a closed <code>Statement</code>, the given
57 * SQL statement produces anything other than a single
58 * <code>ResultSet</code> object, the method is called on a
59 * <code>PreparedStatement</code> or <code>CallableStatement</code>
60 * @throws SQLTimeoutException when the driver has determined that the
61 * timeout value that was specified by the {@code setQueryTimeout}
62 * method has been exceeded and has at least attempted to cancel
63 * the currently running {@code Statement}
64 */
65 ResultSet executeQuery(String sql) throws SQLException;
66
67 /**
68 * Executes the given SQL statement, which may be an <code>INSERT</code>,
69 * <code>UPDATE</code>, or <code>DELETE</code> statement or an
70 * SQL statement that returns nothing, such as an SQL DDL statement.
71 *<p>
72 * <strong>Note:</strong>This method cannot be called on a
73 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
74 * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
75 * <code>DELETE</code>; or an SQL statement that returns nothing,
76 * such as a DDL statement.
77 *
78 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
79 * or (2) 0 for SQL statements that return nothing
80 *
81 * @exception SQLException if a database access error occurs,
82 * this method is called on a closed <code>Statement</code>, the given
83 * SQL statement produces a <code>ResultSet</code> object, the method is called on a
84 * <code>PreparedStatement</code> or <code>CallableStatement</code>
85 * @throws SQLTimeoutException when the driver has determined that the
86 * timeout value that was specified by the {@code setQueryTimeout}
87 * method has been exceeded and has at least attempted to cancel
88 * the currently running {@code Statement}
89 */
90 int executeUpdate(String sql) throws SQLException;
91
92 /**
93 * Releases this <code>Statement</code> object's database
94 * and JDBC resources immediately instead of waiting for
95 * this to happen when it is automatically closed.
96 * It is generally good practice to release resources as soon as
97 * you are finished with them to avoid tying up database
98 * resources.
99 * <P>
100 * Calling the method <code>close</code> on a <code>Statement</code>
101 * object that is already closed has no effect.
102 * <P>
103 * <B>Note:</B>When a <code>Statement</code> object is
104 * closed, its current <code>ResultSet</code> object, if one exists, is
105 * also closed.
106 *
107 * @exception SQLException if a database access error occurs
108 */
109 void close() throws SQLException;
110
111 //----------------------------------------------------------------------
112
113 /**
114 * Retrieves the maximum number of bytes that can be
115 * returned for character and binary column values in a <code>ResultSet</code>
116 * object produced by this <code>Statement</code> object.
117 * This limit applies only to <code>BINARY</code>, <code>VARBINARY</code>,
118 * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
119 * <code>NCHAR</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>
120 * and <code>LONGVARCHAR</code> columns. If the limit is exceeded, the
121 * excess data is silently discarded.
122 *
123 * @return the current column size limit for columns storing character and
124 * binary values; zero means there is no limit
125 * @exception SQLException if a database access error occurs or
126 * this method is called on a closed <code>Statement</code>
127 * @see #setMaxFieldSize
128 */
129 int getMaxFieldSize() throws SQLException;
130
131 /**
132 * Sets the limit for the maximum number of bytes that can be returned for
133 * character and binary column values in a <code>ResultSet</code>
134 * object produced by this <code>Statement</code> object.
135 *
136 * This limit applies
137 * only to <code>BINARY</code>, <code>VARBINARY</code>,
138 * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
139 * <code>NCHAR</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code> and
140 * <code>LONGVARCHAR</code> fields. If the limit is exceeded, the excess data
141 * is silently discarded. For maximum portability, use values
142 * greater than 256.
143 *
144 * @param max the new column size limit in bytes; zero means there is no limit
145 * @exception SQLException if a database access error occurs,
146 * this method is called on a closed <code>Statement</code>
147 * or the condition {@code max >= 0} is not satisfied
148 * @see #getMaxFieldSize
149 */
150 void setMaxFieldSize(int max) throws SQLException;
151
152 /**
153 * Retrieves the maximum number of rows that a
154 * <code>ResultSet</code> object produced by this
155 * <code>Statement</code> object can contain. If this limit is exceeded,
156 * the excess rows are silently dropped.
157 *
158 * @return the current maximum number of rows for a <code>ResultSet</code>
159 * object produced by this <code>Statement</code> object;
160 * zero means there is no limit
161 * @exception SQLException if a database access error occurs or
162 * this method is called on a closed <code>Statement</code>
163 * @see #setMaxRows
164 */
165 int getMaxRows() throws SQLException;
166
167 /**
168 * Sets the limit for the maximum number of rows that any
169 * <code>ResultSet</code> object generated by this <code>Statement</code>
170 * object can contain to the given number.
171 * If the limit is exceeded, the excess
172 * rows are silently dropped.
173 *
174 * @param max the new max rows limit; zero means there is no limit
175 * @exception SQLException if a database access error occurs,
176 * this method is called on a closed <code>Statement</code>
177 * or the condition {@code max >= 0} is not satisfied
178 * @see #getMaxRows
179 */
180 void setMaxRows(int max) throws SQLException;
181
182 /**
183 * Sets escape processing on or off.
184 * If escape scanning is on (the default), the driver will do
185 * escape substitution before sending the SQL statement to the database.
186 *<p>
187 * The {@code Connection} and {@code DataSource} property
188 * {@code escapeProcessing} may be used to change the default escape processing
189 * behavior. A value of true (the default) enables escape Processing for
190 * all {@code Statement} objects. A value of false disables escape processing
191 * for all {@code Statement} objects. The {@code setEscapeProcessing}
192 * method may be used to specify the escape processing behavior for an
193 * individual {@code Statement} object.
194 * <p>
195 * Note: Since prepared statements have usually been parsed prior
196 * to making this call, disabling escape processing for
197 * <code>PreparedStatements</code> objects will have no effect.
198 *
199 * @param enable <code>true</code> to enable escape processing;
200 * <code>false</code> to disable it
201 * @exception SQLException if a database access error occurs or
202 * this method is called on a closed <code>Statement</code>
203 */
204 void setEscapeProcessing(boolean enable) throws SQLException;
205
206 /**
207 * Retrieves the number of seconds the driver will
208 * wait for a <code>Statement</code> object to execute.
209 * If the limit is exceeded, a
210 * <code>SQLException</code> is thrown.
211 *
212 * @return the current query timeout limit in seconds; zero means there is
213 * no limit
214 * @exception SQLException if a database access error occurs or
215 * this method is called on a closed <code>Statement</code>
216 * @see #setQueryTimeout
217 */
218 int getQueryTimeout() throws SQLException;
219
220 /**
221 * Sets the number of seconds the driver will wait for a
222 * <code>Statement</code> object to execute to the given number of seconds.
223 *By default there is no limit on the amount of time allowed for a running
224 * statement to complete. If the limit is exceeded, an
225 * <code>SQLTimeoutException</code> is thrown.
226 * A JDBC driver must apply this limit to the <code>execute</code>,
227 * <code>executeQuery</code> and <code>executeUpdate</code> methods.
228 * <p>
229 * <strong>Note:</strong> JDBC driver implementations may also apply this
230 * limit to {@code ResultSet} methods
231 * (consult your driver vendor documentation for details).
232 * <p>
233 * <strong>Note:</strong> In the case of {@code Statement} batching, it is
234 * implementation defined as to whether the time-out is applied to
235 * individual SQL commands added via the {@code addBatch} method or to
236 * the entire batch of SQL commands invoked by the {@code executeBatch}
237 * method (consult your driver vendor documentation for details).
238 *
239 * @param seconds the new query timeout limit in seconds; zero means
240 * there is no limit
241 * @exception SQLException if a database access error occurs,
242 * this method is called on a closed <code>Statement</code>
243 * or the condition {@code seconds >= 0} is not satisfied
244 * @see #getQueryTimeout
245 */
246 void setQueryTimeout(int seconds) throws SQLException;
247
248 /**
249 * Cancels this <code>Statement</code> object if both the DBMS and
250 * driver support aborting an SQL statement.
251 * This method can be used by one thread to cancel a statement that
252 * is being executed by another thread.
253 *
254 * @exception SQLException if a database access error occurs or
255 * this method is called on a closed <code>Statement</code>
256 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
257 * this method
258 */
259 void cancel() throws SQLException;
260
261 /**
262 * Retrieves the first warning reported by calls on this <code>Statement</code> object.
263 * Subsequent <code>Statement</code> object warnings will be chained to this
264 * <code>SQLWarning</code> object.
265 *
266 * <p>The warning chain is automatically cleared each time
267 * a statement is (re)executed. This method may not be called on a closed
268 * <code>Statement</code> object; doing so will cause an <code>SQLException</code>
269 * to be thrown.
270 *
271 * <P><B>Note:</B> If you are processing a <code>ResultSet</code> object, any
272 * warnings associated with reads on that <code>ResultSet</code> object
273 * will be chained on it rather than on the <code>Statement</code>
274 * object that produced it.
275 *
276 * @return the first <code>SQLWarning</code> object or <code>null</code>
277 * if there are no warnings
278 * @exception SQLException if a database access error occurs or
279 * this method is called on a closed <code>Statement</code>
280 */
281 SQLWarning getWarnings() throws SQLException;
282
283 /**
284 * Clears all the warnings reported on this <code>Statement</code>
285 * object. After a call to this method,
286 * the method <code>getWarnings</code> will return
287 * <code>null</code> until a new warning is reported for this
288 * <code>Statement</code> object.
289 *
290 * @exception SQLException if a database access error occurs or
291 * this method is called on a closed <code>Statement</code>
292 */
293 void clearWarnings() throws SQLException;
294
295 /**
296 * Sets the SQL cursor name to the given <code>String</code>, which
297 * will be used by subsequent <code>Statement</code> object
298 * <code>execute</code> methods. This name can then be
299 * used in SQL positioned update or delete statements to identify the
300 * current row in the <code>ResultSet</code> object generated by this
301 * statement. If the database does not support positioned update/delete,
302 * this method is a noop. To insure that a cursor has the proper isolation
303 * level to support updates, the cursor's <code>SELECT</code> statement
304 * should have the form <code>SELECT FOR UPDATE</code>. If
305 * <code>FOR UPDATE</code> is not present, positioned updates may fail.
306 *
307 * <P><B>Note:</B> By definition, the execution of positioned updates and
308 * deletes must be done by a different <code>Statement</code> object than
309 * the one that generated the <code>ResultSet</code> object being used for
310 * positioning. Also, cursor names must be unique within a connection.
311 *
312 * @param name the new cursor name, which must be unique within
313 * a connection
314 * @exception SQLException if a database access error occurs or
315 * this method is called on a closed <code>Statement</code>
316 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
317 */
318 void setCursorName(String name) throws SQLException;
319
320 //----------------------- Multiple Results --------------------------
321
322 /**
323 * Executes the given SQL statement, which may return multiple results.
324 * In some (uncommon) situations, a single SQL statement may return
325 * multiple result sets and/or update counts. Normally you can ignore
326 * this unless you are (1) executing a stored procedure that you know may
327 * return multiple results or (2) you are dynamically executing an
328 * unknown SQL string.
329 * <P>
330 * The <code>execute</code> method executes an SQL statement and indicates the
331 * form of the first result. You must then use the methods
332 * <code>getResultSet</code> or <code>getUpdateCount</code>
333 * to retrieve the result, and <code>getMoreResults</code> to
334 * move to any subsequent result(s).
335 * <p>
336 *<strong>Note:</strong>This method cannot be called on a
337 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
338 * @param sql any SQL statement
339 * @return <code>true</code> if the first result is a <code>ResultSet</code>
340 * object; <code>false</code> if it is an update count or there are
341 * no results
342 * @exception SQLException if a database access error occurs,
343 * this method is called on a closed <code>Statement</code>,
344 * the method is called on a
345 * <code>PreparedStatement</code> or <code>CallableStatement</code>
346 * @throws SQLTimeoutException when the driver has determined that the
347 * timeout value that was specified by the {@code setQueryTimeout}
348 * method has been exceeded and has at least attempted to cancel
349 * the currently running {@code Statement}
350 * @see #getResultSet
351 * @see #getUpdateCount
352 * @see #getMoreResults
353 */
354 boolean execute(String sql) throws SQLException;
355
356 /**
357 * Retrieves the current result as a <code>ResultSet</code> object.
358 * This method should be called only once per result.
359 *
360 * @return the current result as a <code>ResultSet</code> object or
361 * <code>null</code> if the result is an update count or there are no more results
362 * @exception SQLException if a database access error occurs or
363 * this method is called on a closed <code>Statement</code>
364 * @see #execute
365 */
366 ResultSet getResultSet() throws SQLException;
367
368 /**
369 * Retrieves the current result as an update count;
370 * if the result is a <code>ResultSet</code> object or there are no more results, -1
371 * is returned. This method should be called only once per result.
372 *
373 * @return the current result as an update count; -1 if the current result is a
374 * <code>ResultSet</code> object or there are no more results
375 * @exception SQLException if a database access error occurs or
376 * this method is called on a closed <code>Statement</code>
377 * @see #execute
378 */
379 int getUpdateCount() throws SQLException;
380
381 /**
382 * Moves to this <code>Statement</code> object's next result, returns
383 * <code>true</code> if it is a <code>ResultSet</code> object, and
384 * implicitly closes any current <code>ResultSet</code>
385 * object(s) obtained with the method <code>getResultSet</code>.
386 *
387 * <P>There are no more results when the following is true:
388 * <PRE>{@code
389 * // stmt is a Statement object
390 * ((stmt.getMoreResults() == false) && (stmt.getUpdateCount() == -1))
391 * }</PRE>
392 *
393 * @return <code>true</code> if the next result is a <code>ResultSet</code>
394 * object; <code>false</code> if it is an update count or there are
395 * no more results
396 * @exception SQLException if a database access error occurs or
397 * this method is called on a closed <code>Statement</code>
398 * @see #execute
399 */
400 boolean getMoreResults() throws SQLException;
401
402
403 //--------------------------JDBC 2.0-----------------------------
404
405
406 /**
407 * Gives the driver a hint as to the direction in which
408 * rows will be processed in <code>ResultSet</code>
409 * objects created using this <code>Statement</code> object. The
410 * default value is <code>ResultSet.FETCH_FORWARD</code>.
411 * <P>
412 * Note that this method sets the default fetch direction for
413 * result sets generated by this <code>Statement</code> object.
414 * Each result set has its own methods for getting and setting
415 * its own fetch direction.
416 *
417 * @param direction the initial direction for processing rows
418 * @exception SQLException if a database access error occurs,
419 * this method is called on a closed <code>Statement</code>
420 * or the given direction
421 * is not one of <code>ResultSet.FETCH_FORWARD</code>,
422 * <code>ResultSet.FETCH_REVERSE</code>, or <code>ResultSet.FETCH_UNKNOWN</code>
423 * @since 1.2
424 * @see #getFetchDirection
425 */
426 void setFetchDirection(int direction) throws SQLException;
427
428 /**
429 * Retrieves the direction for fetching rows from
430 * database tables that is the default for result sets
431 * generated from this <code>Statement</code> object.
432 * If this <code>Statement</code> object has not set
433 * a fetch direction by calling the method <code>setFetchDirection</code>,
434 * the return value is implementation-specific.
435 *
436 * @return the default fetch direction for result sets generated
437 * from this <code>Statement</code> object
438 * @exception SQLException if a database access error occurs or
439 * this method is called on a closed <code>Statement</code>
440 * @since 1.2
441 * @see #setFetchDirection
442 */
443 int getFetchDirection() throws SQLException;
444
445 /**
446 * Gives the JDBC driver a hint as to the number of rows that should
447 * be fetched from the database when more rows are needed for
448 * <code>ResultSet</code> objects genrated by this <code>Statement</code>.
449 * If the value specified is zero, then the hint is ignored.
450 * The default value is zero.
451 *
452 * @param rows the number of rows to fetch
453 * @exception SQLException if a database access error occurs,
454 * this method is called on a closed <code>Statement</code> or the
455 * condition {@code rows >= 0} is not satisfied.
456 * @since 1.2
457 * @see #getFetchSize
458 */
459 void setFetchSize(int rows) throws SQLException;
460
461 /**
462 * Retrieves the number of result set rows that is the default
463 * fetch size for <code>ResultSet</code> objects
464 * generated from this <code>Statement</code> object.
465 * If this <code>Statement</code> object has not set
466 * a fetch size by calling the method <code>setFetchSize</code>,
467 * the return value is implementation-specific.
468 *
469 * @return the default fetch size for result sets generated
470 * from this <code>Statement</code> object
471 * @exception SQLException if a database access error occurs or
472 * this method is called on a closed <code>Statement</code>
473 * @since 1.2
474 * @see #setFetchSize
475 */
476 int getFetchSize() throws SQLException;
477
478 /**
479 * Retrieves the result set concurrency for <code>ResultSet</code> objects
480 * generated by this <code>Statement</code> object.
481 *
482 * @return either <code>ResultSet.CONCUR_READ_ONLY</code> or
483 * <code>ResultSet.CONCUR_UPDATABLE</code>
484 * @exception SQLException if a database access error occurs or
485 * this method is called on a closed <code>Statement</code>
486 * @since 1.2
487 */
488 int getResultSetConcurrency() throws SQLException;
489
490 /**
491 * Retrieves the result set type for <code>ResultSet</code> objects
492 * generated by this <code>Statement</code> object.
493 *
494 * @return one of <code>ResultSet.TYPE_FORWARD_ONLY</code>,
495 * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
496 * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
497 * @exception SQLException if a database access error occurs or
498 * this method is called on a closed <code>Statement</code>
499 * @since 1.2
500 */
501 int getResultSetType() throws SQLException;
502
503 /**
504 * Adds the given SQL command to the current list of commmands for this
505 * <code>Statement</code> object. The commands in this list can be
506 * executed as a batch by calling the method <code>executeBatch</code>.
507 * <P>
508 *<strong>Note:</strong>This method cannot be called on a
509 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
510 * @param sql typically this is a SQL <code>INSERT</code> or
511 * <code>UPDATE</code> statement
512 * @exception SQLException if a database access error occurs,
513 * this method is called on a closed <code>Statement</code>, the
514 * driver does not support batch updates, the method is called on a
515 * <code>PreparedStatement</code> or <code>CallableStatement</code>
516 * @see #executeBatch
517 * @see DatabaseMetaData#supportsBatchUpdates
518 * @since 1.2
519 */
520 void addBatch( String sql ) throws SQLException;
521
522 /**
523 * Empties this <code>Statement</code> object's current list of
524 * SQL commands.
525 * <P>
526 * @exception SQLException if a database access error occurs,
527 * this method is called on a closed <code>Statement</code> or the
528 * driver does not support batch updates
529 * @see #addBatch
530 * @see DatabaseMetaData#supportsBatchUpdates
531 * @since 1.2
532 */
533 void clearBatch() throws SQLException;
534
535 /**
536 * Submits a batch of commands to the database for execution and
537 * if all commands execute successfully, returns an array of update counts.
538 * The <code>int</code> elements of the array that is returned are ordered
539 * to correspond to the commands in the batch, which are ordered
540 * according to the order in which they were added to the batch.
541 * The elements in the array returned by the method <code>executeBatch</code>
542 * may be one of the following:
543 * <OL>
544 * <LI>A number greater than or equal to zero -- indicates that the
545 * command was processed successfully and is an update count giving the
546 * number of rows in the database that were affected by the command's
547 * execution
548 * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was
549 * processed successfully but that the number of rows affected is
550 * unknown
551 * <P>
552 * If one of the commands in a batch update fails to execute properly,
553 * this method throws a <code>BatchUpdateException</code>, and a JDBC
554 * driver may or may not continue to process the remaining commands in
555 * the batch. However, the driver's behavior must be consistent with a
556 * particular DBMS, either always continuing to process commands or never
557 * continuing to process commands. If the driver continues processing
558 * after a failure, the array returned by the method
559 * <code>BatchUpdateException.getUpdateCounts</code>
560 * will contain as many elements as there are commands in the batch, and
561 * at least one of the elements will be the following:
562 * <P>
563 * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed
564 * to execute successfully and occurs only if a driver continues to
565 * process commands after a command fails
566 * </OL>
567 * <P>
568 * The possible implementations and return values have been modified in
569 * the Java 2 SDK, Standard Edition, version 1.3 to
570 * accommodate the option of continuing to proccess commands in a batch
571 * update after a <code>BatchUpdateException</code> obejct has been thrown.
572 *
573 * @return an array of update counts containing one element for each
574 * command in the batch. The elements of the array are ordered according
575 * to the order in which commands were added to the batch.
576 * @exception SQLException if a database access error occurs,
577 * this method is called on a closed <code>Statement</code> or the
578 * driver does not support batch statements. Throws {@link BatchUpdateException}
579 * (a subclass of <code>SQLException</code>) if one of the commands sent to the
580 * database fails to execute properly or attempts to return a result set.
581 * @throws SQLTimeoutException when the driver has determined that the
582 * timeout value that was specified by the {@code setQueryTimeout}
583 * method has been exceeded and has at least attempted to cancel
584 * the currently running {@code Statement}
585 *
586 * @see #addBatch
587 * @see DatabaseMetaData#supportsBatchUpdates
588 * @since 1.2
589 */
590 int[] executeBatch() throws SQLException;
591
592 /**
593 * Retrieves the <code>Connection</code> object
594 * that produced this <code>Statement</code> object.
595 * @return the connection that produced this statement
596 * @exception SQLException if a database access error occurs or
597 * this method is called on a closed <code>Statement</code>
598 * @since 1.2
599 */
600 Connection getConnection() throws SQLException;
601
602 //--------------------------JDBC 3.0-----------------------------
603
604 /**
605 * The constant indicating that the current <code>ResultSet</code> object
606 * should be closed when calling <code>getMoreResults</code>.
607 *
608 * @since 1.4
609 */
610 int CLOSE_CURRENT_RESULT = 1;
611
612 /**
613 * The constant indicating that the current <code>ResultSet</code> object
614 * should not be closed when calling <code>getMoreResults</code>.
615 *
616 * @since 1.4
617 */
618 int KEEP_CURRENT_RESULT = 2;
619
620 /**
621 * The constant indicating that all <code>ResultSet</code> objects that
622 * have previously been kept open should be closed when calling
623 * <code>getMoreResults</code>.
624 *
625 * @since 1.4
626 */
627 int CLOSE_ALL_RESULTS = 3;
628
629 /**
630 * The constant indicating that a batch statement executed successfully
631 * but that no count of the number of rows it affected is available.
632 *
633 * @since 1.4
634 */
635 int SUCCESS_NO_INFO = -2;
636
637 /**
638 * The constant indicating that an error occured while executing a
639 * batch statement.
640 *
641 * @since 1.4
642 */
643 int EXECUTE_FAILED = -3;
644
645 /**
646 * The constant indicating that generated keys should be made
647 * available for retrieval.
648 *
649 * @since 1.4
650 */
651 int RETURN_GENERATED_KEYS = 1;
652
653 /**
654 * The constant indicating that generated keys should not be made
655 * available for retrieval.
656 *
657 * @since 1.4
658 */
659 int NO_GENERATED_KEYS = 2;
660
661 /**
662 * Moves to this <code>Statement</code> object's next result, deals with
663 * any current <code>ResultSet</code> object(s) according to the instructions
664 * specified by the given flag, and returns
665 * <code>true</code> if the next result is a <code>ResultSet</code> object.
666 *
667 * <P>There are no more results when the following is true:
668 * <PRE>{@code
669 * // stmt is a Statement object
670 * ((stmt.getMoreResults(current) == false) && (stmt.getUpdateCount() == -1))
671 * }</PRE>
672 *
673 * @param current one of the following <code>Statement</code>
674 * constants indicating what should happen to current
675 * <code>ResultSet</code> objects obtained using the method
676 * <code>getResultSet</code>:
677 * <code>Statement.CLOSE_CURRENT_RESULT</code>,
678 * <code>Statement.KEEP_CURRENT_RESULT</code>, or
679 * <code>Statement.CLOSE_ALL_RESULTS</code>
680 * @return <code>true</code> if the next result is a <code>ResultSet</code>
681 * object; <code>false</code> if it is an update count or there are no
682 * more results
683 * @exception SQLException if a database access error occurs,
684 * this method is called on a closed <code>Statement</code> or the argument
685 * supplied is not one of the following:
686 * <code>Statement.CLOSE_CURRENT_RESULT</code>,
687 * <code>Statement.KEEP_CURRENT_RESULT</code> or
688 * <code>Statement.CLOSE_ALL_RESULTS</code>
689 *@exception SQLFeatureNotSupportedException if
690 * <code>DatabaseMetaData.supportsMultipleOpenResults</code> returns
691 * <code>false</code> and either
692 * <code>Statement.KEEP_CURRENT_RESULT</code> or
693 * <code>Statement.CLOSE_ALL_RESULTS</code> are supplied as
694 * the argument.
695 * @since 1.4
696 * @see #execute
697 */
698 boolean getMoreResults(int current) throws SQLException;
699
700 /**
701 * Retrieves any auto-generated keys created as a result of executing this
702 * <code>Statement</code> object. If this <code>Statement</code> object did
703 * not generate any keys, an empty <code>ResultSet</code>
704 * object is returned.
705 *
706 *<p><B>Note:</B>If the columns which represent the auto-generated keys were not specified,
707 * the JDBC driver implementation will determine the columns which best represent the auto-generated keys.
708 *
709 * @return a <code>ResultSet</code> object containing the auto-generated key(s)
710 * generated by the execution of this <code>Statement</code> object
711 * @exception SQLException if a database access error occurs or
712 * this method is called on a closed <code>Statement</code>
713 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
714 * @since 1.4
715 */
716 ResultSet getGeneratedKeys() throws SQLException;
717
718 /**
719 * Executes the given SQL statement and signals the driver with the
720 * given flag about whether the
721 * auto-generated keys produced by this <code>Statement</code> object
722 * should be made available for retrieval. The driver will ignore the
723 * flag if the SQL statement
724 * is not an <code>INSERT</code> statement, or an SQL statement able to return
725 * auto-generated keys (the list of such statements is vendor-specific).
726 *<p>
727 * <strong>Note:</strong>This method cannot be called on a
728 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
729 * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
730 * <code>DELETE</code>; or an SQL statement that returns nothing,
731 * such as a DDL statement.
732 *
733 * @param autoGeneratedKeys a flag indicating whether auto-generated keys
734 * should be made available for retrieval;
735 * one of the following constants:
736 * <code>Statement.RETURN_GENERATED_KEYS</code>
737 * <code>Statement.NO_GENERATED_KEYS</code>
738 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
739 * or (2) 0 for SQL statements that return nothing
740 *
741 * @exception SQLException if a database access error occurs,
742 * this method is called on a closed <code>Statement</code>, the given
743 * SQL statement returns a <code>ResultSet</code> object,
744 * the given constant is not one of those allowed, the method is called on a
745 * <code>PreparedStatement</code> or <code>CallableStatement</code>
746 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
747 * this method with a constant of Statement.RETURN_GENERATED_KEYS
748 * @throws SQLTimeoutException when the driver has determined that the
749 * timeout value that was specified by the {@code setQueryTimeout}
750 * method has been exceeded and has at least attempted to cancel
751 * the currently running {@code Statement}
752 * @since 1.4
753 */
754 int executeUpdate(String sql, int autoGeneratedKeys) throws SQLException;
755
756 /**
757 * Executes the given SQL statement and signals the driver that the
758 * auto-generated keys indicated in the given array should be made available
759 * for retrieval. This array contains the indexes of the columns in the
760 * target table that contain the auto-generated keys that should be made
761 * available. The driver will ignore the array if the SQL statement
762 * is not an <code>INSERT</code> statement, or an SQL statement able to return
763 * auto-generated keys (the list of such statements is vendor-specific).
764 *<p>
765 * <strong>Note:</strong>This method cannot be called on a
766 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
767 * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
768 * <code>DELETE</code>; or an SQL statement that returns nothing,
769 * such as a DDL statement.
770 *
771 * @param columnIndexes an array of column indexes indicating the columns
772 * that should be returned from the inserted row
773 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
774 * or (2) 0 for SQL statements that return nothing
775 *
776 * @exception SQLException if a database access error occurs,
777 * this method is called on a closed <code>Statement</code>, the SQL
778 * statement returns a <code>ResultSet</code> object,the second argument
779 * supplied to this method is not an
780 * <code>int</code> array whose elements are valid column indexes, the method is called on a
781 * <code>PreparedStatement</code> or <code>CallableStatement</code>
782 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
783 * @throws SQLTimeoutException when the driver has determined that the
784 * timeout value that was specified by the {@code setQueryTimeout}
785 * method has been exceeded and has at least attempted to cancel
786 * the currently running {@code Statement}
787 * @since 1.4
788 */
789 int executeUpdate(String sql, int columnIndexes[]) throws SQLException;
790
791 /**
792 * Executes the given SQL statement and signals the driver that the
793 * auto-generated keys indicated in the given array should be made available
794 * for retrieval. This array contains the names of the columns in the
795 * target table that contain the auto-generated keys that should be made
796 * available. The driver will ignore the array if the SQL statement
797 * is not an <code>INSERT</code> statement, or an SQL statement able to return
798 * auto-generated keys (the list of such statements is vendor-specific).
799 *<p>
800 * <strong>Note:</strong>This method cannot be called on a
801 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
802 * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
803 * <code>DELETE</code>; or an SQL statement that returns nothing,
804 * such as a DDL statement.
805 * @param columnNames an array of the names of the columns that should be
806 * returned from the inserted row
807 * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
808 * or <code>DELETE</code> statements, or 0 for SQL statements
809 * that return nothing
810 * @exception SQLException if a database access error occurs,
811 * this method is called on a closed <code>Statement</code>, the SQL
812 * statement returns a <code>ResultSet</code> object, the
813 * second argument supplied to this method is not a <code>String</code> array
814 * whose elements are valid column names, the method is called on a
815 * <code>PreparedStatement</code> or <code>CallableStatement</code>
816 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
817 * @throws SQLTimeoutException when the driver has determined that the
818 * timeout value that was specified by the {@code setQueryTimeout}
819 * method has been exceeded and has at least attempted to cancel
820 * the currently running {@code Statement}
821 * @since 1.4
822 */
823 int executeUpdate(String sql, String columnNames[]) throws SQLException;
824
825 /**
826 * Executes the given SQL statement, which may return multiple results,
827 * and signals the driver that any
828 * auto-generated keys should be made available
829 * for retrieval. The driver will ignore this signal if the SQL statement
830 * is not an <code>INSERT</code> statement, or an SQL statement able to return
831 * auto-generated keys (the list of such statements is vendor-specific).
832 * <P>
833 * In some (uncommon) situations, a single SQL statement may return
834 * multiple result sets and/or update counts. Normally you can ignore
835 * this unless you are (1) executing a stored procedure that you know may
836 * return multiple results or (2) you are dynamically executing an
837 * unknown SQL string.
838 * <P>
839 * The <code>execute</code> method executes an SQL statement and indicates the
840 * form of the first result. You must then use the methods
841 * <code>getResultSet</code> or <code>getUpdateCount</code>
842 * to retrieve the result, and <code>getMoreResults</code> to
843 * move to any subsequent result(s).
844 *<p>
845 *<strong>Note:</strong>This method cannot be called on a
846 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
847 * @param sql any SQL statement
848 * @param autoGeneratedKeys a constant indicating whether auto-generated
849 * keys should be made available for retrieval using the method
850 * <code>getGeneratedKeys</code>; one of the following constants:
851 * <code>Statement.RETURN_GENERATED_KEYS</code> or
852 * <code>Statement.NO_GENERATED_KEYS</code>
853 * @return <code>true</code> if the first result is a <code>ResultSet</code>
854 * object; <code>false</code> if it is an update count or there are
855 * no results
856 * @exception SQLException if a database access error occurs,
857 * this method is called on a closed <code>Statement</code>, the second
858 * parameter supplied to this method is not
859 * <code>Statement.RETURN_GENERATED_KEYS</code> or
860 * <code>Statement.NO_GENERATED_KEYS</code>,
861 * the method is called on a
862 * <code>PreparedStatement</code> or <code>CallableStatement</code>
863 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
864 * this method with a constant of Statement.RETURN_GENERATED_KEYS
865 * @throws SQLTimeoutException when the driver has determined that the
866 * timeout value that was specified by the {@code setQueryTimeout}
867 * method has been exceeded and has at least attempted to cancel
868 * the currently running {@code Statement}
869 * @see #getResultSet
870 * @see #getUpdateCount
871 * @see #getMoreResults
872 * @see #getGeneratedKeys
873 *
874 * @since 1.4
875 */
876 boolean execute(String sql, int autoGeneratedKeys) throws SQLException;
877
878 /**
879 * Executes the given SQL statement, which may return multiple results,
880 * and signals the driver that the
881 * auto-generated keys indicated in the given array should be made available
882 * for retrieval. This array contains the indexes of the columns in the
883 * target table that contain the auto-generated keys that should be made
884 * available. The driver will ignore the array if the SQL statement
885 * is not an <code>INSERT</code> statement, or an SQL statement able to return
886 * auto-generated keys (the list of such statements is vendor-specific).
887 * <P>
888 * Under some (uncommon) situations, a single SQL statement may return
889 * multiple result sets and/or update counts. Normally you can ignore
890 * this unless you are (1) executing a stored procedure that you know may
891 * return multiple results or (2) you are dynamically executing an
892 * unknown SQL string.
893 * <P>
894 * The <code>execute</code> method executes an SQL statement and indicates the
895 * form of the first result. You must then use the methods
896 * <code>getResultSet</code> or <code>getUpdateCount</code>
897 * to retrieve the result, and <code>getMoreResults</code> to
898 * move to any subsequent result(s).
899 *<p>
900 * <strong>Note:</strong>This method cannot be called on a
901 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
902 * @param sql any SQL statement
903 * @param columnIndexes an array of the indexes of the columns in the
904 * inserted row that should be made available for retrieval by a
905 * call to the method <code>getGeneratedKeys</code>
906 * @return <code>true</code> if the first result is a <code>ResultSet</code>
907 * object; <code>false</code> if it is an update count or there
908 * are no results
909 * @exception SQLException if a database access error occurs,
910 * this method is called on a closed <code>Statement</code>, the
911 * elements in the <code>int</code> array passed to this method
912 * are not valid column indexes, the method is called on a
913 * <code>PreparedStatement</code> or <code>CallableStatement</code>
914 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
915 * @throws SQLTimeoutException when the driver has determined that the
916 * timeout value that was specified by the {@code setQueryTimeout}
917 * method has been exceeded and has at least attempted to cancel
918 * the currently running {@code Statement}
919 * @see #getResultSet
920 * @see #getUpdateCount
921 * @see #getMoreResults
922 *
923 * @since 1.4
924 */
925 boolean execute(String sql, int columnIndexes[]) throws SQLException;
926
927 /**
928 * Executes the given SQL statement, which may return multiple results,
929 * and signals the driver that the
930 * auto-generated keys indicated in the given array should be made available
931 * for retrieval. This array contains the names of the columns in the
932 * target table that contain the auto-generated keys that should be made
933 * available. The driver will ignore the array if the SQL statement
934 * is not an <code>INSERT</code> statement, or an SQL statement able to return
935 * auto-generated keys (the list of such statements is vendor-specific).
936 * <P>
937 * In some (uncommon) situations, a single SQL statement may return
938 * multiple result sets and/or update counts. Normally you can ignore
939 * this unless you are (1) executing a stored procedure that you know may
940 * return multiple results or (2) you are dynamically executing an
941 * unknown SQL string.
942 * <P>
943 * The <code>execute</code> method executes an SQL statement and indicates the
944 * form of the first result. You must then use the methods
945 * <code>getResultSet</code> or <code>getUpdateCount</code>
946 * to retrieve the result, and <code>getMoreResults</code> to
947 * move to any subsequent result(s).
948 *<p>
949 * <strong>Note:</strong>This method cannot be called on a
950 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
951 * @param sql any SQL statement
952 * @param columnNames an array of the names of the columns in the inserted
953 * row that should be made available for retrieval by a call to the
954 * method <code>getGeneratedKeys</code>
955 * @return <code>true</code> if the next result is a <code>ResultSet</code>
956 * object; <code>false</code> if it is an update count or there
957 * are no more results
958 * @exception SQLException if a database access error occurs,
959 * this method is called on a closed <code>Statement</code>,the
960 * elements of the <code>String</code> array passed to this
961 * method are not valid column names, the method is called on a
962 * <code>PreparedStatement</code> or <code>CallableStatement</code>
963 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
964 * @throws SQLTimeoutException when the driver has determined that the
965 * timeout value that was specified by the {@code setQueryTimeout}
966 * method has been exceeded and has at least attempted to cancel
967 * the currently running {@code Statement}
968 * @see #getResultSet
969 * @see #getUpdateCount
970 * @see #getMoreResults
971 * @see #getGeneratedKeys
972 *
973 * @since 1.4
974 */
975 boolean execute(String sql, String columnNames[]) throws SQLException;
976
977 /**
978 * Retrieves the result set holdability for <code>ResultSet</code> objects
979 * generated by this <code>Statement</code> object.
980 *
981 * @return either <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
982 * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
983 * @exception SQLException if a database access error occurs or
984 * this method is called on a closed <code>Statement</code>
985 *
986 * @since 1.4
987 */
988 int getResultSetHoldability() throws SQLException;
989
990 /**
991 * Retrieves whether this <code>Statement</code> object has been closed. A <code>Statement</code> is closed if the
992 * method close has been called on it, or if it is automatically closed.
993 * @return true if this <code>Statement</code> object is closed; false if it is still open
994 * @throws SQLException if a database access error occurs
995 * @since 1.6
996 */
997 boolean isClosed() throws SQLException;
998
999 /**
1000 * Requests that a <code>Statement</code> be pooled or not pooled. The value
1001 * specified is a hint to the statement pool implementation indicating
1002 * whether the application wants the statement to be pooled. It is up to
1003 * the statement pool manager as to whether the hint is used.
1004 * <p>
1005 * The poolable value of a statement is applicable to both internal
1006 * statement caches implemented by the driver and external statement caches
1007 * implemented by application servers and other applications.
1008 * <p>
1009 * By default, a <code>Statement</code> is not poolable when created, and
1010 * a <code>PreparedStatement</code> and <code>CallableStatement</code>
1011 * are poolable when created.
1012 * <p>
1013 * @param poolable requests that the statement be pooled if true and
1014 * that the statement not be pooled if false
1015 * <p>
1016 * @throws SQLException if this method is called on a closed
1017 * <code>Statement</code>
1018 * <p>
1019 * @since 1.6
1020 */
1021 void setPoolable(boolean poolable)
1022 throws SQLException;
1023
1024 /**
1025 * Returns a value indicating whether the <code>Statement</code>
1026 * is poolable or not.
1027 * <p>
1028 * @return <code>true</code> if the <code>Statement</code>
1029 * is poolable; <code>false</code> otherwise
1030 * <p>
1031 * @throws SQLException if this method is called on a closed
1032 * <code>Statement</code>
1033 * <p>
1034 * @since 1.6
1035 * <p>
1036 * @see java.sql.Statement#setPoolable(boolean) setPoolable(boolean)
1037 */
1038 boolean isPoolable()
1039 throws SQLException;
1040
1041 //--------------------------JDBC 4.1 -----------------------------
1042
1043 /**
1044 * Specifies that this {@code Statement} will be closed when all its
1045 * dependent result sets are closed. If execution of the {@code Statement}
1046 * does not produce any result sets, this method has no effect.
1047 * <p>
1048 * <strong>Note:</strong> Multiple calls to {@code closeOnCompletion} do
1049 * not toggle the effect on this {@code Statement}. However, a call to
1050 * {@code closeOnCompletion} does effect both the subsequent execution of
1051 * statements, and statements that currently have open, dependent,
1052 * result sets.
1053 *
1054 * @throws SQLException if this method is called on a closed
1055 * {@code Statement}
1056 * @since 1.7
1057 */
1058 public void closeOnCompletion() throws SQLException;
1059
1060 /**
1061 * Returns a value indicating whether this {@code Statement} will be
1062 * closed when all its dependent result sets are closed.
1063 * @return {@code true} if the {@code Statement} will be closed when all
1064 * of its dependent result sets are closed; {@code false} otherwise
1065 * @throws SQLException if this method is called on a closed
1066 * {@code Statement}
1067 * @since 1.7
1068 */
1069 public boolean isCloseOnCompletion() throws SQLException;
1070
1071
1072 //--------------------------JDBC 4.2 -----------------------------
1073
1074 /**
1075 * Retrieves the current result as an update count; if the result
1076 * is a <code>ResultSet</code> object or there are no more results, -1
1077 * is returned. This method should be called only once per result.
1078 * <p>
1079 * This method should be used when the returned row count may exceed
1080 * {@link Integer#MAX_VALUE}.
1081 *<p>
1082 * The default implementation will throw {@code UnsupportedOperationException}
1083 *
1084 * @return the current result as an update count; -1 if the current result
1085 * is a <code>ResultSet</code> object or there are no more results
1086 * @exception SQLException if a database access error occurs or
1087 * this method is called on a closed <code>Statement</code>
1088 * @see #execute
1089 * @since 1.8
1090 */
1091 default long getLargeUpdateCount() throws SQLException {
1092 throw new UnsupportedOperationException("getLargeUpdateCount not implemented");
1093 }
1094
1095 /**
1096 * Sets the limit for the maximum number of rows that any
1097 * <code>ResultSet</code> object generated by this <code>Statement</code>
1098 * object can contain to the given number.
1099 * If the limit is exceeded, the excess
1100 * rows are silently dropped.
1101 * <p>
1102 * This method should be used when the row limit may exceed
1103 * {@link Integer#MAX_VALUE}.
1104 *<p>
1105 * The default implementation will throw {@code UnsupportedOperationException}
1106 *
1107 * @param max the new max rows limit; zero means there is no limit
1108 * @exception SQLException if a database access error occurs,
1109 * this method is called on a closed <code>Statement</code>
1110 * or the condition {@code max >= 0} is not satisfied
1111 * @see #getMaxRows
1112 * @since 1.8
1113 */
1114 default void setLargeMaxRows(long max) throws SQLException {
1115 throw new UnsupportedOperationException("setLargeMaxRows not implemented");
1116 }
1117
1118 /**
1119 * Retrieves the maximum number of rows that a
1120 * <code>ResultSet</code> object produced by this
1121 * <code>Statement</code> object can contain. If this limit is exceeded,
1122 * the excess rows are silently dropped.
1123 * <p>
1124 * This method should be used when the returned row limit may exceed
1125 * {@link Integer#MAX_VALUE}.
1126 *<p>
1127 * The default implementation will return {@code 0}
1128 *
1129 * @return the current maximum number of rows for a <code>ResultSet</code>
1130 * object produced by this <code>Statement</code> object;
1131 * zero means there is no limit
1132 * @exception SQLException if a database access error occurs or
1133 * this method is called on a closed <code>Statement</code>
1134 * @see #setMaxRows
1135 * @since 1.8
1136 */
1137 default long getLargeMaxRows() throws SQLException {
1138 return 0;
1139 }
1140
1141 /**
1142 * Submits a batch of commands to the database for execution and
1143 * if all commands execute successfully, returns an array of update counts.
1144 * The <code>long</code> elements of the array that is returned are ordered
1145 * to correspond to the commands in the batch, which are ordered
1146 * according to the order in which they were added to the batch.
1147 * The elements in the array returned by the method {@code executeLargeBatch}
1148 * may be one of the following:
1149 * <OL>
1150 * <LI>A number greater than or equal to zero -- indicates that the
1151 * command was processed successfully and is an update count giving the
1152 * number of rows in the database that were affected by the command's
1153 * execution
1154 * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was
1155 * processed successfully but that the number of rows affected is
1156 * unknown
1157 * <P>
1158 * If one of the commands in a batch update fails to execute properly,
1159 * this method throws a <code>BatchUpdateException</code>, and a JDBC
1160 * driver may or may not continue to process the remaining commands in
1161 * the batch. However, the driver's behavior must be consistent with a
1162 * particular DBMS, either always continuing to process commands or never
1163 * continuing to process commands. If the driver continues processing
1164 * after a failure, the array returned by the method
1165 * <code>BatchUpdateException.getLargeUpdateCounts</code>
1166 * will contain as many elements as there are commands in the batch, and
1167 * at least one of the elements will be the following:
1168 * <P>
1169 * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed
1170 * to execute successfully and occurs only if a driver continues to
1171 * process commands after a command fails
1172 * </OL>
1173 * <p>
1174 * This method should be used when the returned row count may exceed
1175 * {@link Integer#MAX_VALUE}.
1176 *<p>
1177 * The default implementation will throw {@code UnsupportedOperationException}
1178 *
1179 * @return an array of update counts containing one element for each
1180 * command in the batch. The elements of the array are ordered according
1181 * to the order in which commands were added to the batch.
1182 * @exception SQLException if a database access error occurs,
1183 * this method is called on a closed <code>Statement</code> or the
1184 * driver does not support batch statements. Throws {@link BatchUpdateException}
1185 * (a subclass of <code>SQLException</code>) if one of the commands sent to the
1186 * database fails to execute properly or attempts to return a result set.
1187 * @throws SQLTimeoutException when the driver has determined that the
1188 * timeout value that was specified by the {@code setQueryTimeout}
1189 * method has been exceeded and has at least attempted to cancel
1190 * the currently running {@code Statement}
1191 *
1192 * @see #addBatch
1193 * @see DatabaseMetaData#supportsBatchUpdates
1194 * @since 1.8
1195 */
1196 default long[] executeLargeBatch() throws SQLException {
1197 throw new UnsupportedOperationException("executeLargeBatch not implemented");
1198 }
1199
1200 /**
1201 * Executes the given SQL statement, which may be an <code>INSERT</code>,
1202 * <code>UPDATE</code>, or <code>DELETE</code> statement or an
1203 * SQL statement that returns nothing, such as an SQL DDL statement.
1204 * <p>
1205 * This method should be used when the returned row count may exceed
1206 * {@link Integer#MAX_VALUE}.
1207 * <p>
1208 * <strong>Note:</strong>This method cannot be called on a
1209 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
1210 *<p>
1211 * The default implementation will throw {@code UnsupportedOperationException}
1212 *
1213 * @param sql an SQL Data Manipulation Language (DML) statement,
1214 * such as <code>INSERT</code>, <code>UPDATE</code> or
1215 * <code>DELETE</code>; or an SQL statement that returns nothing,
1216 * such as a DDL statement.
1217 *
1218 * @return either (1) the row count for SQL Data Manipulation Language
1219 * (DML) statements or (2) 0 for SQL statements that return nothing
1220 *
1221 * @exception SQLException if a database access error occurs,
1222 * this method is called on a closed <code>Statement</code>, the given
1223 * SQL statement produces a <code>ResultSet</code> object, the method is called on a
1224 * <code>PreparedStatement</code> or <code>CallableStatement</code>
1225 * @throws SQLTimeoutException when the driver has determined that the
1226 * timeout value that was specified by the {@code setQueryTimeout}
1227 * method has been exceeded and has at least attempted to cancel
1228 * the currently running {@code Statement}
1229 * @since 1.8
1230 */
1231 default long executeLargeUpdate(String sql) throws SQLException {
1232 throw new UnsupportedOperationException("executeLargeUpdate not implemented");
1233 }
1234
1235 /**
1236 * Executes the given SQL statement and signals the driver with the
1237 * given flag about whether the
1238 * auto-generated keys produced by this <code>Statement</code> object
1239 * should be made available for retrieval. The driver will ignore the
1240 * flag if the SQL statement
1241 * is not an <code>INSERT</code> statement, or an SQL statement able to return
1242 * auto-generated keys (the list of such statements is vendor-specific).
1243 * <p>
1244 * This method should be used when the returned row count may exceed
1245 * {@link Integer#MAX_VALUE}.
1246 * <p>
1247 * <strong>Note:</strong>This method cannot be called on a
1248 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
1249 *<p>
1250 * The default implementation will throw {@code SQLFeatureNotSupportedException}
1251 *
1252 * @param sql an SQL Data Manipulation Language (DML) statement,
1253 * such as <code>INSERT</code>, <code>UPDATE</code> or
1254 * <code>DELETE</code>; or an SQL statement that returns nothing,
1255 * such as a DDL statement.
1256 *
1257 * @param autoGeneratedKeys a flag indicating whether auto-generated keys
1258 * should be made available for retrieval;
1259 * one of the following constants:
1260 * <code>Statement.RETURN_GENERATED_KEYS</code>
1261 * <code>Statement.NO_GENERATED_KEYS</code>
1262 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
1263 * or (2) 0 for SQL statements that return nothing
1264 *
1265 * @exception SQLException if a database access error occurs,
1266 * this method is called on a closed <code>Statement</code>, the given
1267 * SQL statement returns a <code>ResultSet</code> object,
1268 * the given constant is not one of those allowed, the method is called on a
1269 * <code>PreparedStatement</code> or <code>CallableStatement</code>
1270 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
1271 * this method with a constant of Statement.RETURN_GENERATED_KEYS
1272 * @throws SQLTimeoutException when the driver has determined that the
1273 * timeout value that was specified by the {@code setQueryTimeout}
1274 * method has been exceeded and has at least attempted to cancel
1275 * the currently running {@code Statement}
1276 * @since 1.8
1277 */
1278 default long executeLargeUpdate(String sql, int autoGeneratedKeys)
1279 throws SQLException {
1280 throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");
1281 }
1282
1283 /**
1284 * Executes the given SQL statement and signals the driver that the
1285 * auto-generated keys indicated in the given array should be made available
1286 * for retrieval. This array contains the indexes of the columns in the
1287 * target table that contain the auto-generated keys that should be made
1288 * available. The driver will ignore the array if the SQL statement
1289 * is not an <code>INSERT</code> statement, or an SQL statement able to return
1290 * auto-generated keys (the list of such statements is vendor-specific).
1291 * <p>
1292 * This method should be used when the returned row count may exceed
1293 * {@link Integer#MAX_VALUE}.
1294 * <p>
1295 * <strong>Note:</strong>This method cannot be called on a
1296 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
1297 *<p>
1298 * The default implementation will throw {@code SQLFeatureNotSupportedException}
1299 *
1300 * @param sql an SQL Data Manipulation Language (DML) statement,
1301 * such as <code>INSERT</code>, <code>UPDATE</code> or
1302 * <code>DELETE</code>; or an SQL statement that returns nothing,
1303 * such as a DDL statement.
1304 *
1305 * @param columnIndexes an array of column indexes indicating the columns
1306 * that should be returned from the inserted row
1307 * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
1308 * or (2) 0 for SQL statements that return nothing
1309 *
1310 * @exception SQLException if a database access error occurs,
1311 * this method is called on a closed <code>Statement</code>, the SQL
1312 * statement returns a <code>ResultSet</code> object,the second argument
1313 * supplied to this method is not an
1314 * <code>int</code> array whose elements are valid column indexes, the method is called on a
1315 * <code>PreparedStatement</code> or <code>CallableStatement</code>
1316 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1317 * @throws SQLTimeoutException when the driver has determined that the
1318 * timeout value that was specified by the {@code setQueryTimeout}
1319 * method has been exceeded and has at least attempted to cancel
1320 * the currently running {@code Statement}
1321 * @since 1.8
1322 */
1323 default long executeLargeUpdate(String sql, int columnIndexes[]) throws SQLException {
1324 throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");
1325 }
1326
1327 /**
1328 * Executes the given SQL statement and signals the driver that the
1329 * auto-generated keys indicated in the given array should be made available
1330 * for retrieval. This array contains the names of the columns in the
1331 * target table that contain the auto-generated keys that should be made
1332 * available. The driver will ignore the array if the SQL statement
1333 * is not an <code>INSERT</code> statement, or an SQL statement able to return
1334 * auto-generated keys (the list of such statements is vendor-specific).
1335 * <p>
1336 * This method should be used when the returned row count may exceed
1337 * {@link Integer#MAX_VALUE}.
1338 * <p>
1339 * <strong>Note:</strong>This method cannot be called on a
1340 * <code>PreparedStatement</code> or <code>CallableStatement</code>.
1341 *<p>
1342 * The default implementation will throw {@code SQLFeatureNotSupportedException}
1343 *
1344 * @param sql an SQL Data Manipulation Language (DML) statement,
1345 * such as <code>INSERT</code>, <code>UPDATE</code> or
1346 * <code>DELETE</code>; or an SQL statement that returns nothing,
1347 * such as a DDL statement.
1348 * @param columnNames an array of the names of the columns that should be
1349 * returned from the inserted row
1350 * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
1351 * or <code>DELETE</code> statements, or 0 for SQL statements
1352 * that return nothing
1353 * @exception SQLException if a database access error occurs,
1354 * this method is called on a closed <code>Statement</code>, the SQL
1355 * statement returns a <code>ResultSet</code> object, the
1356 * second argument supplied to this method is not a <code>String</code> array
1357 * whose elements are valid column names, the method is called on a
1358 * <code>PreparedStatement</code> or <code>CallableStatement</code>
1359 * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method
1360 * @throws SQLTimeoutException when the driver has determined that the
1361 * timeout value that was specified by the {@code setQueryTimeout}
1362 * method has been exceeded and has at least attempted to cancel
1363 * the currently running {@code Statement}
1364 * @since 1.8
1365 */
1366 default long executeLargeUpdate(String sql, String columnNames[])
1367 throws SQLException {
1368 throw new SQLFeatureNotSupportedException("executeLargeUpdate not implemented");
1369 }
1370 }