KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > sql > Statement


1 /*
2  * @(#)Statement.java 1.40 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.sql;
9
10 /**
11  * <P>The object used for executing a static SQL statement
12  * and returning the results it produces.
13  * <P>
14  * By default, only one <code>ResultSet</code> object per <code>Statement</code>
15  * object can be open at the same time. Therefore, if the reading of one
16  * <code>ResultSet</code> object is interleaved
17  * with the reading of another, each must have been generated by
18  * different <code>Statement</code> objects. All execution methods in the
19  * <code>Statement</code> interface implicitly close a statment's current
20  * <code>ResultSet</code> object if an open one exists.
21  *
22  * @see Connection#createStatement
23  * @see ResultSet
24  */

25 public interface Statement {
26
27     /**
28      * Executes the given SQL statement, which returns a single
29      * <code>ResultSet</code> object.
30      *
31      * @param sql an SQL statement to be sent to the database, typically a
32      * static SQL <code>SELECT</code> statement
33      * @return a <code>ResultSet</code> object that contains the data produced
34      * by the given query; never <code>null</code>
35      * @exception SQLException if a database access error occurs or the given
36      * SQL statement produces anything other than a single
37      * <code>ResultSet</code> object
38      */

39     ResultSet JavaDoc executeQuery(String JavaDoc sql) throws SQLException JavaDoc;
40
41     /**
42      * Executes the given SQL statement, which may be an <code>INSERT</code>,
43      * <code>UPDATE</code>, or <code>DELETE</code> statement or an
44      * SQL statement that returns nothing, such as an SQL DDL statement.
45      *
46      * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
47      * <code>DELETE</code> statement or an SQL statement that returns nothing
48      * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>
49      * or <code>DELETE</code> statements, or <code>0</code> for SQL statements
50      * that return nothing
51      * @exception SQLException if a database access error occurs or the given
52      * SQL statement produces a <code>ResultSet</code> object
53      */

54     int executeUpdate(String JavaDoc sql) throws SQLException JavaDoc;
55
56     /**
57      * Releases this <code>Statement</code> object's database
58      * and JDBC resources immediately instead of waiting for
59      * this to happen when it is automatically closed.
60      * It is generally good practice to release resources as soon as
61      * you are finished with them to avoid tying up database
62      * resources.
63      * <P>
64      * Calling the method <code>close</code> on a <code>Statement</code>
65      * object that is already closed has no effect.
66      * <P>
67      * <B>Note:</B> A <code>Statement</code> object is automatically closed
68      * when it is garbage collected. When a <code>Statement</code> object is
69      * closed, its current <code>ResultSet</code> object, if one exists, is
70      * also closed.
71      *
72      * @exception SQLException if a database access error occurs
73      */

74     void close() throws SQLException JavaDoc;
75
76     //----------------------------------------------------------------------
77

78     /**
79      * Retrieves the maximum number of bytes that can be
80      * returned for character and binary column values in a <code>ResultSet</code>
81      * object produced by this <code>Statement</code> object.
82      * This limit applies only to <code>BINARY</code>,
83      * <code>VARBINARY</code>, <code>LONGVARBINARY</code>, <code>CHAR</code>,
84      * <code>VARCHAR</code>, and <code>LONGVARCHAR</code>
85      * columns. If the limit is exceeded, the excess data is silently
86      * discarded.
87      *
88      * @return the current column size limit for columns storing character and
89      * binary values; zero means there is no limit
90      * @exception SQLException if a database access error occurs
91      * @see #setMaxFieldSize
92      */

93     int getMaxFieldSize() throws SQLException JavaDoc;
94     
95     /**
96      * Sets the limit for the maximum number of bytes in a <code>ResultSet</code>
97      * column storing character or binary values to
98      * the given number of bytes. This limit applies
99      * only to <code>BINARY</code>, <code>VARBINARY</code>,
100      * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>, and
101      * <code>LONGVARCHAR</code> fields. If the limit is exceeded, the excess data
102      * is silently discarded. For maximum portability, use values
103      * greater than 256.
104      *
105      * @param max the new column size limit in bytes; zero means there is no limit
106      * @exception SQLException if a database access error occurs
107      * or the condition max >= 0 is not satisfied
108      * @see #getMaxFieldSize
109      */

110     void setMaxFieldSize(int max) throws SQLException JavaDoc;
111
112     /**
113      * Retrieves the maximum number of rows that a
114      * <code>ResultSet</code> object produced by this
115      * <code>Statement</code> object can contain. If this limit is exceeded,
116      * the excess rows are silently dropped.
117      *
118      * @return the current maximum number of rows for a <code>ResultSet</code>
119      * object produced by this <code>Statement</code> object;
120      * zero means there is no limit
121      * @exception SQLException if a database access error occurs
122      * @see #setMaxRows
123      */

124     int getMaxRows() throws SQLException JavaDoc;
125
126     /**
127      * Sets the limit for the maximum number of rows that any
128      * <code>ResultSet</code> object can contain to the given number.
129      * If the limit is exceeded, the excess
130      * rows are silently dropped.
131      *
132      * @param max the new max rows limit; zero means there is no limit
133      * @exception SQLException if a database access error occurs
134      * or the condition max >= 0 is not satisfied
135      * @see #getMaxRows
136      */

137     void setMaxRows(int max) throws SQLException JavaDoc;
138
139     /**
140      * Sets escape processing on or off.
141      * If escape scanning is on (the default), the driver will do
142      * escape substitution before sending the SQL statement to the database.
143      *
144      * Note: Since prepared statements have usually been parsed prior
145      * to making this call, disabling escape processing for
146      * <code>PreparedStatements</code> objects will have no effect.
147      *
148      * @param enable <code>true</code> to enable escape processing;
149      * <code>false</code> to disable it
150      * @exception SQLException if a database access error occurs
151      */

152     void setEscapeProcessing(boolean enable) throws SQLException JavaDoc;
153
154     /**
155      * Retrieves the number of seconds the driver will
156      * wait for a <code>Statement</code> object to execute. If the limit is exceeded, a
157      * <code>SQLException</code> is thrown.
158      *
159      * @return the current query timeout limit in seconds; zero means there is
160      * no limit
161      * @exception SQLException if a database access error occurs
162      * @see #setQueryTimeout
163      */

164     int getQueryTimeout() throws SQLException JavaDoc;
165
166     /**
167      * Sets the number of seconds the driver will wait for a
168      * <code>Statement</code> object to execute to the given number of seconds.
169      * If the limit is exceeded, an <code>SQLException</code> is thrown.
170      *
171      * @param seconds the new query timeout limit in seconds; zero means
172      * there is no limit
173      * @exception SQLException if a database access error occurs
174      * or the condition seconds >= 0 is not satisfied
175      * @see #getQueryTimeout
176      */

177     void setQueryTimeout(int seconds) throws SQLException JavaDoc;
178
179     /**
180      * Cancels this <code>Statement</code> object if both the DBMS and
181      * driver support aborting an SQL statement.
182      * This method can be used by one thread to cancel a statement that
183      * is being executed by another thread.
184      *
185      * @exception SQLException if a database access error occurs
186      */

187     void cancel() throws SQLException JavaDoc;
188
189     /**
190      * Retrieves the first warning reported by calls on this <code>Statement</code> object.
191      * Subsequent <code>Statement</code> object warnings will be chained to this
192      * <code>SQLWarning</code> object.
193      *
194      * <p>The warning chain is automatically cleared each time
195      * a statement is (re)executed. This method may not be called on a closed
196      * <code>Statement</code> object; doing so will cause an <code>SQLException</code>
197      * to be thrown.
198      *
199      * <P><B>Note:</B> If you are processing a <code>ResultSet</code> object, any
200      * warnings associated with reads on that <code>ResultSet</code> object
201      * will be chained on it rather than on the <code>Statement</code>
202      * object that produced it.
203      *
204      * @return the first <code>SQLWarning</code> object or <code>null</code>
205      * if there are no warnings
206      * @exception SQLException if a database access error occurs or this
207      * method is called on a closed statement
208      */

209     SQLWarning JavaDoc getWarnings() throws SQLException JavaDoc;
210
211     /**
212      * Clears all the warnings reported on this <code>Statement</code>
213      * object. After a call to this method,
214      * the method <code>getWarnings</code> will return
215      * <code>null</code> until a new warning is reported for this
216      * <code>Statement</code> object.
217      *
218      * @exception SQLException if a database access error occurs
219      */

220     void clearWarnings() throws SQLException JavaDoc;
221
222     /**
223      * Sets the SQL cursor name to the given <code>String</code>, which
224      * will be used by subsequent <code>Statement</code> object
225      * <code>execute</code> methods. This name can then be
226      * used in SQL positioned update or delete statements to identify the
227      * current row in the <code>ResultSet</code> object generated by this
228      * statement. If the database does not support positioned update/delete,
229      * this method is a noop. To insure that a cursor has the proper isolation
230      * level to support updates, the cursor's <code>SELECT</code> statement
231      * should have the form <code>SELECT FOR UPDATE</code>. If
232      * <code>FOR UPDATE</code> is not present, positioned updates may fail.
233      *
234      * <P><B>Note:</B> By definition, the execution of positioned updates and
235      * deletes must be done by a different <code>Statement</code> object than
236      * the one that generated the <code>ResultSet</code> object being used for
237      * positioning. Also, cursor names must be unique within a connection.
238      *
239      * @param name the new cursor name, which must be unique within
240      * a connection
241      * @exception SQLException if a database access error occurs
242      */

243     void setCursorName(String JavaDoc name) throws SQLException JavaDoc;
244     
245     //----------------------- Multiple Results --------------------------
246

247     /**
248      * Executes the given SQL statement, which may return multiple results.
249      * In some (uncommon) situations, a single SQL statement may return
250      * multiple result sets and/or update counts. Normally you can ignore
251      * this unless you are (1) executing a stored procedure that you know may
252      * return multiple results or (2) you are dynamically executing an
253      * unknown SQL string.
254      * <P>
255      * The <code>execute</code> method executes an SQL statement and indicates the
256      * form of the first result. You must then use the methods
257      * <code>getResultSet</code> or <code>getUpdateCount</code>
258      * to retrieve the result, and <code>getMoreResults</code> to
259      * move to any subsequent result(s).
260      *
261      * @param sql any SQL statement
262      * @return <code>true</code> if the first result is a <code>ResultSet</code>
263      * object; <code>false</code> if it is an update count or there are
264      * no results
265      * @exception SQLException if a database access error occurs
266      * @see #getResultSet
267      * @see #getUpdateCount
268      * @see #getMoreResults
269      */

270     boolean execute(String JavaDoc sql) throws SQLException JavaDoc;
271     
272     /**
273      * Retrieves the current result as a <code>ResultSet</code> object.
274      * This method should be called only once per result.
275      *
276      * @return the current result as a <code>ResultSet</code> object or
277      * <code>null</code> if the result is an update count or there are no more results
278      * @exception SQLException if a database access error occurs
279      * @see #execute
280      */

281     ResultSet JavaDoc getResultSet() throws SQLException JavaDoc;
282
283     /**
284      * Retrieves the current result as an update count;
285      * if the result is a <code>ResultSet</code> object or there are no more results, -1
286      * is returned. This method should be called only once per result.
287      *
288      * @return the current result as an update count; -1 if the current result is a
289      * <code>ResultSet</code> object or there are no more results
290      * @exception SQLException if a database access error occurs
291      * @see #execute
292      */

293     int getUpdateCount() throws SQLException JavaDoc;
294
295     /**
296      * Moves to this <code>Statement</code> object's next result, returns
297      * <code>true</code> if it is a <code>ResultSet</code> object, and
298      * implicitly closes any current <code>ResultSet</code>
299      * object(s) obtained with the method <code>getResultSet</code>.
300      *
301      * <P>There are no more results when the following is true:
302      * <PRE>
303      * // stmt is a Statement object
304      * ((stmt.getMoreResults() == false) && (stmt.getUpdateCount() == -1))
305      * </PRE>
306      *
307      * @return <code>true</code> if the next result is a <code>ResultSet</code>
308      * object; <code>false</code> if it is an update count or there are
309      * no more results
310      * @exception SQLException if a database access error occurs
311      * @see #execute
312      */

313     boolean getMoreResults() throws SQLException JavaDoc;
314
315
316     //--------------------------JDBC 2.0-----------------------------
317

318
319     /**
320      * Gives the driver a hint as to the direction in which
321      * rows will be processed in <code>ResultSet</code>
322      * objects created using this <code>Statement</code> object. The
323      * default value is <code>ResultSet.FETCH_FORWARD</code>.
324      * <P>
325      * Note that this method sets the default fetch direction for
326      * result sets generated by this <code>Statement</code> object.
327      * Each result set has its own methods for getting and setting
328      * its own fetch direction.
329      *
330      * @param direction the initial direction for processing rows
331      * @exception SQLException if a database access error occurs
332      * or the given direction
333      * is not one of <code>ResultSet.FETCH_FORWARD</code>,
334      * <code>ResultSet.FETCH_REVERSE</code>, or <code>ResultSet.FETCH_UNKNOWN</code>
335      * @since 1.2
336      * @see #getFetchDirection
337      */

338     void setFetchDirection(int direction) throws SQLException JavaDoc;
339
340     /**
341      * Retrieves the direction for fetching rows from
342      * database tables that is the default for result sets
343      * generated from this <code>Statement</code> object.
344      * If this <code>Statement</code> object has not set
345      * a fetch direction by calling the method <code>setFetchDirection</code>,
346      * the return value is implementation-specific.
347      *
348      * @return the default fetch direction for result sets generated
349      * from this <code>Statement</code> object
350      * @exception SQLException if a database access error occurs
351      * @since 1.2
352      * @see #setFetchDirection
353      */

354     int getFetchDirection() throws SQLException JavaDoc;
355
356     /**
357      * Gives the JDBC driver a hint as to the number of rows that should
358      * be fetched from the database when more rows are needed. The number
359      * of rows specified affects only result sets created using this
360      * statement. If the value specified is zero, then the hint is ignored.
361      * The default value is zero.
362      *
363      * @param rows the number of rows to fetch
364      * @exception SQLException if a database access error occurs, or the
365      * condition 0 <= <code>rows</code> <= <code>this.getMaxRows()</code>
366      * is not satisfied.
367      * @since 1.2
368      * @see #getFetchSize
369      */

370     void setFetchSize(int rows) throws SQLException JavaDoc;
371   
372     /**
373      * Retrieves the number of result set rows that is the default
374      * fetch size for <code>ResultSet</code> objects
375      * generated from this <code>Statement</code> object.
376      * If this <code>Statement</code> object has not set
377      * a fetch size by calling the method <code>setFetchSize</code>,
378      * the return value is implementation-specific.
379      *
380      * @return the default fetch size for result sets generated
381      * from this <code>Statement</code> object
382      * @exception SQLException if a database access error occurs
383      * @since 1.2
384      * @see #setFetchSize
385      */

386     int getFetchSize() throws SQLException JavaDoc;
387
388     /**
389      * Retrieves the result set concurrency for <code>ResultSet</code> objects
390      * generated by this <code>Statement</code> object.
391      *
392      * @return either <code>ResultSet.CONCUR_READ_ONLY</code> or
393      * <code>ResultSet.CONCUR_UPDATABLE</code>
394      * @exception SQLException if a database access error occurs
395      * @since 1.2
396      */

397     int getResultSetConcurrency() throws SQLException JavaDoc;
398
399     /**
400      * Retrieves the result set type for <code>ResultSet</code> objects
401      * generated by this <code>Statement</code> object.
402      *
403      * @return one of <code>ResultSet.TYPE_FORWARD_ONLY</code>,
404      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or
405      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>
406      * @exception SQLException if a database access error occurs
407      * @since 1.2
408      */

409     int getResultSetType() throws SQLException JavaDoc;
410
411     /**
412      * Adds the given SQL command to the current list of commmands for this
413      * <code>Statement</code> object. The commands in this list can be
414      * executed as a batch by calling the method <code>executeBatch</code>.
415      * <P>
416      * <B>NOTE:</B> This method is optional.
417      *
418      * @param sql typically this is a static SQL <code>INSERT</code> or
419      * <code>UPDATE</code> statement
420      * @exception SQLException if a database access error occurs, or the
421      * driver does not support batch updates
422      * @see #executeBatch
423      * @since 1.2
424      */

425     void addBatch( String JavaDoc sql ) throws SQLException JavaDoc;
426
427     /**
428      * Empties this <code>Statement</code> object's current list of
429      * SQL commands.
430      * <P>
431      * <B>NOTE:</B> This method is optional.
432      *
433      * @exception SQLException if a database access error occurs or the
434      * driver does not support batch updates
435      * @see #addBatch
436      * @since 1.2
437      */

438     void clearBatch() throws SQLException JavaDoc;
439
440     /**
441      * Submits a batch of commands to the database for execution and
442      * if all commands execute successfully, returns an array of update counts.
443      * The <code>int</code> elements of the array that is returned are ordered
444      * to correspond to the commands in the batch, which are ordered
445      * according to the order in which they were added to the batch.
446      * The elements in the array returned by the method <code>executeBatch</code>
447      * may be one of the following:
448      * <OL>
449      * <LI>A number greater than or equal to zero -- indicates that the
450      * command was processed successfully and is an update count giving the
451      * number of rows in the database that were affected by the command's
452      * execution
453      * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was
454      * processed successfully but that the number of rows affected is
455      * unknown
456      * <P>
457      * If one of the commands in a batch update fails to execute properly,
458      * this method throws a <code>BatchUpdateException</code>, and a JDBC
459      * driver may or may not continue to process the remaining commands in
460      * the batch. However, the driver's behavior must be consistent with a
461      * particular DBMS, either always continuing to process commands or never
462      * continuing to process commands. If the driver continues processing
463      * after a failure, the array returned by the method
464      * <code>BatchUpdateException.getUpdateCounts</code>
465      * will contain as many elements as there are commands in the batch, and
466      * at least one of the elements will be the following:
467      * <P>
468      * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed
469      * to execute successfully and occurs only if a driver continues to
470      * process commands after a command fails
471      * </OL>
472      * <P>
473      * A driver is not required to implement this method.
474      * The possible implementations and return values have been modified in
475      * the Java 2 SDK, Standard Edition, version 1.3 to
476      * accommodate the option of continuing to proccess commands in a batch
477      * update after a <code>BatchUpdateException</code> obejct has been thrown.
478      *
479      * @return an array of update counts containing one element for each
480      * command in the batch. The elements of the array are ordered according
481      * to the order in which commands were added to the batch.
482      * @exception SQLException if a database access error occurs or the
483      * driver does not support batch statements. Throws {@link BatchUpdateException}
484      * (a subclass of <code>SQLException</code>) if one of the commands sent to the
485      * database fails to execute properly or attempts to return a result set.
486      * @since 1.3
487      */

488     int[] executeBatch() throws SQLException JavaDoc;
489
490     /**
491      * Retrieves the <code>Connection</code> object
492      * that produced this <code>Statement</code> object.
493      * @return the connection that produced this statement
494      * @exception SQLException if a database access error occurs
495      * @since 1.2
496      */

497     Connection JavaDoc getConnection() throws SQLException JavaDoc;
498
499   //--------------------------JDBC 3.0-----------------------------
500

501     /**
502      * The constant indicating that the current <code>ResultSet</code> object
503      * should be closed when calling <code>getMoreResults</code>.
504      *
505      * @since 1.4
506      */

507     int CLOSE_CURRENT_RESULT = 1;
508
509     /**
510      * The constant indicating that the current <code>ResultSet</code> object
511      * should not be closed when calling <code>getMoreResults</code>.
512      *
513      * @since 1.4
514      */

515     int KEEP_CURRENT_RESULT = 2;
516
517     /**
518      * The constant indicating that all <code>ResultSet</code> objects that
519      * have previously been kept open should be closed when calling
520      * <code>getMoreResults</code>.
521      *
522      * @since 1.4
523      */

524     int CLOSE_ALL_RESULTS = 3;
525
526     /**
527      * The constant indicating that a batch statement executed successfully
528      * but that no count of the number of rows it affected is available.
529      *
530      * @since 1.4
531      */

532     int SUCCESS_NO_INFO = -2;
533
534     /**
535      * The constant indicating that an error occured while executing a
536      * batch statement.
537      *
538      * @since 1.4
539      */

540     int EXECUTE_FAILED = -3;
541
542     /**
543      * The constant indicating that generated keys should be made
544      * available for retrieval.
545      *
546      * @since 1.4
547      */

548     int RETURN_GENERATED_KEYS = 1;
549
550     /**
551      * The constant indicating that generated keys should not be made
552      * available for retrieval.
553      *
554      * @since 1.4
555      */

556     int NO_GENERATED_KEYS = 2;
557
558     /**
559      * Moves to this <code>Statement</code> object's next result, deals with
560      * any current <code>ResultSet</code> object(s) according to the instructions
561      * specified by the given flag, and returns
562      * <code>true</code> if the next result is a <code>ResultSet</code> object.
563      *
564      * <P>There are no more results when the following is true:
565      * <PRE>
566      * // stmt is a Statement object
567      * ((stmt.getMoreResults() == false) && (stmt.getUpdateCount() == -1))
568      * </PRE>
569      *
570      * @param current one of the following <code>Statement</code>
571      * constants indicating what should happen to current
572      * <code>ResultSet</code> objects obtained using the method
573      * <code>getResultSet</code>:
574      * <code>Statement.CLOSE_CURRENT_RESULT</code>,
575      * <code>Statement.KEEP_CURRENT_RESULT</code>, or
576      * <code>Statement.CLOSE_ALL_RESULTS</code>
577      * @return <code>true</code> if the next result is a <code>ResultSet</code>
578      * object; <code>false</code> if it is an update count or there are no
579      * more results
580      * @exception SQLException if a database access error occurs or the argument
581      * supplied is not one of the following:
582      * <code>Statement.CLOSE_CURRENT_RESULT</code>,
583      * <code>Statement.KEEP_CURRENT_RESULT</code>, or
584      * <code>Statement.CLOSE_ALL_RESULTS</code>
585      * @since 1.4
586      * @see #execute
587      */

588     boolean getMoreResults(int current) throws SQLException JavaDoc;
589
590     /**
591      * Retrieves any auto-generated keys created as a result of executing this
592      * <code>Statement</code> object. If this <code>Statement</code> object did
593      * not generate any keys, an empty <code>ResultSet</code>
594      * object is returned.
595      *
596      * @return a <code>ResultSet</code> object containing the auto-generated key(s)
597      * generated by the execution of this <code>Statement</code> object
598      * @exception SQLException if a database access error occurs
599      * @since 1.4
600      */

601     ResultSet JavaDoc getGeneratedKeys() throws SQLException JavaDoc;
602
603     /**
604      * Executes the given SQL statement and signals the driver with the
605      * given flag about whether the
606      * auto-generated keys produced by this <code>Statement</code> object
607      * should be made available for retrieval.
608      *
609      * @param sql must be an SQL <code>INSERT</code>, <code>UPDATE</code> or
610      * <code>DELETE</code> statement or an SQL statement that
611      * returns nothing
612      * @param autoGeneratedKeys a flag indicating whether auto-generated keys
613      * should be made available for retrieval;
614      * one of the following constants:
615      * <code>Statement.RETURN_GENERATED_KEYS</code>
616      * <code>Statement.NO_GENERATED_KEYS</code>
617      * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>
618      * or <code>DELETE</code> statements, or <code>0</code> for SQL
619      * statements that return nothing
620      * @exception SQLException if a database access error occurs, the given
621      * SQL statement returns a <code>ResultSet</code> object, or
622      * the given constant is not one of those allowed
623      * @since 1.4
624      */

625     int executeUpdate(String JavaDoc sql, int autoGeneratedKeys) throws SQLException JavaDoc;
626
627     /**
628      * Executes the given SQL statement and signals the driver that the
629      * auto-generated keys indicated in the given array should be made available
630      * for retrieval. The driver will ignore the array if the SQL statement
631      * is not an <code>INSERT</code> statement.
632      *
633      * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
634      * <code>DELETE</code> statement or an SQL statement that returns nothing,
635      * such as an SQL DDL statement
636      * @param columnIndexes an array of column indexes indicating the columns
637      * that should be returned from the inserted row
638      * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
639      * or <code>DELETE</code> statements, or 0 for SQL statements
640      * that return nothing
641      * @exception SQLException if a database access error occurs, the SQL
642      * statement returns a <code>ResultSet</code> object, or the
643      * second argument supplied to this method is not an <code>int</code> array
644      * whose elements are valid column indexes
645      * @since 1.4
646      */

647     int executeUpdate(String JavaDoc sql, int columnIndexes[]) throws SQLException JavaDoc;
648
649     /**
650      * Executes the given SQL statement and signals the driver that the
651      * auto-generated keys indicated in the given array should be made available
652      * for retrieval. The driver will ignore the array if the SQL statement
653      * is not an <code>INSERT</code> statement.
654      *
655      * @param sql an SQL <code>INSERT</code>, <code>UPDATE</code> or
656      * <code>DELETE</code> statement or an SQL statement that returns nothing
657      * @param columnNames an array of the names of the columns that should be
658      * returned from the inserted row
659      * @return either the row count for <code>INSERT</code>, <code>UPDATE</code>,
660      * or <code>DELETE</code> statements, or 0 for SQL statements
661      * that return nothing
662      * @exception SQLException if a database access error occurs, the SQL
663      * statement returns a <code>ResultSet</code> object, or the
664      * second argument supplied to this method is not a <code>String</code> array
665      * whose elements are valid column names
666      *
667      * @since 1.4
668      */

669     int executeUpdate(String JavaDoc sql, String JavaDoc columnNames[]) throws SQLException JavaDoc;
670
671     /**
672      * Executes the given SQL statement, which may return multiple results,
673      * and signals the driver that any
674      * auto-generated keys should be made available
675      * for retrieval. The driver will ignore this signal if the SQL statement
676      * is not an <code>INSERT</code> statement.
677      * <P>
678      * In some (uncommon) situations, a single SQL statement may return
679      * multiple result sets and/or update counts. Normally you can ignore
680      * this unless you are (1) executing a stored procedure that you know may
681      * return multiple results or (2) you are dynamically executing an
682      * unknown SQL string.
683      * <P>
684      * The <code>execute</code> method executes an SQL statement and indicates the
685      * form of the first result. You must then use the methods
686      * <code>getResultSet</code> or <code>getUpdateCount</code>
687      * to retrieve the result, and <code>getMoreResults</code> to
688      * move to any subsequent result(s).
689      *
690      * @param sql any SQL statement
691      * @param autoGeneratedKeys a constant indicating whether auto-generated
692      * keys should be made available for retrieval using the method
693      * <code>getGeneratedKeys</code>; one of the following constants:
694      * <code>Statement.RETURN_GENERATED_KEYS</code> or
695      * <code>Statement.NO_GENERATED_KEYS</code>
696      * @return <code>true</code> if the first result is a <code>ResultSet</code>
697      * object; <code>false</code> if it is an update count or there are
698      * no results
699      * @exception SQLException if a database access error occurs or the second
700      * parameter supplied to this method is not
701      * <code>Statement.RETURN_GENERATED_KEYS</code> or
702      * <code>Statement.NO_GENERATED_KEYS</code>.
703      * @see #getResultSet
704      * @see #getUpdateCount
705      * @see #getMoreResults
706      * @see #getGeneratedKeys
707      *
708      * @since 1.4
709      */

710     boolean execute(String JavaDoc sql, int autoGeneratedKeys) throws SQLException JavaDoc;
711
712     /**
713      * Executes the given SQL statement, which may return multiple results,
714      * and signals the driver that the
715      * auto-generated keys indicated in the given array should be made available
716      * for retrieval. This array contains the indexes of the columns in the
717      * target table that contain the auto-generated keys that should be made
718      * available. The driver will ignore the array if the given SQL statement
719      * is not an <code>INSERT</code> statement.
720      * <P>
721      * Under some (uncommon) situations, a single SQL statement may return
722      * multiple result sets and/or update counts. Normally you can ignore
723      * this unless you are (1) executing a stored procedure that you know may
724      * return multiple results or (2) you are dynamically executing an
725      * unknown SQL string.
726      * <P>
727      * The <code>execute</code> method executes an SQL statement and indicates the
728      * form of the first result. You must then use the methods
729      * <code>getResultSet</code> or <code>getUpdateCount</code>
730      * to retrieve the result, and <code>getMoreResults</code> to
731      * move to any subsequent result(s).
732      *
733      * @param sql any SQL statement
734      * @param columnIndexes an array of the indexes of the columns in the
735      * inserted row that should be made available for retrieval by a
736      * call to the method <code>getGeneratedKeys</code>
737      * @return <code>true</code> if the first result is a <code>ResultSet</code>
738      * object; <code>false</code> if it is an update count or there
739      * are no results
740      * @exception SQLException if a database access error occurs or the
741      * elements in the <code>int</code> array passed to this method
742      * are not valid column indexes
743      * @see #getResultSet
744      * @see #getUpdateCount
745      * @see #getMoreResults
746      *
747      * @since 1.4
748      */

749     boolean execute(String JavaDoc sql, int columnIndexes[]) throws SQLException JavaDoc;
750
751     /**
752      * Executes the given SQL statement, which may return multiple results,
753      * and signals the driver that the
754      * auto-generated keys indicated in the given array should be made available
755      * for retrieval. This array contains the names of the columns in the
756      * target table that contain the auto-generated keys that should be made
757      * available. The driver will ignore the array if the given SQL statement
758      * is not an <code>INSERT</code> statement.
759      * <P>
760      * In some (uncommon) situations, a single SQL statement may return
761      * multiple result sets and/or update counts. Normally you can ignore
762      * this unless you are (1) executing a stored procedure that you know may
763      * return multiple results or (2) you are dynamically executing an
764      * unknown SQL string.
765      * <P>
766      * The <code>execute</code> method executes an SQL statement and indicates the
767      * form of the first result. You must then use the methods
768      * <code>getResultSet</code> or <code>getUpdateCount</code>
769      * to retrieve the result, and <code>getMoreResults</code> to
770      * move to any subsequent result(s).
771      *
772      * @param sql any SQL statement
773      * @param columnNames an array of the names of the columns in the inserted
774      * row that should be made available for retrieval by a call to the
775      * method <code>getGeneratedKeys</code>
776      * @return <code>true</code> if the next result is a <code>ResultSet</code>
777      * object; <code>false</code> if it is an update count or there
778      * are no more results
779      * @exception SQLException if a database access error occurs or the
780      * elements of the <code>String</code> array passed to this
781      * method are not valid column names
782      * @see #getResultSet
783      * @see #getUpdateCount
784      * @see #getMoreResults
785      * @see #getGeneratedKeys
786      *
787      * @since 1.4
788      */

789     boolean execute(String JavaDoc sql, String JavaDoc columnNames[]) throws SQLException JavaDoc;
790
791    /**
792      * Retrieves the result set holdability for <code>ResultSet</code> objects
793      * generated by this <code>Statement</code> object.
794      *
795      * @return either <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or
796      * <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>
797      * @exception SQLException if a database access error occurs
798      *
799      * @since 1.4
800      */

801     int getResultSetHoldability() throws SQLException JavaDoc;
802
803 }
804
Popular Tags