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 }