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