1 /*
2  * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * This code is free software; you can redistribute it and/or modify it
6  * under the terms of the GNU General Public License version 2 only, as
7  * published by the Free Software Foundation.  Oracle designates this
8  * particular file as subject to the "Classpath" exception as provided
9  * by Oracle in the LICENSE file that accompanied this code.
10  *
11  * This code is distributed in the hope that it will be useful, but WITHOUT
12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14  * version 2 for more details (a copy is included in the LICENSE file that
15  * accompanied this code).
16  *
17  * You should have received a copy of the GNU General Public License version
18  * 2 along with this work; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20  *
21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22  * or visit www.oracle.com if you need additional information or have any
23  * questions.
24  */
25 
26 package java.sql;
27 
28 /**
29  * <P>The object used for executing a static SQL statement
30  * and returning the results it produces.
31  * <P>
32  * By default, only one <code>ResultSet</code> object per <code>Statement</code>
33  * object can be open at the same time. Therefore, if the reading of one
34  * <code>ResultSet</code> object is interleaved
35  * with the reading of another, each must have been generated by
36  * different <code>Statement</code> objects. All execution methods in the
37  * <code>Statement</code> interface implicitly close a statment's current
38  * <code>ResultSet</code> object if an open one exists.
39  *
40  * @see Connection#createStatement
41  * @see ResultSet
42  */
43 public interface Statement extends Wrapper, AutoCloseable {
44 
45     /**
46      * Executes the given SQL statement, which returns a single
47      * <code>ResultSet</code> object.
48      *<p>
49      * <strong>Note:</strong>This method cannot be called on a
50      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
51      * @param sql an SQL statement to be sent to the database, typically a
52      *        static SQL <code>SELECT</code> statement
53      * @return a <code>ResultSet</code> object that contains the data produced
54      *         by the given query; never <code>null</code>
55      * @exception SQLException if a database access error occurs,
56      * this method is called on a closed <code>Statement</code>, the given
57      *            SQL statement produces anything other than a single
58      *            <code>ResultSet</code> object, the method is called on a
59      * <code>PreparedStatement</code> or <code>CallableStatement</code>
60      * @throws SQLTimeoutException when the driver has determined that the
61      * timeout value that was specified by the {@code setQueryTimeout}
62      * method has been exceeded and has at least attempted to cancel
63      * the currently running {@code Statement}
64      */
executeQuery(String sql)65     ResultSet executeQuery(String sql) throws SQLException;
66 
67     /**
68      * Executes the given SQL statement, which may be an <code>INSERT</code>,
69      * <code>UPDATE</code>, or <code>DELETE</code> statement or an
70      * SQL statement that returns nothing, such as an SQL DDL statement.
71      *<p>
72      * <strong>Note:</strong>This method cannot be called on a
73      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
74      * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
75      * <code>DELETE</code>; or an SQL statement that returns nothing,
76      * such as a DDL statement.
77      *
78      * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
79      *         or (2) 0 for SQL statements that return nothing
80      *
81      * @exception SQLException if a database access error occurs,
82      * this method is called on a closed <code>Statement</code>, the given
83      * SQL statement produces a <code>ResultSet</code> object, the method is called on a
84      * <code>PreparedStatement</code> or <code>CallableStatement</code>
85      * @throws SQLTimeoutException when the driver has determined that the
86      * timeout value that was specified by the {@code setQueryTimeout}
87      * method has been exceeded and has at least attempted to cancel
88      * the currently running {@code Statement}
89      */
executeUpdate(String sql)90     int executeUpdate(String sql) throws SQLException;
91 
92     /**
93      * Releases this <code>Statement</code> object's database
94      * and JDBC resources immediately instead of waiting for
95      * this to happen when it is automatically closed.
96      * It is generally good practice to release resources as soon as
97      * you are finished with them to avoid tying up database
98      * resources.
99      * <P>
100      * Calling the method <code>close</code> on a <code>Statement</code>
101      * object that is already closed has no effect.
102      * <P>
103      * <B>Note:</B>When a <code>Statement</code> object is
104      * closed, its current <code>ResultSet</code> object, if one exists, is
105      * also closed.
106      *
107      * @exception SQLException if a database access error occurs
108      */
close()109     void close() throws SQLException;
110 
111     //----------------------------------------------------------------------
112 
113     /**
114      * Retrieves the maximum number of bytes that can be
115      * returned for character and binary column values in a <code>ResultSet</code>
116      * object produced by this <code>Statement</code> object.
117      * This limit applies only to  <code>BINARY</code>, <code>VARBINARY</code>,
118      * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
119      * <code>NCHAR</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>
120      * and <code>LONGVARCHAR</code> columns.  If the limit is exceeded, the
121      * excess data is silently discarded.
122      *
123      * @return the current column size limit for columns storing character and
124      *         binary values; zero means there is no limit
125      * @exception SQLException if a database access error occurs or
126      * this method is called on a closed <code>Statement</code>
127      * @see #setMaxFieldSize
128      */
getMaxFieldSize()129     int getMaxFieldSize() throws SQLException;
130 
131     /**
132      * Sets the limit for the maximum number of bytes that can be returned for
133      * character and binary column values in a <code>ResultSet</code>
134      * object produced by this <code>Statement</code> object.
135      *
136      * This limit applies
137      * only to <code>BINARY</code>, <code>VARBINARY</code>,
138      * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,
139      * <code>NCHAR</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code> and
140      * <code>LONGVARCHAR</code> fields.  If the limit is exceeded, the excess data
141      * is silently discarded. For maximum portability, use values
142      * greater than 256.
143      *
144      * @param max the new column size limit in bytes; zero means there is no limit
145      * @exception SQLException if a database access error occurs,
146      * this method is called on a closed <code>Statement</code>
147      *            or the condition max >= 0 is not satisfied
148      * @see #getMaxFieldSize
149      */
setMaxFieldSize(int max)150     void setMaxFieldSize(int max) throws SQLException;
151 
152     /**
153      * Retrieves the maximum number of rows that a
154      * <code>ResultSet</code> object produced by this
155      * <code>Statement</code> object can contain.  If this limit is exceeded,
156      * the excess rows are silently dropped.
157      *
158      * @return the current maximum number of rows for a <code>ResultSet</code>
159      *         object produced by this <code>Statement</code> object;
160      *         zero means there is no limit
161      * @exception SQLException if a database access error occurs or
162      * this method is called on a closed <code>Statement</code>
163      * @see #setMaxRows
164      */
getMaxRows()165     int getMaxRows() throws SQLException;
166 
167     /**
168      * Sets the limit for the maximum number of rows that any
169      * <code>ResultSet</code> object  generated by this <code>Statement</code>
170      * object can contain to the given number.
171      * If the limit is exceeded, the excess
172      * rows are silently dropped.
173      *
174      * @param max the new max rows limit; zero means there is no limit
175      * @exception SQLException if a database access error occurs,
176      * this method is called on a closed <code>Statement</code>
177      *            or the condition max >= 0 is not satisfied
178      * @see #getMaxRows
179      */
setMaxRows(int max)180     void setMaxRows(int max) throws SQLException;
181 
182     /**
183      * Sets escape processing on or off.
184      * If escape scanning is on (the default), the driver will do
185      * escape substitution before sending the SQL statement to the database.
186      *
187      * Note: Since prepared statements have usually been parsed prior
188      * to making this call, disabling escape processing for
189      * <code>PreparedStatements</code> objects will have no effect.
190      *
191      * @param enable <code>true</code> to enable escape processing;
192      *       <code>false</code> to disable it
193      * @exception SQLException if a database access error occurs or
194      * this method is called on a closed <code>Statement</code>
195      */
setEscapeProcessing(boolean enable)196     void setEscapeProcessing(boolean enable) throws SQLException;
197 
198     /**
199      * Retrieves the number of seconds the driver will
200      * wait for a <code>Statement</code> object to execute.
201      * If the limit is exceeded, a
202      * <code>SQLException</code> is thrown.
203      *
204      * @return the current query timeout limit in seconds; zero means there is
205      *         no limit
206      * @exception SQLException if a database access error occurs or
207      * this method is called on a closed <code>Statement</code>
208      * @see #setQueryTimeout
209      */
getQueryTimeout()210     int getQueryTimeout() throws SQLException;
211 
212     /**
213      * Sets the number of seconds the driver will wait for a
214      * <code>Statement</code> object to execute to the given number of seconds.
215      *By default there is no limit on the amount of time allowed for a running
216      * statement to complete. If the limit is exceeded, an
217      * <code>SQLTimeoutException</code> is thrown.
218      * A JDBC driver must apply this limit to the <code>execute</code>,
219      * <code>executeQuery</code> and <code>executeUpdate</code> methods.
220      * <p>
221      * <strong>Note:</strong> JDBC driver implementations may also apply this
222      * limit to {@code ResultSet} methods
223      * (consult your driver vendor documentation for details).
224      * <p>
225      * <strong>Note:</strong> In the case of {@code Statement} batching, it is
226      * implementation defined as to whether the time-out is applied to
227      * individual SQL commands added via the {@code addBatch} method or to
228      * the entire batch of SQL commands invoked by the {@code executeBatch}
229      * method (consult your driver vendor documentation for details).
230      *
231      * @param seconds the new query timeout limit in seconds; zero means
232      *        there is no limit
233      * @exception SQLException if a database access error occurs,
234      * this method is called on a closed <code>Statement</code>
235      *            or the condition seconds >= 0 is not satisfied
236      * @see #getQueryTimeout
237      */
setQueryTimeout(int seconds)238     void setQueryTimeout(int seconds) throws SQLException;
239 
240     /**
241      * Cancels this <code>Statement</code> object if both the DBMS and
242      * driver support aborting an SQL statement.
243      * This method can be used by one thread to cancel a statement that
244      * is being executed by another thread.
245      *
246      * @exception SQLException if a database access error occurs or
247      * this method is called on a closed <code>Statement</code>
248      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
249      * this method
250      */
cancel()251     void cancel() throws SQLException;
252 
253     /**
254      * Retrieves the first warning reported by calls on this <code>Statement</code> object.
255      * Subsequent <code>Statement</code> object warnings will be chained to this
256      * <code>SQLWarning</code> object.
257      *
258      * <p>The warning chain is automatically cleared each time
259      * a statement is (re)executed. This method may not be called on a closed
260      * <code>Statement</code> object; doing so will cause an <code>SQLException</code>
261      * to be thrown.
262      *
263      * <P><B>Note:</B> If you are processing a <code>ResultSet</code> object, any
264      * warnings associated with reads on that <code>ResultSet</code> object
265      * will be chained on it rather than on the <code>Statement</code>
266      * object that produced it.
267      *
268      * @return the first <code>SQLWarning</code> object or <code>null</code>
269      *         if there are no warnings
270      * @exception SQLException if a database access error occurs or
271      * this method is called on a closed <code>Statement</code>
272      */
getWarnings()273     SQLWarning getWarnings() throws SQLException;
274 
275     /**
276      * Clears all the warnings reported on this <code>Statement</code>
277      * object. After a call to this method,
278      * the method <code>getWarnings</code> will return
279      * <code>null</code> until a new warning is reported for this
280      * <code>Statement</code> object.
281      *
282      * @exception SQLException if a database access error occurs or
283      * this method is called on a closed <code>Statement</code>
284      */
clearWarnings()285     void clearWarnings() throws SQLException;
286 
287     /**
288      * Sets the SQL cursor name to the given <code>String</code>, which
289      * will be used by subsequent <code>Statement</code> object
290      * <code>execute</code> methods. This name can then be
291      * used in SQL positioned update or delete statements to identify the
292      * current row in the <code>ResultSet</code> object generated by this
293      * statement.  If the database does not support positioned update/delete,
294      * this method is a noop.  To insure that a cursor has the proper isolation
295      * level to support updates, the cursor's <code>SELECT</code> statement
296      * should have the form <code>SELECT FOR UPDATE</code>.  If
297      * <code>FOR UPDATE</code> is not present, positioned updates may fail.
298      *
299      * <P><B>Note:</B> By definition, the execution of positioned updates and
300      * deletes must be done by a different <code>Statement</code> object than
301      * the one that generated the <code>ResultSet</code> object being used for
302      * positioning. Also, cursor names must be unique within a connection.
303      *
304      * @param name the new cursor name, which must be unique within
305      *             a connection
306      * @exception SQLException if a database access error occurs or
307      * this method is called on a closed <code>Statement</code>
308      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
309      */
setCursorName(String name)310     void setCursorName(String name) throws SQLException;
311 
312     //----------------------- Multiple Results --------------------------
313 
314     /**
315      * Executes the given SQL statement, which may return multiple results.
316      * In some (uncommon) situations, a single SQL statement may return
317      * multiple result sets and/or update counts.  Normally you can ignore
318      * this unless you are (1) executing a stored procedure that you know may
319      * return multiple results or (2) you are dynamically executing an
320      * unknown SQL string.
321      * <P>
322      * The <code>execute</code> method executes an SQL statement and indicates the
323      * form of the first result.  You must then use the methods
324      * <code>getResultSet</code> or <code>getUpdateCount</code>
325      * to retrieve the result, and <code>getMoreResults</code> to
326      * move to any subsequent result(s).
327      * <p>
328      *<strong>Note:</strong>This method cannot be called on a
329      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
330      * @param sql any SQL statement
331      * @return <code>true</code> if the first result is a <code>ResultSet</code>
332      *         object; <code>false</code> if it is an update count or there are
333      *         no results
334      * @exception SQLException if a database access error occurs,
335      * this method is called on a closed <code>Statement</code>,
336      * the method is called on a
337      * <code>PreparedStatement</code> or <code>CallableStatement</code>
338      * @throws SQLTimeoutException when the driver has determined that the
339      * timeout value that was specified by the {@code setQueryTimeout}
340      * method has been exceeded and has at least attempted to cancel
341      * the currently running {@code Statement}
342      * @see #getResultSet
343      * @see #getUpdateCount
344      * @see #getMoreResults
345      */
execute(String sql)346     boolean execute(String sql) throws SQLException;
347 
348     /**
349      *  Retrieves the current result as a <code>ResultSet</code> object.
350      *  This method should be called only once per result.
351      *
352      * @return the current result as a <code>ResultSet</code> object or
353      * <code>null</code> if the result is an update count or there are no more results
354      * @exception SQLException if a database access error occurs or
355      * this method is called on a closed <code>Statement</code>
356      * @see #execute
357      */
getResultSet()358     ResultSet getResultSet() throws SQLException;
359 
360     /**
361      *  Retrieves the current result as an update count;
362      *  if the result is a <code>ResultSet</code> object or there are no more results, -1
363      *  is returned. This method should be called only once per result.
364      *
365      * @return the current result as an update count; -1 if the current result is a
366      * <code>ResultSet</code> object or there are no more results
367      * @exception SQLException if a database access error occurs or
368      * this method is called on a closed <code>Statement</code>
369      * @see #execute
370      */
getUpdateCount()371     int getUpdateCount() throws SQLException;
372 
373     /**
374      * Moves to this <code>Statement</code> object's next result, returns
375      * <code>true</code> if it is a <code>ResultSet</code> object, and
376      * implicitly closes any current <code>ResultSet</code>
377      * object(s) obtained with the method <code>getResultSet</code>.
378      *
379      * <P>There are no more results when the following is true:
380      * <PRE>
381      *     // stmt is a Statement object
382      *     ((stmt.getMoreResults() == false) && (stmt.getUpdateCount() == -1))
383      * </PRE>
384      *
385      * @return <code>true</code> if the next result is a <code>ResultSet</code>
386      *         object; <code>false</code> if it is an update count or there are
387      *         no more results
388      * @exception SQLException if a database access error occurs or
389      * this method is called on a closed <code>Statement</code>
390      * @see #execute
391      */
getMoreResults()392     boolean getMoreResults() throws SQLException;
393 
394 
395     //--------------------------JDBC 2.0-----------------------------
396 
397 
398     /**
399      * Gives the driver a hint as to the direction in which
400      * rows will be processed in <code>ResultSet</code>
401      * objects created using this <code>Statement</code> object.  The
402      * default value is <code>ResultSet.FETCH_FORWARD</code>.
403      * <P>
404      * Note that this method sets the default fetch direction for
405      * result sets generated by this <code>Statement</code> object.
406      * Each result set has its own methods for getting and setting
407      * its own fetch direction.
408      *
409      * @param direction the initial direction for processing rows
410      * @exception SQLException if a database access error occurs,
411      * this method is called on a closed <code>Statement</code>
412      * or the given direction
413      * is not one of <code>ResultSet.FETCH_FORWARD</code>,
414      * <code>ResultSet.FETCH_REVERSE</code>, or <code>ResultSet.FETCH_UNKNOWN</code>
415      * @since 1.2
416      * @see #getFetchDirection
417      */
setFetchDirection(int direction)418     void setFetchDirection(int direction) throws SQLException;
419 
420     /**
421      * Retrieves the direction for fetching rows from
422      * database tables that is the default for result sets
423      * generated from this <code>Statement</code> object.
424      * If this <code>Statement</code> object has not set
425      * a fetch direction by calling the method <code>setFetchDirection</code>,
426      * the return value is implementation-specific.
427      *
428      * @return the default fetch direction for result sets generated
429      *          from this <code>Statement</code> object
430      * @exception SQLException if a database access error occurs or
431      * this method is called on a closed <code>Statement</code>
432      * @since 1.2
433      * @see #setFetchDirection
434      */
getFetchDirection()435     int getFetchDirection() throws SQLException;
436 
437     /**
438      * Gives the JDBC driver a hint as to the number of rows that should
439      * be fetched from the database when more rows are needed for
440      * <code>ResultSet</code> objects genrated by this <code>Statement</code>.
441      * If the value specified is zero, then the hint is ignored.
442      * The default value is zero.
443      *
444      * @param rows the number of rows to fetch
445      * @exception SQLException if a database access error occurs,
446      * this method is called on a closed <code>Statement</code> or the
447      *        condition  <code>rows >= 0</code> is not satisfied.
448      * @since 1.2
449      * @see #getFetchSize
450      */
setFetchSize(int rows)451     void setFetchSize(int rows) throws SQLException;
452 
453     /**
454      * Retrieves the number of result set rows that is the default
455      * fetch size for <code>ResultSet</code> objects
456      * generated from this <code>Statement</code> object.
457      * If this <code>Statement</code> object has not set
458      * a fetch size by calling the method <code>setFetchSize</code>,
459      * the return value is implementation-specific.
460      *
461      * @return the default fetch size for result sets generated
462      *          from this <code>Statement</code> object
463      * @exception SQLException if a database access error occurs or
464      * this method is called on a closed <code>Statement</code>
465      * @since 1.2
466      * @see #setFetchSize
467      */
getFetchSize()468     int getFetchSize() throws SQLException;
469 
470     /**
471      * Retrieves the result set concurrency for <code>ResultSet</code> objects
472      * generated by this <code>Statement</code> object.
473      *
474      * @return either <code>ResultSet.CONCUR_READ_ONLY</code> or
475      * <code>ResultSet.CONCUR_UPDATABLE</code>
476      * @exception SQLException if a database access error occurs or
477      * this method is called on a closed <code>Statement</code>
478      * @since 1.2
479      */
getResultSetConcurrency()480     int getResultSetConcurrency() throws SQLException;
481 
482     /**
483      * Retrieves the result set type for <code>ResultSet</code> objects
484      * generated by this <code>Statement</code> object.
485      *
486      * @return one of <code>ResultSet.TYPE_FORWARD_ONLY</code>,
487      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
488      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
489      * @exception SQLException if a database access error occurs or
490      * this method is called on a closed <code>Statement</code>
491      * @since 1.2
492      */
getResultSetType()493     int getResultSetType()  throws SQLException;
494 
495     /**
496      * Adds the given SQL command to the current list of commmands for this
497      * <code>Statement</code> object. The commands in this list can be
498      * executed as a batch by calling the method <code>executeBatch</code>.
499      * <P>
500      *<strong>Note:</strong>This method cannot be called on a
501      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
502      * @param sql typically this is a SQL <code>INSERT</code> or
503      * <code>UPDATE</code> statement
504      * @exception SQLException if a database access error occurs,
505      * this method is called on a closed <code>Statement</code>, the
506      * driver does not support batch updates, the method is called on a
507      * <code>PreparedStatement</code> or <code>CallableStatement</code>
508      * @see #executeBatch
509      * @see DatabaseMetaData#supportsBatchUpdates
510      * @since 1.2
511      */
addBatch( String sql )512     void addBatch( String sql ) throws SQLException;
513 
514     /**
515      * Empties this <code>Statement</code> object's current list of
516      * SQL commands.
517      * <P>
518      * @exception SQLException if a database access error occurs,
519      *  this method is called on a closed <code>Statement</code> or the
520      * driver does not support batch updates
521      * @see #addBatch
522      * @see DatabaseMetaData#supportsBatchUpdates
523      * @since 1.2
524      */
clearBatch()525     void clearBatch() throws SQLException;
526 
527     /**
528      * Submits a batch of commands to the database for execution and
529      * if all commands execute successfully, returns an array of update counts.
530      * The <code>int</code> elements of the array that is returned are ordered
531      * to correspond to the commands in the batch, which are ordered
532      * according to the order in which they were added to the batch.
533      * The elements in the array returned by the method <code>executeBatch</code>
534      * may be one of the following:
535      * <OL>
536      * <LI>A number greater than or equal to zero -- indicates that the
537      * command was processed successfully and is an update count giving the
538      * number of rows in the database that were affected by the command's
539      * execution
540      * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was
541      * processed successfully but that the number of rows affected is
542      * unknown
543      * <P>
544      * If one of the commands in a batch update fails to execute properly,
545      * this method throws a <code>BatchUpdateException</code>, and a JDBC
546      * driver may or may not continue to process the remaining commands in
547      * the batch.  However, the driver's behavior must be consistent with a
548      * particular DBMS, either always continuing to process commands or never
549      * continuing to process commands.  If the driver continues processing
550      * after a failure, the array returned by the method
551      * <code>BatchUpdateException.getUpdateCounts</code>
552      * will contain as many elements as there are commands in the batch, and
553      * at least one of the elements will be the following:
554      * <P>
555      * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed
556      * to execute successfully and occurs only if a driver continues to
557      * process commands after a command fails
558      * </OL>
559      * <P>
560      * The possible implementations and return values have been modified in
561      * the Java 2 SDK, Standard Edition, version 1.3 to
562      * accommodate the option of continuing to proccess commands in a batch
563      * update after a <code>BatchUpdateException</code> obejct has been thrown.
564      *
565      * @return an array of update counts containing one element for each
566      * command in the batch.  The elements of the array are ordered according
567      * to the order in which commands were added to the batch.
568      * @exception SQLException if a database access error occurs,
569      * this method is called on a closed <code>Statement</code> or the
570      * driver does not support batch statements. Throws {@link BatchUpdateException}
571      * (a subclass of <code>SQLException</code>) if one of the commands sent to the
572      * database fails to execute properly or attempts to return a result set.
573      * @throws SQLTimeoutException when the driver has determined that the
574      * timeout value that was specified by the {@code setQueryTimeout}
575      * method has been exceeded and has at least attempted to cancel
576      * the currently running {@code Statement}
577      *
578      * @see #addBatch
579      * @see DatabaseMetaData#supportsBatchUpdates
580      * @since 1.2
581      */
executeBatch()582     int[] executeBatch() throws SQLException;
583 
584     /**
585      * Retrieves the <code>Connection</code> object
586      * that produced this <code>Statement</code> object.
587      * @return the connection that produced this statement
588      * @exception SQLException if a database access error occurs or
589      * this method is called on a closed <code>Statement</code>
590      * @since 1.2
591      */
getConnection()592     Connection getConnection()  throws SQLException;
593 
594   //--------------------------JDBC 3.0-----------------------------
595 
596     /**
597      * The constant indicating that the current <code>ResultSet</code> object
598      * should be closed when calling <code>getMoreResults</code>.
599      *
600      * @since 1.4
601      */
602     int CLOSE_CURRENT_RESULT = 1;
603 
604     /**
605      * The constant indicating that the current <code>ResultSet</code> object
606      * should not be closed when calling <code>getMoreResults</code>.
607      *
608      * @since 1.4
609      */
610     int KEEP_CURRENT_RESULT = 2;
611 
612     /**
613      * The constant indicating that all <code>ResultSet</code> objects that
614      * have previously been kept open should be closed when calling
615      * <code>getMoreResults</code>.
616      *
617      * @since 1.4
618      */
619     int CLOSE_ALL_RESULTS = 3;
620 
621     /**
622      * The constant indicating that a batch statement executed successfully
623      * but that no count of the number of rows it affected is available.
624      *
625      * @since 1.4
626      */
627     int SUCCESS_NO_INFO = -2;
628 
629     /**
630      * The constant indicating that an error occured while executing a
631      * batch statement.
632      *
633      * @since 1.4
634      */
635     int EXECUTE_FAILED = -3;
636 
637     /**
638      * The constant indicating that generated keys should be made
639      * available for retrieval.
640      *
641      * @since 1.4
642      */
643     int RETURN_GENERATED_KEYS = 1;
644 
645     /**
646      * The constant indicating that generated keys should not be made
647      * available for retrieval.
648      *
649      * @since 1.4
650      */
651     int NO_GENERATED_KEYS = 2;
652 
653     /**
654      * Moves to this <code>Statement</code> object's next result, deals with
655      * any current <code>ResultSet</code> object(s) according  to the instructions
656      * specified by the given flag, and returns
657      * <code>true</code> if the next result is a <code>ResultSet</code> object.
658      *
659      * <P>There are no more results when the following is true:
660      * <PRE>
661      *     // stmt is a Statement object
662      *     ((stmt.getMoreResults(current) == false) && (stmt.getUpdateCount() == -1))
663      * </PRE>
664      *
665      * @param current one of the following <code>Statement</code>
666      *        constants indicating what should happen to current
667      *        <code>ResultSet</code> objects obtained using the method
668      *        <code>getResultSet</code>:
669      *        <code>Statement.CLOSE_CURRENT_RESULT</code>,
670      *        <code>Statement.KEEP_CURRENT_RESULT</code>, or
671      *        <code>Statement.CLOSE_ALL_RESULTS</code>
672      * @return <code>true</code> if the next result is a <code>ResultSet</code>
673      *         object; <code>false</code> if it is an update count or there are no
674      *         more results
675      * @exception SQLException if a database access error occurs,
676      * this method is called on a closed <code>Statement</code> or the argument
677          *         supplied is not one of the following:
678      *        <code>Statement.CLOSE_CURRENT_RESULT</code>,
679      *        <code>Statement.KEEP_CURRENT_RESULT</code> or
680      *        <code>Statement.CLOSE_ALL_RESULTS</code>
681      *@exception SQLFeatureNotSupportedException if
682      * <code>DatabaseMetaData.supportsMultipleOpenResults</code> returns
683      * <code>false</code> and either
684      *        <code>Statement.KEEP_CURRENT_RESULT</code> or
685      *        <code>Statement.CLOSE_ALL_RESULTS</code> are supplied as
686      * the argument.
687      * @since 1.4
688      * @see #execute
689      */
getMoreResults(int current)690     boolean getMoreResults(int current) throws SQLException;
691 
692     /**
693      * Retrieves any auto-generated keys created as a result of executing this
694      * <code>Statement</code> object. If this <code>Statement</code> object did
695      * not generate any keys, an empty <code>ResultSet</code>
696      * object is returned.
697      *
698      *<p><B>Note:</B>If the columns which represent the auto-generated keys were not specified,
699      * the JDBC driver implementation will determine the columns which best represent the auto-generated keys.
700      *
701      * @return a <code>ResultSet</code> object containing the auto-generated key(s)
702      *         generated by the execution of this <code>Statement</code> object
703      * @exception SQLException if a database access error occurs or
704      * this method is called on a closed <code>Statement</code>
705      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
706      * @since 1.4
707      */
getGeneratedKeys()708     ResultSet getGeneratedKeys() throws SQLException;
709 
710     /**
711      * Executes the given SQL statement and signals the driver with the
712      * given flag about whether the
713      * auto-generated keys produced by this <code>Statement</code> object
714      * should be made available for retrieval.  The driver will ignore the
715      * flag if the SQL statement
716      * is not an <code>INSERT</code> statement, or an SQL statement able to return
717      * auto-generated keys (the list of such statements is vendor-specific).
718      *<p>
719      * <strong>Note:</strong>This method cannot be called on a
720      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
721      * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
722      * <code>DELETE</code>; or an SQL statement that returns nothing,
723      * such as a DDL statement.
724      *
725      * @param autoGeneratedKeys a flag indicating whether auto-generated keys
726      *        should be made available for retrieval;
727      *         one of the following constants:
728      *         <code>Statement.RETURN_GENERATED_KEYS</code>
729      *         <code>Statement.NO_GENERATED_KEYS</code>
730      * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
731      *         or (2) 0 for SQL statements that return nothing
732      *
733      * @exception SQLException if a database access error occurs,
734      *  this method is called on a closed <code>Statement</code>, the given
735      *            SQL statement returns a <code>ResultSet</code> object,
736      *            the given constant is not one of those allowed, the method is called on a
737      * <code>PreparedStatement</code> or <code>CallableStatement</code>
738      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
739      * this method with a constant of Statement.RETURN_GENERATED_KEYS
740      * @throws SQLTimeoutException when the driver has determined that the
741      * timeout value that was specified by the {@code setQueryTimeout}
742      * method has been exceeded and has at least attempted to cancel
743      * the currently running {@code Statement}
744      * @since 1.4
745      */
executeUpdate(String sql, int autoGeneratedKeys)746     int executeUpdate(String sql, int autoGeneratedKeys) throws SQLException;
747 
748     /**
749      * Executes the given SQL statement and signals the driver that the
750      * auto-generated keys indicated in the given array should be made available
751      * for retrieval.   This array contains the indexes of the columns in the
752      * target table that contain the auto-generated keys that should be made
753      * available. The driver will ignore the array if the SQL statement
754      * is not an <code>INSERT</code> statement, or an SQL statement able to return
755      * auto-generated keys (the list of such statements is vendor-specific).
756      *<p>
757      * <strong>Note:</strong>This method cannot be called on a
758      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
759      * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
760      * <code>DELETE</code>; or an SQL statement that returns nothing,
761      * such as a DDL statement.
762      *
763      * @param columnIndexes an array of column indexes indicating the columns
764      *        that should be returned from the inserted row
765      * @return either (1) the row count for SQL Data Manipulation Language (DML) statements
766      *         or (2) 0 for SQL statements that return nothing
767      *
768      * @exception SQLException if a database access error occurs,
769      * this method is called on a closed <code>Statement</code>, the SQL
770      * statement returns a <code>ResultSet</code> object,the second argument
771      * supplied to this method is not an
772      * <code>int</code> array whose elements are valid column indexes, the method is called on a
773      * <code>PreparedStatement</code> or <code>CallableStatement</code>
774      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
775      * @throws SQLTimeoutException when the driver has determined that the
776      * timeout value that was specified by the {@code setQueryTimeout}
777      * method has been exceeded and has at least attempted to cancel
778      * the currently running {@code Statement}
779      * @since 1.4
780      */
executeUpdate(String sql, int columnIndexes[])781     int executeUpdate(String sql, int columnIndexes[]) throws SQLException;
782 
783     /**
784      * Executes the given SQL statement and signals the driver that the
785      * auto-generated keys indicated in the given array should be made available
786      * for retrieval.   This array contains the names of the columns in the
787      * target table that contain the auto-generated keys that should be made
788      * available. The driver will ignore the array if the SQL statement
789      * is not an <code>INSERT</code> statement, or an SQL statement able to return
790      * auto-generated keys (the list of such statements is vendor-specific).
791      *<p>
792      * <strong>Note:</strong>This method cannot be called on a
793      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
794      * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or
795      * <code>DELETE</code>; or an SQL statement that returns nothing,
796      * such as a DDL statement.
797      * @param columnNames an array of the names of the columns that should be
798      *        returned from the inserted row
799      * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
800      *         or <code>DELETE</code> statements, or 0 for SQL statements
801      *         that return nothing
802      * @exception SQLException if a database access error occurs,
803      *  this method is called on a closed <code>Statement</code>, the SQL
804      *            statement returns a <code>ResultSet</code> object, the
805      *            second argument supplied to this method is not a <code>String</code> array
806      *            whose elements are valid column names, the method is called on a
807      * <code>PreparedStatement</code> or <code>CallableStatement</code>
808      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
809      * @throws SQLTimeoutException when the driver has determined that the
810      * timeout value that was specified by the {@code setQueryTimeout}
811      * method has been exceeded and has at least attempted to cancel
812      * the currently running {@code Statement}
813      * @since 1.4
814      */
executeUpdate(String sql, String columnNames[])815     int executeUpdate(String sql, String columnNames[]) throws SQLException;
816 
817     /**
818      * Executes the given SQL statement, which may return multiple results,
819      * and signals the driver that any
820      * auto-generated keys should be made available
821      * for retrieval.  The driver will ignore this signal if the SQL statement
822      * is not an <code>INSERT</code> statement, or an SQL statement able to return
823      * auto-generated keys (the list of such statements is vendor-specific).
824      * <P>
825      * In some (uncommon) situations, a single SQL statement may return
826      * multiple result sets and/or update counts.  Normally you can ignore
827      * this unless you are (1) executing a stored procedure that you know may
828      * return multiple results or (2) you are dynamically executing an
829      * unknown SQL string.
830      * <P>
831      * The <code>execute</code> method executes an SQL statement and indicates the
832      * form of the first result.  You must then use the methods
833      * <code>getResultSet</code> or <code>getUpdateCount</code>
834      * to retrieve the result, and <code>getMoreResults</code> to
835      * move to any subsequent result(s).
836      *<p>
837      *<strong>Note:</strong>This method cannot be called on a
838      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
839      * @param sql any SQL statement
840      * @param autoGeneratedKeys a constant indicating whether auto-generated
841      *        keys should be made available for retrieval using the method
842      *        <code>getGeneratedKeys</code>; one of the following constants:
843      *        <code>Statement.RETURN_GENERATED_KEYS</code> or
844      *        <code>Statement.NO_GENERATED_KEYS</code>
845      * @return <code>true</code> if the first result is a <code>ResultSet</code>
846      *         object; <code>false</code> if it is an update count or there are
847      *         no results
848      * @exception SQLException if a database access error occurs,
849      * this method is called on a closed <code>Statement</code>, the second
850      *         parameter supplied to this method is not
851      *         <code>Statement.RETURN_GENERATED_KEYS</code> or
852      *         <code>Statement.NO_GENERATED_KEYS</code>,
853      * the method is called on a
854      * <code>PreparedStatement</code> or <code>CallableStatement</code>
855      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
856      * this method with a constant of Statement.RETURN_GENERATED_KEYS
857      * @throws SQLTimeoutException when the driver has determined that the
858      * timeout value that was specified by the {@code setQueryTimeout}
859      * method has been exceeded and has at least attempted to cancel
860      * the currently running {@code Statement}
861      * @see #getResultSet
862      * @see #getUpdateCount
863      * @see #getMoreResults
864      * @see #getGeneratedKeys
865      *
866      * @since 1.4
867      */
execute(String sql, int autoGeneratedKeys)868     boolean execute(String sql, int autoGeneratedKeys) throws SQLException;
869 
870     /**
871      * Executes the given SQL statement, which may return multiple results,
872      * and signals the driver that the
873      * auto-generated keys indicated in the given array should be made available
874      * for retrieval.  This array contains the indexes of the columns in the
875      * target table that contain the auto-generated keys that should be made
876      * available.  The driver will ignore the array if the SQL statement
877      * is not an <code>INSERT</code> statement, or an SQL statement able to return
878      * auto-generated keys (the list of such statements is vendor-specific).
879      * <P>
880      * Under some (uncommon) situations, a single SQL statement may return
881      * multiple result sets and/or update counts.  Normally you can ignore
882      * this unless you are (1) executing a stored procedure that you know may
883      * return multiple results or (2) you are dynamically executing an
884      * unknown SQL string.
885      * <P>
886      * The <code>execute</code> method executes an SQL statement and indicates the
887      * form of the first result.  You must then use the methods
888      * <code>getResultSet</code> or <code>getUpdateCount</code>
889      * to retrieve the result, and <code>getMoreResults</code> to
890      * move to any subsequent result(s).
891      *<p>
892      * <strong>Note:</strong>This method cannot be called on a
893      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
894      * @param sql any SQL statement
895      * @param columnIndexes an array of the indexes of the columns in the
896      *        inserted row that should be  made available for retrieval by a
897      *        call to the method <code>getGeneratedKeys</code>
898      * @return <code>true</code> if the first result is a <code>ResultSet</code>
899      *         object; <code>false</code> if it is an update count or there
900      *         are no results
901      * @exception SQLException if a database access error occurs,
902      * this method is called on a closed <code>Statement</code>, the
903      *            elements in the <code>int</code> array passed to this method
904      *            are not valid column indexes, the method is called on a
905      * <code>PreparedStatement</code> or <code>CallableStatement</code>
906      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
907      * @throws SQLTimeoutException when the driver has determined that the
908      * timeout value that was specified by the {@code setQueryTimeout}
909      * method has been exceeded and has at least attempted to cancel
910      * the currently running {@code Statement}
911      * @see #getResultSet
912      * @see #getUpdateCount
913      * @see #getMoreResults
914      *
915      * @since 1.4
916      */
execute(String sql, int columnIndexes[])917     boolean execute(String sql, int columnIndexes[]) throws SQLException;
918 
919     /**
920      * Executes the given SQL statement, which may return multiple results,
921      * and signals the driver that the
922      * auto-generated keys indicated in the given array should be made available
923      * for retrieval. This array contains the names of the columns in the
924      * target table that contain the auto-generated keys that should be made
925      * available.  The driver will ignore the array if the SQL statement
926      * is not an <code>INSERT</code> statement, or an SQL statement able to return
927      * auto-generated keys (the list of such statements is vendor-specific).
928      * <P>
929      * In some (uncommon) situations, a single SQL statement may return
930      * multiple result sets and/or update counts.  Normally you can ignore
931      * this unless you are (1) executing a stored procedure that you know may
932      * return multiple results or (2) you are dynamically executing an
933      * unknown SQL string.
934      * <P>
935      * The <code>execute</code> method executes an SQL statement and indicates the
936      * form of the first result.  You must then use the methods
937      * <code>getResultSet</code> or <code>getUpdateCount</code>
938      * to retrieve the result, and <code>getMoreResults</code> to
939      * move to any subsequent result(s).
940      *<p>
941      * <strong>Note:</strong>This method cannot be called on a
942      * <code>PreparedStatement</code> or <code>CallableStatement</code>.
943      * @param sql any SQL statement
944      * @param columnNames an array of the names of the columns in the inserted
945      *        row that should be made available for retrieval by a call to the
946      *        method <code>getGeneratedKeys</code>
947      * @return <code>true</code> if the next result is a <code>ResultSet</code>
948      *         object; <code>false</code> if it is an update count or there
949      *         are no more results
950      * @exception SQLException if a database access error occurs,
951      * this method is called on a closed <code>Statement</code>,the
952      *          elements of the <code>String</code> array passed to this
953      *          method are not valid column names, the method is called on a
954      * <code>PreparedStatement</code> or <code>CallableStatement</code>
955      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method
956      * @throws SQLTimeoutException when the driver has determined that the
957      * timeout value that was specified by the {@code setQueryTimeout}
958      * method has been exceeded and has at least attempted to cancel
959      * the currently running {@code Statement}
960      * @see #getResultSet
961      * @see #getUpdateCount
962      * @see #getMoreResults
963      * @see #getGeneratedKeys
964      *
965      * @since 1.4
966      */
execute(String sql, String columnNames[])967     boolean execute(String sql, String columnNames[]) throws SQLException;
968 
969    /**
970      * Retrieves the result set holdability for <code>ResultSet</code> objects
971      * generated by this <code>Statement</code> object.
972      *
973      * @return either <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
974      *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
975      * @exception SQLException if a database access error occurs or
976      * this method is called on a closed <code>Statement</code>
977      *
978      * @since 1.4
979      */
getResultSetHoldability()980     int getResultSetHoldability() throws SQLException;
981 
982     /**
983      * Retrieves whether this <code>Statement</code> object has been closed. A <code>Statement</code> is closed if the
984      * method close has been called on it, or if it is automatically closed.
985      * @return true if this <code>Statement</code> object is closed; false if it is still open
986      * @throws SQLException if a database access error occurs
987      * @since 1.6
988      */
isClosed()989     boolean isClosed() throws SQLException;
990 
991         /**
992          * Requests that a <code>Statement</code> be pooled or not pooled.  The value
993          * specified is a hint to the statement pool implementation indicating
994          * whether the applicaiton wants the statement to be pooled.  It is up to
995          * the statement pool manager as to whether the hint is used.
996          * <p>
997          * The poolable value of a statement is applicable to both internal
998          * statement caches implemented by the driver and external statement caches
999          * implemented by application servers and other applications.
1000          * <p>
1001          * By default, a <code>Statement</code> is not poolable when created, and
1002          * a <code>PreparedStatement</code> and <code>CallableStatement</code>
1003          * are poolable when created.
1004          * <p>
1005          * @param poolable              requests that the statement be pooled if true and
1006          *                                              that the statement not be pooled if false
1007          * <p>
1008          * @throws SQLException if this method is called on a closed
1009          * <code>Statement</code>
1010          * <p>
1011          * @since 1.6
1012          */
setPoolable(boolean poolable)1013         void setPoolable(boolean poolable)
1014                 throws SQLException;
1015 
1016         /**
1017          * Returns a  value indicating whether the <code>Statement</code>
1018          * is poolable or not.
1019          * <p>
1020          * @return              <code>true</code> if the <code>Statement</code>
1021          * is poolable; <code>false</code> otherwise
1022          * <p>
1023          * @throws SQLException if this method is called on a closed
1024          * <code>Statement</code>
1025          * <p>
1026          * @since 1.6
1027          * <p>
1028          * @see java.sql.Statement#setPoolable(boolean) setPoolable(boolean)
1029          */
isPoolable()1030         boolean isPoolable()
1031                 throws SQLException;
1032 
1033 }
1034