1 /*

     2  * Copyright 1996-2006 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 package java.sql;

    27 

    28 /**

    29  * <P>The object used for executing a static SQL statement

    30  * and returning the results it produces.

    31  * <P>

    32  * By default, only one <code>ResultSet</code> object per <code>Statement</code>

    33  * object can be open at the same time. Therefore, if the reading of one

    34  * <code>ResultSet</code> object is interleaved

    35  * with the reading of another, each must have been generated by

    36  * different <code>Statement</code> objects. All execution methods in the

    37  * <code>Statement</code> interface implicitly close a statment's current

    38  * <code>ResultSet</code> object if an open one exists.

    39  *

    40  * @see Connection#createStatement

    41  * @see ResultSet

    42  */

    43 public interface Statement extends Wrapper {

    44 

    45     /**

    46      * Executes the given SQL statement, which returns a single

    47      * <code>ResultSet</code> object.

    48      *

    49      * @param sql an SQL statement to be sent to the database, typically a

    50      *        static SQL <code>SELECT</code> statement

    51      * @return a <code>ResultSet</code> object that contains the data produced

    52      *         by the given query; never <code>null</code>

    53      * @exception SQLException if a database access error occurs,

    54      * this method is called on a closed <code>Statement</code> or the given

    55      *            SQL statement produces anything other than a single

    56      *            <code>ResultSet</code> object

    57      */

    58     ResultSet executeQuery(String sql) throws SQLException;

    59 

    60     /**

    61      * Executes the given SQL statement, which may be an <code>INSERT</code>,

    62      * <code>UPDATE</code>, or <code>DELETE</code> statement or an

    63      * SQL statement that returns nothing, such as an SQL DDL statement.

    64      *

    65      * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or

    66      * <code>DELETE</code>; or an SQL statement that returns nothing,

    67      * such as a DDL statement.

    68      *

    69      * @return either (1) the row count for SQL Data Manipulation Language (DML) statements

    70      *         or (2) 0 for SQL statements that return nothing

    71      *

    72      * @exception SQLException if a database access error occurs,

    73      * this method is called on a closed <code>Statement</code> or the given

    74      *            SQL statement produces a <code>ResultSet</code> object

    75      */

    76     int executeUpdate(String sql) throws SQLException;

    77 

    78     /**

    79      * Releases this <code>Statement</code> object's database

    80      * and JDBC resources immediately instead of waiting for

    81      * this to happen when it is automatically closed.

    82      * It is generally good practice to release resources as soon as

    83      * you are finished with them to avoid tying up database

    84      * resources.

    85      * <P>

    86      * Calling the method <code>close</code> on a <code>Statement</code>

    87      * object that is already closed has no effect.

    88      * <P>

    89      * <B>Note:</B>When a <code>Statement</code> object is

    90      * closed, its current <code>ResultSet</code> object, if one exists, is

    91      * also closed.

    92      *

    93      * @exception SQLException if a database access error occurs

    94      */

    95     void close() throws SQLException;

    96 

    97     //----------------------------------------------------------------------

    98 

    99     /**

   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 

   363     //--------------------------JDBC 2.0-----------------------------

   364 

   365 

   366     /**

   367      * Gives the driver a hint as to the direction in which

   368      * rows will be processed in <code>ResultSet</code>

   369      * objects created using this <code>Statement</code> object.  The

   370      * default value is <code>ResultSet.FETCH_FORWARD</code>.

   371      * <P>

   372      * Note that this method sets the default fetch direction for

   373      * result sets generated by this <code>Statement</code> object.

   374      * Each result set has its own methods for getting and setting

   375      * its own fetch direction.

   376      *

   377      * @param direction the initial direction for processing rows

   378      * @exception SQLException if a database access error occurs,

   379      * this method is called on a closed <code>Statement</code>

   380      * or the given direction

   381      * is not one of <code>ResultSet.FETCH_FORWARD</code>,

   382      * <code>ResultSet.FETCH_REVERSE</code>, or <code>ResultSet.FETCH_UNKNOWN</code>

   383      * @since 1.2

   384      * @see #getFetchDirection

   385      */

   386     void setFetchDirection(int direction) throws SQLException;

   387 

   388     /**

   389      * Retrieves the direction for fetching rows from

   390      * database tables that is the default for result sets

   391      * generated from this <code>Statement</code> object.

   392      * If this <code>Statement</code> object has not set

   393      * a fetch direction by calling the method <code>setFetchDirection</code>,

   394      * the return value is implementation-specific.

   395      *

   396      * @return the default fetch direction for result sets generated

   397      *          from this <code>Statement</code> object

   398      * @exception SQLException if a database access error occurs or

   399      * this method is called on a closed <code>Statement</code>

   400      * @since 1.2

   401      * @see #setFetchDirection

   402      */

   403     int getFetchDirection() throws SQLException;

   404 

   405     /**

   406      * Gives the JDBC driver a hint as to the number of rows that should

   407      * be fetched from the database when more rows are needed for

   408      * <code>ResultSet</code> objects genrated by this <code>Statement</code>.

   409      * If the value specified is zero, then the hint is ignored.

   410      * The default value is zero.

   411      *

   412      * @param rows the number of rows to fetch

   413      * @exception SQLException if a database access error occurs,

   414      * this method is called on a closed <code>Statement</code> or the

   415      *        condition  <code>rows >= 0</code> is not satisfied.

   416      * @since 1.2

   417      * @see #getFetchSize

   418      */

   419     void setFetchSize(int rows) throws SQLException;

   420 

   421     /**

   422      * Retrieves the number of result set rows that is the default

   423      * fetch size for <code>ResultSet</code> objects

   424      * generated from this <code>Statement</code> object.

   425      * If this <code>Statement</code> object has not set

   426      * a fetch size by calling the method <code>setFetchSize</code>,

   427      * the return value is implementation-specific.

   428      *

   429      * @return the default fetch size for result sets generated

   430      *          from this <code>Statement</code> object

   431      * @exception SQLException if a database access error occurs or

   432      * this method is called on a closed <code>Statement</code>

   433      * @since 1.2

   434      * @see #setFetchSize

   435      */

   436     int getFetchSize() throws SQLException;

   437 

   438     /**

   439      * Retrieves the result set concurrency for <code>ResultSet</code> objects

   440      * generated by this <code>Statement</code> object.

   441      *

   442      * @return either <code>ResultSet.CONCUR_READ_ONLY</code> or

   443      * <code>ResultSet.CONCUR_UPDATABLE</code>

   444      * @exception SQLException if a database access error occurs or

   445      * this method is called on a closed <code>Statement</code>

   446      * @since 1.2

   447      */

   448     int getResultSetConcurrency() throws SQLException;

   449 

   450     /**

   451      * Retrieves the result set type for <code>ResultSet</code> objects

   452      * generated by this <code>Statement</code> object.

   453      *

   454      * @return one of <code>ResultSet.TYPE_FORWARD_ONLY</code>,

   455      * <code>ResultSet.TYPE_SCROLL_INSENSITIVE</code>, or

   456      * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>

   457      * @exception SQLException if a database access error occurs or

   458      * this method is called on a closed <code>Statement</code>

   459      * @since 1.2

   460      */

   461     int getResultSetType()  throws SQLException;

   462 

   463     /**

   464      * Adds the given SQL command to the current list of commmands for this

   465      * <code>Statement</code> object. The commands in this list can be

   466      * executed as a batch by calling the method <code>executeBatch</code>.

   467      * <P>

   468      *

   469      * @param sql typically this is a SQL <code>INSERT</code> or

   470      * <code>UPDATE</code> statement

   471      * @exception SQLException if a database access error occurs,

   472      * this method is called on a closed <code>Statement</code> or the

   473      * driver does not support batch updates

   474      * @see #executeBatch

   475      * @see DatabaseMetaData#supportsBatchUpdates

   476      * @since 1.2

   477      */

   478     void addBatch( String sql ) throws SQLException;

   479 

   480     /**

   481      * Empties this <code>Statement</code> object's current list of

   482      * SQL commands.

   483      * <P>

   484      * @exception SQLException if a database access error occurs,

   485      *  this method is called on a closed <code>Statement</code> or the

   486      * driver does not support batch updates

   487      * @see #addBatch

   488      * @see DatabaseMetaData#supportsBatchUpdates

   489      * @since 1.2

   490      */

   491     void clearBatch() throws SQLException;

   492 

   493     /**

   494      * Submits a batch of commands to the database for execution and

   495      * if all commands execute successfully, returns an array of update counts.

   496      * The <code>int</code> elements of the array that is returned are ordered

   497      * to correspond to the commands in the batch, which are ordered

   498      * according to the order in which they were added to the batch.

   499      * The elements in the array returned by the method <code>executeBatch</code>

   500      * may be one of the following:

   501      * <OL>

   502      * <LI>A number greater than or equal to zero -- indicates that the

   503      * command was processed successfully and is an update count giving the

   504      * number of rows in the database that were affected by the command's

   505      * execution

   506      * <LI>A value of <code>SUCCESS_NO_INFO</code> -- indicates that the command was

   507      * processed successfully but that the number of rows affected is

   508      * unknown

   509      * <P>

   510      * If one of the commands in a batch update fails to execute properly,

   511      * this method throws a <code>BatchUpdateException</code>, and a JDBC

   512      * driver may or may not continue to process the remaining commands in

   513      * the batch.  However, the driver's behavior must be consistent with a

   514      * particular DBMS, either always continuing to process commands or never

   515      * continuing to process commands.  If the driver continues processing

   516      * after a failure, the array returned by the method

   517      * <code>BatchUpdateException.getUpdateCounts</code>

   518      * will contain as many elements as there are commands in the batch, and

   519      * at least one of the elements will be the following:

   520      * <P>

   521      * <LI>A value of <code>EXECUTE_FAILED</code> -- indicates that the command failed

   522      * to execute successfully and occurs only if a driver continues to

   523      * process commands after a command fails

   524      * </OL>

   525      * <P>

   526      * The possible implementations and return values have been modified in

   527      * the Java 2 SDK, Standard Edition, version 1.3 to

   528      * accommodate the option of continuing to proccess commands in a batch

   529      * update after a <code>BatchUpdateException</code> obejct has been thrown.

   530      *

   531      * @return an array of update counts containing one element for each

   532      * command in the batch.  The elements of the array are ordered according

   533      * to the order in which commands were added to the batch.

   534      * @exception SQLException if a database access error occurs,

   535      * this method is called on a closed <code>Statement</code> or the

   536      * driver does not support batch statements. Throws {@link BatchUpdateException}

   537      * (a subclass of <code>SQLException</code>) if one of the commands sent to the

   538      * database fails to execute properly or attempts to return a result set.

   539      *

   540      *

   541      * @see #addBatch

   542      * @see DatabaseMetaData#supportsBatchUpdates

   543      * @since 1.3

   544      */

   545     int[] executeBatch() throws SQLException;

   546 

   547     /**

   548      * Retrieves the <code>Connection</code> object

   549      * that produced this <code>Statement</code> object.

   550      * @return the connection that produced this statement

   551      * @exception SQLException if a database access error occurs or

   552      * this method is called on a closed <code>Statement</code>

   553      * @since 1.2

   554      */

   555     Connection getConnection()  throws SQLException;

   556 

   557   //--------------------------JDBC 3.0-----------------------------

   558 

   559     /**

   560      * The constant indicating that the current <code>ResultSet</code> object

   561      * should be closed when calling <code>getMoreResults</code>.

   562      *

   563      * @since 1.4

   564      */

   565     int CLOSE_CURRENT_RESULT = 1;

   566 

   567     /**

   568      * The constant indicating that the current <code>ResultSet</code> object

   569      * should not be closed when calling <code>getMoreResults</code>.

   570      *

   571      * @since 1.4

   572      */

   573     int KEEP_CURRENT_RESULT = 2;

   574 

   575     /**

   576      * The constant indicating that all <code>ResultSet</code> objects that

   577      * have previously been kept open should be closed when calling

   578      * <code>getMoreResults</code>.

   579      *

   580      * @since 1.4

   581      */

   582     int CLOSE_ALL_RESULTS = 3;

   583 

   584     /**

   585      * The constant indicating that a batch statement executed successfully

   586      * but that no count of the number of rows it affected is available.

   587      *

   588      * @since 1.4

   589      */

   590     int SUCCESS_NO_INFO = -2;

   591 

   592     /**

   593      * The constant indicating that an error occured while executing a

   594      * batch statement.

   595      *

   596      * @since 1.4

   597      */

   598     int EXECUTE_FAILED = -3;

   599 

   600     /**

   601      * The constant indicating that generated keys should be made

   602      * available for retrieval.

   603      *

   604      * @since 1.4

   605      */

   606     int RETURN_GENERATED_KEYS = 1;

   607 

   608     /**

   609      * The constant indicating that generated keys should not be made

   610      * available for retrieval.

   611      *

   612      * @since 1.4

   613      */

   614     int NO_GENERATED_KEYS = 2;

   615 

   616     /**

   617      * Moves to this <code>Statement</code> object's next result, deals with

   618      * any current <code>ResultSet</code> object(s) according  to the instructions

   619      * specified by the given flag, and returns

   620      * <code>true</code> if the next result is a <code>ResultSet</code> object.

   621      *

   622      * <P>There are no more results when the following is true:

   623      * <PRE>

   624      *     // stmt is a Statement object

   625      *     ((stmt.getMoreResults(current) == false) && (stmt.getUpdateCount() == -1))

   626      * </PRE>

   627      *

   628      * @param current one of the following <code>Statement</code>

   629      *        constants indicating what should happen to current

   630      *        <code>ResultSet</code> objects obtained using the method

   631      *        <code>getResultSet</code>:

   632      *        <code>Statement.CLOSE_CURRENT_RESULT</code>,

   633      *        <code>Statement.KEEP_CURRENT_RESULT</code>, or

   634      *        <code>Statement.CLOSE_ALL_RESULTS</code>

   635      * @return <code>true</code> if the next result is a <code>ResultSet</code>

   636      *         object; <code>false</code> if it is an update count or there are no

   637      *         more results

   638      * @exception SQLException if a database access error occurs,

   639      * this method is called on a closed <code>Statement</code> or the argument

   640          *         supplied is not one of the following:

   641      *        <code>Statement.CLOSE_CURRENT_RESULT</code>,

   642      *        <code>Statement.KEEP_CURRENT_RESULT</code> or

   643      *        <code>Statement.CLOSE_ALL_RESULTS</code>

   644      *@exception SQLFeatureNotSupportedException if

   645      * <code>DatabaseMetaData.supportsMultipleOpenResults</code> returns

   646      * <code>false</code> and either

   647      *        <code>Statement.KEEP_CURRENT_RESULT</code> or

   648      *        <code>Statement.CLOSE_ALL_RESULTS</code> are supplied as

   649      * the argument.

   650      * @since 1.4

   651      * @see #execute

   652      */

   653     boolean getMoreResults(int current) throws SQLException;

   654 

   655     /**

   656      * Retrieves any auto-generated keys created as a result of executing this

   657      * <code>Statement</code> object. If this <code>Statement</code> object did

   658      * not generate any keys, an empty <code>ResultSet</code>

   659      * object is returned.

   660      *

   661      *<p><B>Note:</B>If the columns which represent the auto-generated keys were not specified,

   662      * the JDBC driver implementation will determine the columns which best represent the auto-generated keys.

   663      *

   664      * @return a <code>ResultSet</code> object containing the auto-generated key(s)

   665      *         generated by the execution of this <code>Statement</code> object

   666      * @exception SQLException if a database access error occurs or

   667      * this method is called on a closed <code>Statement</code>

   668      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   669      * @since 1.4

   670      */

   671     ResultSet getGeneratedKeys() throws SQLException;

   672 

   673     /**

   674      * Executes the given SQL statement and signals the driver with the

   675      * given flag about whether the

   676      * auto-generated keys produced by this <code>Statement</code> object

   677      * should be made available for retrieval.  The driver will ignore the

   678      * flag if the SQL statement

   679      * is not an <code>INSERT</code> statement, or an SQL statement able to return

   680      * auto-generated keys (the list of such statements is vendor-specific).

   681      *

   682      * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or

   683      * <code>DELETE</code>; or an SQL statement that returns nothing,

   684      * such as a DDL statement.

   685      *

   686      * @param autoGeneratedKeys a flag indicating whether auto-generated keys

   687      *        should be made available for retrieval;

   688      *         one of the following constants:

   689      *         <code>Statement.RETURN_GENERATED_KEYS</code>

   690      *         <code>Statement.NO_GENERATED_KEYS</code>

   691      * @return either (1) the row count for SQL Data Manipulation Language (DML) statements

   692      *         or (2) 0 for SQL statements that return nothing

   693      *

   694      * @exception SQLException if a database access error occurs,

   695      *  this method is called on a closed <code>Statement</code>, the given

   696      *            SQL statement returns a <code>ResultSet</code> object, or

   697      *            the given constant is not one of those allowed

   698      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   699      * this method with a constant of Statement.RETURN_GENERATED_KEYS

   700      * @since 1.4

   701      */

   702     int executeUpdate(String sql, int autoGeneratedKeys) throws SQLException;

   703 

   704     /**

   705      * Executes the given SQL statement and signals the driver that the

   706      * auto-generated keys indicated in the given array should be made available

   707      * for retrieval.   This array contains the indexes of the columns in the

   708      * target table that contain the auto-generated keys that should be made

   709      * available. The driver will ignore the array if the SQL statement

   710      * is not an <code>INSERT</code> statement, or an SQL statement able to return

   711      * auto-generated keys (the list of such statements is vendor-specific).

   712      *

   713      * @param sql an SQL Data Manipulation Language (DML) statement, such as <code>INSERT</code>, <code>UPDATE</code> or

   714      * <code>DELETE</code>; or an SQL statement that returns nothing,

   715      * such as a DDL statement.

   716      *

   717      * @param columnIndexes an array of column indexes indicating the columns

   718      *        that should be returned from the inserted row

   719      * @return either (1) the row count for SQL Data Manipulation Language (DML) statements

   720      *         or (2) 0 for SQL statements that return nothing

   721      *

   722      * @exception SQLException if a database access error occurs,

   723      * this method is called on a closed <code>Statement</code>, the SQL

   724      *            statement returns a <code>ResultSet</code> object, or the

   725      *            second argument supplied to this method is not an <code>int</code> array

   726      *            whose elements are valid column indexes

   727      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   728      * @since 1.4

   729      */

   730     int executeUpdate(String sql, int columnIndexes[]) 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[]) throws SQLException;

   759 

   760     /**

   761      * Executes the given SQL statement, which may return multiple results,

   762      * and signals the driver that any

   763      * auto-generated keys should be made available

   764      * for retrieval.  The driver will ignore this signal if the SQL statement

   765      * is not an <code>INSERT</code> statement, or an SQL statement able to return

   766      * auto-generated keys (the list of such statements is vendor-specific).

   767      * <P>

   768      * In some (uncommon) situations, a single SQL statement may return

   769      * multiple result sets and/or update counts.  Normally you can ignore

   770      * this unless you are (1) executing a stored procedure that you know may

   771      * return multiple results or (2) you are dynamically executing an

   772      * unknown SQL string.

   773      * <P>

   774      * The <code>execute</code> method executes an SQL statement and indicates the

   775      * form of the first result.  You must then use the methods

   776      * <code>getResultSet</code> or <code>getUpdateCount</code>

   777      * to retrieve the result, and <code>getMoreResults</code> to

   778      * move to any subsequent result(s).

   779      *

   780      * @param sql any SQL statement

   781      * @param autoGeneratedKeys a constant indicating whether auto-generated

   782      *        keys should be made available for retrieval using the method

   783      *        <code>getGeneratedKeys</code>; one of the following constants:

   784      *        <code>Statement.RETURN_GENERATED_KEYS</code> or

   785      *        <code>Statement.NO_GENERATED_KEYS</code>

   786      * @return <code>true</code> if the first result is a <code>ResultSet</code>

   787      *         object; <code>false</code> if it is an update count or there are

   788      *         no results

   789      * @exception SQLException if a database access error occurs,

   790      * this method is called on a closed <code>Statement</code> or the second

   791      *         parameter supplied to this method is not

   792      *         <code>Statement.RETURN_GENERATED_KEYS</code> or

   793      *         <code>Statement.NO_GENERATED_KEYS</code>.

   794      * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

   795      * this method with a constant of Statement.RETURN_GENERATED_KEYS

   796      * @see #getResultSet

   797      * @see #getUpdateCount

   798      * @see #getMoreResults

   799      * @see #getGeneratedKeys

   800      *

   801      * @since 1.4

   802      */

   803     boolean execute(String sql, int autoGeneratedKeys) throws SQLException;

   804 

   805     /**

   806      * Executes the given SQL statement, which may return multiple results,

   807      * and signals the driver that the

   808      * auto-generated keys indicated in the given array should be made available

   809      * for retrieval.  This array contains the indexes of the columns in the

   810      * target table that contain the auto-generated keys that should be made

   811      * available.  The driver will ignore the array if the SQL statement

   812      * is not an <code>INSERT</code> statement, or an SQL statement able to return

   813      * auto-generated keys (the list of such statements is vendor-specific).

   814      * <P>

   815      * Under some (uncommon) situations, a single SQL statement may return

   816      * multiple result sets and/or update counts.  Normally you can ignore

   817      * this unless you are (1) executing a stored procedure that you know may

   818      * return multiple results or (2) you are dynamically executing an

   819      * unknown SQL string.

   820      * <P>

   821      * The <code>execute</code> method executes an SQL statement and indicates the

   822      * form of the first result.  You must then use the methods

   823      * <code>getResultSet</code> or <code>getUpdateCount</code>

   824      * to retrieve the result, and <code>getMoreResults</code> to

   825      * move to any subsequent result(s).

   826      *

   827      * @param sql any SQL statement

   828      * @param columnIndexes an array of the indexes of the columns in the

   829      *        inserted row that should be  made available for retrieval by a

   830      *        call to the method <code>getGeneratedKeys</code>

   831      * @return <code>true</code> if the first result is a <code>ResultSet</code>

   832      *         object; <code>false</code> if it is an update count or there

   833      *         are no results

   834      * @exception SQLException if a database access error occurs,

   835      * this method is called on a closed <code>Statement</code> or the

   836      *            elements in the <code>int</code> array passed to this method

   837      *            are not valid column indexes

   838      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   839      * @see #getResultSet

   840      * @see #getUpdateCount

   841      * @see #getMoreResults

   842      *

   843      * @since 1.4

   844      */

   845     boolean execute(String sql, int columnIndexes[]) throws SQLException;

   846 

   847     /**

   848      * Executes the given SQL statement, which may return multiple results,

   849      * and signals the driver that the

   850      * auto-generated keys indicated in the given array should be made available

   851      * for retrieval. This array contains the names of the columns in the

   852      * target table that contain the auto-generated keys that should be made

   853      * available.  The driver will ignore the array if the SQL statement

   854      * is not an <code>INSERT</code> statement, or an SQL statement able to return

   855      * auto-generated keys (the list of such statements is vendor-specific).

   856      * <P>

   857      * In some (uncommon) situations, a single SQL statement may return

   858      * multiple result sets and/or update counts.  Normally you can ignore

   859      * this unless you are (1) executing a stored procedure that you know may

   860      * return multiple results or (2) you are dynamically executing an

   861      * unknown SQL string.

   862      * <P>

   863      * The <code>execute</code> method executes an SQL statement and indicates the

   864      * form of the first result.  You must then use the methods

   865      * <code>getResultSet</code> or <code>getUpdateCount</code>

   866      * to retrieve the result, and <code>getMoreResults</code> to

   867      * move to any subsequent result(s).

   868      *

   869      * @param sql any SQL statement

   870      * @param columnNames an array of the names of the columns in the inserted

   871      *        row that should be made available for retrieval by a call to the

   872      *        method <code>getGeneratedKeys</code>

   873      * @return <code>true</code> if the next result is a <code>ResultSet</code>

   874      *         object; <code>false</code> if it is an update count or there

   875      *         are no more results

   876      * @exception SQLException if a database access error occurs,

   877      * this method is called on a closed <code>Statement</code> or the

   878      *          elements of the <code>String</code> array passed to this

   879      *          method are not valid column names

   880      * @throws SQLFeatureNotSupportedException  if the JDBC driver does not support this method

   881      * @see #getResultSet

   882      * @see #getUpdateCount

   883      * @see #getMoreResults

   884      * @see #getGeneratedKeys

   885      *

   886      * @since 1.4

   887      */

   888     boolean execute(String sql, String columnNames[]) throws SQLException;

   889 

   890    /**

   891      * Retrieves the result set holdability for <code>ResultSet</code> objects

   892      * generated by this <code>Statement</code> object.

   893      *

   894      * @return either <code>ResultSet.HOLD_CURSORS_OVER_COMMIT</code> or

   895      *         <code>ResultSet.CLOSE_CURSORS_AT_COMMIT</code>

   896      * @exception SQLException if a database access error occurs or

   897      * this method is called on a closed <code>Statement</code>

   898      *

   899      * @since 1.4

   900      */

   901     int getResultSetHoldability() throws SQLException;

   902 

   903     /**

   904      * Retrieves whether this <code>Statement</code> object has been closed. A <code>Statement</code> is closed if the

   905      * method close has been called on it, or if it is automatically closed.

   906      * @return true if this <code>Statement</code> object is closed; false if it is still open

   907      * @throws SQLException if a database access error occurs

   908      * @since 1.6

   909      */

   910     boolean isClosed() throws SQLException;

   911 

   912         /**

   913          * Requests that a <code>Statement</code> be pooled or not pooled.  The value

   914          * specified is a hint to the statement pool implementation indicating

   915          * whether the applicaiton wants the statement to be pooled.  It is up to

   916          * the statement pool manager as to whether the hint is used.

   917          * <p>

   918          * The poolable value of a statement is applicable to both internal

   919          * statement caches implemented by the driver and external statement caches

   920          * implemented by application servers and other applications.

   921          * <p>

   922          * By default, a <code>Statement</code> is not poolable when created, and

   923          * a <code>PreparedStatement</code> and <code>CallableStatement</code>

   924          * are poolable when created.

   925          * <p>

   926          * @param poolable              requests that the statement be pooled if true and

   927          *                                              that the statement not be pooled if false

   928          * <p>

   929          * @throws SQLException if this method is called on a closed

   930          * <code>Statement</code>

   931          * <p>

   932          * @since 1.6

   933          */

   934         void setPoolable(boolean poolable)

   935                 throws SQLException;

   936 

   937         /**

   938          * Returns a  value indicating whether the <code>Statement</code>

   939          * is poolable or not.

   940          * <p>

   941          * @return              <code>true</code> if the <code>Statement</code>

   942          * is poolable; <code>false</code> otherwise

   943          * <p>

   944          * @throws SQLException if this method is called on a closed

   945          * <code>Statement</code>

   946          * <p>

   947          * @since 1.6

   948          * <p>

   949          * @see java.sql.Statement#setPoolable(boolean) setPoolable(boolean)

   950          */

   951         boolean isPoolable()

   952                 throws SQLException;

   953 

   954 }