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 }