View Javadoc
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 current
38   * <code>ResultSet</code> object of the statement 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 generated 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 commands 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      *
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 process commands in a batch
571      * update after a <code>BatchUpdateException</code> object 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 occurred 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      *
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 }