001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.sql;
019:
020: /**
021: * Interface used for executing static SQL statements and returning their
022: * results.
023: *
024: * By default, an object implementing the Statement interface can returns
025: * results as ResultSets. For any given Statement object, only one ResultSet can
026: * be open at one time. A call to any of the execution methods of Statement will
027: * cause any previously created ResultSet object for that Statement to be closed
028: * implicitly.
029: * <p>
030: * To have multiple ResultSet objects open concurrently, multiple Statement
031: * objects must be used.
032: */
033: public interface Statement {
034:
035: /**
036: * Passing this constant to getMoreResults implies that all ResultSet
037: * objects previously kept open should be closed.
038: */
039: public static final int CLOSE_ALL_RESULTS = 3;
040:
041: /**
042: * Passing this constant to getMoreResults implies that the current
043: * ResultSet object should be closed
044: */
045: public static final int CLOSE_CURRENT_RESULT = 1;
046:
047: /**
048: * Indicates that an error was encountered during execution of a batch
049: * statement.
050: */
051: public static final int EXECUTE_FAILED = -3;
052:
053: /**
054: * Passing this constant to getMoreResults implies that the current
055: * ResultSet object should not be closed.
056: */
057: public static final int KEEP_CURRENT_RESULT = 2;
058:
059: /**
060: * Indicates that generated keys should not be accessible for retrieval.
061: */
062: public static final int NO_GENERATED_KEYS = 2;
063:
064: /**
065: * Indicates that generated keys should be accessible for retrieval.
066: */
067: public static final int RETURN_GENERATED_KEYS = 1;
068:
069: /**
070: * Indicates that a batch statement was executed with a successful result,
071: * but a count of the number of rows it affected is unavailable.
072: */
073: public static final int SUCCESS_NO_INFO = -2;
074:
075: /**
076: * Adds a specified SQL commands to the list of commands for this Statement.
077: * <p>
078: * The list of commands is executed by invoking the
079: * <code>executeBatch</code> method.
080: *
081: * @param sql
082: * the SQL command as a String. Typically an INSERT or UPDATE
083: * statement.
084: * @throws SQLException
085: * if an error occurs accessing the database or the database
086: * does not support batch updates
087: */
088: public void addBatch(String sql) throws SQLException;
089:
090: /**
091: * Cancels this Statement execution if both the database and the JDBC driver
092: * support aborting an SQL statement in flight. This method can be used by
093: * one thread to stop a Statement that is being executed on another thread.
094: *
095: * @throws SQLException
096: * if an error occurs accessing the database
097: */
098: public void cancel() throws SQLException;
099:
100: /**
101: * Clears the current list of SQL commands for this Statement.
102: *
103: * @throws SQLException
104: * if an error occurs accessing the database or the database
105: * does not support batch updates
106: */
107: public void clearBatch() throws SQLException;
108:
109: /**
110: * Clears all SQLWarnings from this Statement.
111: *
112: * @throws SQLException
113: * if an error occurs accessing the database
114: */
115: public void clearWarnings() throws SQLException;
116:
117: /**
118: * Releases this Statement's database and JDBC driver resources.
119: * <p>
120: * Using this method to release these resources as soon as possible is
121: * strongly recommended. It is not a good idea to rely on these resources
122: * being released when the Statement object is finalized during garbage
123: * collection. Doing so can result in unpredictable performance
124: * characteristics for the application.
125: *
126: * @throws SQLException
127: * if an error occurs accessing the database
128: */
129: public void close() throws SQLException;
130:
131: /**
132: * Executes a supplied SQL statement. This may return multiple ResultSets.
133: * <p>
134: * Use the <code>getResultSet</code> or <code>getUpdateCount</code>
135: * methods to get the first result and <code>getMoreResults</code> to get
136: * any subsequent results.
137: *
138: * @param sql
139: * the SQL statement to execute
140: * @return true if the first result is a ResultSet, false if the first
141: * result is an update count or if there is no result
142: * @throws SQLException
143: * if an error occurs accessing the database
144: */
145: public boolean execute(String sql) throws SQLException;
146:
147: /**
148: * Executes a supplied SQL statement. This may return multiple ResultSets.
149: * This method allows control of whether auto-generated Keys should be made
150: * available for retrieval, if the SQL statement is an INSERT statement.
151: * <p>
152: * Use the <code>getResultSet</code> or <code>getUpdateCount</code>
153: * methods to get the first result and <code>getMoreResults</code> to get
154: * any subsequent results.
155: *
156: * @param sql
157: * the SQL statement to execute
158: * @param autoGeneratedKeys
159: * a flag indicating whether to make auto generated keys
160: * available for retrieval. This parameter must be one of
161: * Statement.NO_GENERATED_KEYS or Statement.RETURN_GENERATED_KEYS
162: * @return true if results exists and the first result is a ResultSet, false
163: * if the first result is an update count or if there is no result
164: * @throws SQLException
165: * if an error occurs accessing the database
166: */
167: public boolean execute(String sql, int autoGeneratedKeys)
168: throws SQLException;
169:
170: /**
171: * Executes the supplied SQL statement. This may return multiple ResultSets.
172: * This method allows retrieval of auto generated keys specified by the
173: * supplied array of column indexes, if the SQL statement is an INSERT
174: * statement.
175: * <p>
176: * Use the <code>getResultSet</code> or <code>getUpdateCount</code>
177: * methods to get the first result and <code>getMoreResults</code> to get
178: * any subsequent results.
179: *
180: * @param sql
181: * the SQL statement to execute
182: * @param columnIndexes
183: * an array of indexes of the columns in the inserted row which
184: * should be made available for retrieval via the
185: * <code>getGeneratedKeys</code> method.
186: * @return true if the first result is a ResultSet, false if the first
187: * result is an update count or if there is no result
188: * @throws SQLException
189: * if an error occurs accessing the database
190: */
191: public boolean execute(String sql, int[] columnIndexes)
192: throws SQLException;
193:
194: /**
195: * Executes the supplied SQL statement. This may return multiple ResultSets.
196: * This method allows retrieval of auto generated keys specified by the
197: * supplied array of column indexes, if the SQL statement is an INSERT
198: * statement.
199: * <p>
200: * Use the <code>getResultSet</code> or <code>getUpdateCount</code>
201: * methods to get the first result and <code>getMoreResults</code> to get
202: * any subsequent results.
203: *
204: * @param sql
205: * the SQL statement to execute
206: * @param columnNames
207: * an array of column names in the inserted row which should be
208: * made available for retrieval via the
209: * <code>getGeneratedKeys</code> method.
210: * @return true if the first result is a ResultSet, false if the first
211: * result is an update count or if there is no result
212: * @throws SQLException
213: * if an error occurs accessing the database
214: */
215: public boolean execute(String sql, String[] columnNames)
216: throws SQLException;
217:
218: /**
219: * Submits a batch of SQL commands to the database. Returns an array of
220: * update counts, if all the commands execute successfully.
221: * <p>
222: * If one of the commands in the batch fails, this method can throw a
223: * BatchUpdateException and the JDBC driver may or may not process the
224: * remaining commands. The JDBC driver must behave consistently with the
225: * underlying database, either always continuing or never continuing. If the
226: * driver continues processing, the array of results returned contains the
227: * same number of elements as there are commands in the batch, with a
228: * minimum of one of the elements having the EXECUTE_FAILED value.
229: *
230: * @return an array of update counts, with one entry for each command in the
231: * batch. The elements are ordered according to the order in which
232: * the commands were added to the batch.
233: * <p>
234: * <ol>
235: * <li> If the value of an element is >=0, the corresponding command
236: * completed successfully and the value is the update count for that
237: * command, which is the number of rows in the database affected by
238: * the command.</li>
239: * <li> If the value is SUCCESS_NO_INFO, the command completed
240: * successfully but the number of rows affected is unknown.
241: * <li>
242: * <li> If the value is EXECUTE_FAILED, the command failed.
243: * </ol>
244: * @throws SQLException
245: * if an error occurs accessing the database
246: */
247: public int[] executeBatch() throws SQLException;
248:
249: /**
250: * Executes a supplied SQL statement. Returns a single ResultSet.
251: *
252: * @param sql
253: * an SQL statement to execute. Typically a SELECT statement
254: * @return a ResultSet containing the data produced by the SQL statement.
255: * Never null.
256: * @throws SQLException
257: * if an error occurs accessing the database or if the statement
258: * produces anything other than a single ResultSet
259: */
260: public ResultSet executeQuery(String sql) throws SQLException;
261:
262: /**
263: * Executes the supplied SQL statement. The statement may be an INSERT,
264: * UPDATE or DELETE statement or a statement which returns nothing.
265: *
266: * @param sql
267: * an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or
268: * a statement which returns nothing
269: * @return the count of updated rows, or 0 for a statement that returns
270: * nothing.
271: * @throws SQLException
272: * if an error occurs accessing the database or if the statement
273: * produces a ResultSet
274: */
275: public int executeUpdate(String sql) throws SQLException;
276:
277: /**
278: * Executes the supplied SQL statement. This method allows control of
279: * whether auto-generated Keys should be made available for retrieval.
280: *
281: * @param sql
282: * an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or
283: * a statement which does not return anything.
284: * @param autoGeneratedKeys
285: * a flag that indicates whether to allow retrieval of auto
286: * generated keys. Parameter must be one of
287: * Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS
288: * @return the number of updated rows, or 0 if the statement returns
289: * nothing.
290: * @throws SQLException
291: * if an error occurs accessing the database or if the statement
292: * produces a ResultSet
293: */
294: public int executeUpdate(String sql, int autoGeneratedKeys)
295: throws SQLException;
296:
297: /**
298: * Executes the supplied SQL statement. This method allows retrieval of auto
299: * generated keys specified by the supplied array of column indexes.
300: *
301: * @param sql
302: * an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or
303: * a statement which returns nothing
304: * @param columnIndexes
305: * an array of indexes of the columns in the inserted row which
306: * should be made available for retrieval via the
307: * <code>getGeneratedKeys</code> method.
308: * @return the count of updated rows, or 0 for a statement that returns
309: * nothing.
310: * @throws SQLException
311: * if an error occurs accessing the database or if the statement
312: * produces a ResultSet
313: */
314: public int executeUpdate(String sql, int[] columnIndexes)
315: throws SQLException;
316:
317: /**
318: * Executes the supplied SQL statement. This method allows retrieval of auto
319: * generated keys specified by the supplied array of column names.
320: *
321: * @param sql
322: * an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or
323: * a statement which returns nothing
324: * @param columnNames
325: * an array of column names in the inserted row which should be
326: * made available for retrieval via the
327: * <code>getGeneratedKeys</code> method.
328: * @return the count of updated rows, or 0 for a statement that returns
329: * nothing.
330: * @throws SQLException
331: * if an error occurs accessing the database or if the statement
332: * produces a ResultSet
333: */
334: public int executeUpdate(String sql, String[] columnNames)
335: throws SQLException;
336:
337: /**
338: * Gets the Connection that produced this Statement.
339: *
340: * @return the Connection
341: * @throws SQLException
342: * if an error occurs accessing the database
343: */
344: public Connection getConnection() throws SQLException;
345:
346: /**
347: * Gets the default direction for fetching rows for ResultSets generated
348: * from this Statement.
349: *
350: * @return an integer describing the default fetch direction, one of:
351: * ResultSet.FETCH_FORWARD, ResultSet.FETCH_REVERSE,
352: * ResultSet.FETCH_UNKNOWN
353: * @throws SQLException
354: * if an error occurs accessing the database
355: */
356: public int getFetchDirection() throws SQLException;
357:
358: /**
359: * Gets the default number of rows for a fetch for the ResultSet objects
360: * returned from this Statement.
361: *
362: * @return the default fetch size for ResultSets produced by this Statement
363: * @throws SQLException
364: * if an error occurs accessing the database
365: */
366: public int getFetchSize() throws SQLException;
367:
368: /**
369: * Returns auto generated keys created by executing this Statement.
370: *
371: * @return a ResultSet containing the auto generated keys - empty if no keys
372: * were generated by the Statement
373: * @throws SQLException
374: * if an error occurs accessing the database
375: */
376: public ResultSet getGeneratedKeys() throws SQLException;
377:
378: /**
379: * Gets the maximum number of bytes which can be returned for values from
380: * Character and Binary values in a ResultSet derived from this Statement.
381: * This limit applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR,
382: * and LONGVARCHAR types. Any data exceeding the maximum size is abandoned
383: * without announcement.
384: *
385: * @return the current size limit, where 0 means that there is no limit
386: * @throws SQLException
387: * if an error occurs accessing the database
388: */
389: public int getMaxFieldSize() throws SQLException;
390:
391: /**
392: * Gets the maximum number of rows that a ResultSet can contain when
393: * produced from this Statement. If the limit is exceeded, the excess rows
394: * are discarded silently.
395: *
396: * @return the current row limit, where 0 means that there is no limit.
397: * @throws SQLException
398: * if an error occurs accessing the database
399: */
400: public int getMaxRows() throws SQLException;
401:
402: /**
403: * Moves to this Statement's next result. Returns true if it is a ResultSet.
404: * Any current ResultSet objects previously obtained with
405: * <code>getResultSet()</code> are closed implicitly.
406: *
407: * @return true if the next result is a ResultSet, false if the next result
408: * is not a ResultSet or if there are no more results. Note that if
409: * there is no more data, this method will return false and
410: * <code>getUpdateCount</code> will return -1.
411: * @throws SQLException
412: * if an error occurs accessing the database
413: */
414: public boolean getMoreResults() throws SQLException;
415:
416: /**
417: * Moves to this Statement's next result. Returns true if the next result is
418: * a ResultSet. Any current ResultSet objects previously obtained with
419: * <code>getResultSet()</code> are handled as indicated by a supplied Flag
420: * parameter.
421: *
422: * @param current
423: * a flag indicating what to do with existing ResultSets. This
424: * parameter must be one of Statement.CLOSE_ALL_RESULTS,
425: * Statement.CLOSE_CURRENT_RESULT or
426: * Statement.KEEP_CURRENT_RESULT.
427: * @return true if the next result exists and is a ResultSet, false if the
428: * next result is not a ResultSet or if there are no more results.
429: * Note that if there is no more data, this method will return false
430: * and <code>getUpdateCount</code> will return -1.
431: * @throws SQLException
432: * if an error occurs accessing the database
433: */
434: public boolean getMoreResults(int current) throws SQLException;
435:
436: /**
437: * Gets the timeout value for Statement execution. The JDBC driver will wait
438: * up to this value for the execution to complete - after the limit is
439: * exceeded an SQL Exception is thrown.
440: *
441: * @return the current Query Timeout value, where 0 indicates that there is
442: * no current timeout.
443: * @throws SQLException
444: * if an error occurs accessing the database
445: */
446: public int getQueryTimeout() throws SQLException;
447:
448: /**
449: * Gets the current result. Should only be called once per result.
450: *
451: * @return the ResultSet for the current result. null if the result is an
452: * update count or if there are no more results.
453: * @throws SQLException
454: * if an error occurs accessing the database
455: */
456: public ResultSet getResultSet() throws SQLException;
457:
458: /**
459: * Gets the concurrency setting for ResultSet objects generated by this
460: * Statement.
461: *
462: * @return ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
463: * @throws SQLException
464: * if an error occurs accessing the database
465: */
466: public int getResultSetConcurrency() throws SQLException;
467:
468: /**
469: * Gets the cursor hold setting for ResultSet objects generated by this
470: * Statement.
471: *
472: * @return ResultSet.HOLD_CURSORS_OVER_COMMIT or
473: * ResultSet.CLOSE_CURSORS_AT_COMMIT
474: * @throws SQLException
475: * if there is an error while accessing the database
476: */
477: public int getResultSetHoldability() throws SQLException;
478:
479: /**
480: * Gets the ResultSet type setting for ResultSets derived from this
481: * Statement.
482: *
483: * @return ResultSet.TYPE_FORWARD_ONLY for a ResultSet where the cursor can
484: * only move forward, ResultSet.TYPE_SCROLL_INSENSITIVE for a
485: * ResultSet which is Scrollable but is not sensitive to changes
486: * made by others, ResultSet.TYPE_SCROLL_SENSITIVE for a ResultSet
487: * which is Scrollable but is sensitive to changes made by others
488: * @throws SQLException
489: * if there is an error accessing the database
490: */
491: public int getResultSetType() throws SQLException;
492:
493: /**
494: * Gets an update count for the current result if it is not a ResultSet.
495: *
496: * @return the current result as an update count. -1 if the current result
497: * is a ResultSet or if there are no more results
498: * @throws SQLException
499: * if an error occurs accessing the database
500: */
501: public int getUpdateCount() throws SQLException;
502:
503: /**
504: * Retrieves the first SQLWarning reported by calls on this Statement.
505: * <p>
506: * If there are multiple warnings, subsequent warnings are chained to the
507: * first one.
508: * <p>
509: * The chain or warnings is cleared each time the Statement is executed.
510: * <p>
511: * Warnings associated with reads from the ResultSet returned from executing
512: * a Statement will be attached to the ResultSet, not the Statement object.
513: *
514: * @return an SQLWarning, null if there are no warnings
515: * @throws SQLException
516: * if an error occurs accessing the database
517: */
518: public SQLWarning getWarnings() throws SQLException;
519:
520: /**
521: * Sets the SQL cursor name. This name is used by subsequent Statement
522: * execute methods.
523: * <p>
524: * Cursor names must be unique within one Connection.
525: * <p>
526: * With the Cursor name set, it can then be utilized in SQL positioned
527: * update or delete statements to determine the current row in a ResultSet
528: * generated from this Statement. The positioned update or delete must be
529: * done with a different Statement than this one.
530: *
531: * @param name
532: * the Cursor name as a String,
533: * @throws SQLException
534: * if an error occurs accessing the database
535: */
536: public void setCursorName(String name) throws SQLException;
537:
538: /**
539: * Sets Escape Processing mode.
540: * <p>
541: * If Escape Processing is on, the JDBC driver will do escape substitution
542: * on an SQL statement before sending it for execution. This does not apply
543: * to PreparedStatements since they are processed when created, before this
544: * method can be called.
545: *
546: * @param enable
547: * true to set escape processing mode on, false to turn it off.
548: * @throws SQLException
549: * if an error occurs accessing the database
550: */
551: public void setEscapeProcessing(boolean enable) throws SQLException;
552:
553: /**
554: * Sets the fetch direction - a hint to the JDBC driver about the direction
555: * of processing of rows in ResultSets created by this Statement. The
556: * default fetch direction is FETCH_FORWARD.
557: *
558: * @param direction
559: * which fetch direction to use. This parameter should be one of
560: * ResultSet.FETCH_UNKNOWN, ResultSet.FETCH_FORWARD or
561: * ResultSet.FETCH_REVERSE
562: * @throws SQLException
563: * if there is an error while accessing the database or if the
564: * fetch direction is unrecognized
565: */
566: public void setFetchDirection(int direction) throws SQLException;
567:
568: /**
569: * Sets the fetch size. This is a hint to the JDBC driver about how many
570: * rows should be fetched from the database when more are required by
571: * application processing.
572: *
573: * @param rows
574: * the number of rows that should be fetched. 0 tells the driver
575: * to ignore the hint. Should be less than
576: * <code>getMaxRows</code> for this statement. Should not be
577: * negative.
578: * @throws SQLException
579: * if an error occurs accessing the database, or if the rows
580: * parameter is out of range.
581: */
582: public void setFetchSize(int rows) throws SQLException;
583:
584: /**
585: * Sets the maximum number of bytes for ResultSet columns that contain
586: * character or binary values. This applies to BINARY, VARBINARY,
587: * LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. Any data exceeding
588: * the maximum size is abandoned without announcement.
589: *
590: * @param max
591: * the maximum field size in bytes. O means "no limit".
592: * @throws SQLException
593: * if an error occurs accessing the database or the max value is
594: * <0.
595: */
596: public void setMaxFieldSize(int max) throws SQLException;
597:
598: /**
599: * Sets the maximum number of rows that any ResultSet can contain. If the
600: * number of rows exceeds this value, the additional rows are silently
601: * discarded.
602: *
603: * @param max
604: * the maximum number of rows. 0 means "no limit".
605: * @throws SQLException
606: * if an error occurs accessing the database or if max <0.
607: */
608: public void setMaxRows(int max) throws SQLException;
609:
610: /**
611: * Sets the timeout, in seconds, for queries - how long the driver will
612: * allow for completion of a Statement execution. If the timeout is
613: * exceeded, the query will throw an SQLException.
614: *
615: * @param seconds
616: * timeout in seconds. 0 means no timeout ("wait forever")
617: * @throws SQLException
618: * if an error occurs accessing the database or if seconds <0.
619: */
620: public void setQueryTimeout(int seconds) throws SQLException;
621: }
|