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