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      *
 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          *
1013          * @param poolable              requests that the statement be pooled if true and
1014          *                                              that the statement not be pooled if false
1015          *
1016          * @throws SQLException if this method is called on a closed
1017          * <code>Statement</code>
1018          *
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          *
1028          * @return              <code>true</code> if the <code>Statement</code>
1029          * is poolable; <code>false</code> otherwise
1030          *
1031          * @throws SQLException if this method is called on a closed
1032          * <code>Statement</code>
1033          *
1034          * @since 1.6
1035          *
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 }
--- EOF ---