History

My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/java/sql/Statement.java (1 of 18352 files). Show all

Unified · Split

java/pkg/java/sql/Statement.java+1063−0
@@ -0,0 +1,1063 @@
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
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+ */
1030+ boolean isPoolable()
1031+ throws SQLException;
1032+
1033+ //--------------------------JDBC 4.1 -----------------------------
1034+
1035+ /**
1036+ * Specifies that this {@code Statement} will be closed when all its
1037+ * dependent result sets are closed. If execution of the {@code Statement}
1038+ * does not produce any result sets, this method has no effect.
1039+ * <p>
1040+ * <strong>Note:</strong> Multiple calls to {@code closeOnCompletion} do
1041+ * not toggle the effect on this {@code Statement}. However, a call to
1042+ * {@code closeOnCompletion} does effect both the subsequent execution of
1043+ * statements, and statements that currently have open, dependent,
1044+ * result sets.
1045+ *
1046+ * @throws SQLException if this method is called on a closed
1047+ * {@code Statement}
1048+ * @since 1.7
1049+ */
1050+ public void closeOnCompletion() throws SQLException;
1051+
1052+ /**
1053+ * Returns a value indicating whether this {@code Statement} will be
1054+ * closed when all its dependent result sets are closed.
1055+ * @return {@code true} if the {@code Statement} will be closed when all
1056+ * of its dependent result sets are closed; {@code false} otherwise
1057+ * @throws SQLException if this method is called on a closed
1058+ * {@code Statement}
1059+ * @since 1.7
1060+ */
1061+ public boolean isCloseOnCompletion() throws SQLException;
1062+
1063+}