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