/*

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

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

 *

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

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

 * published by the Free Software Foundation.  Sun designates this

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

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

 *

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

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

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

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

 * accompanied this code).

 *

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

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

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

 *

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

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

 * have any questions.

 */

package java.sql;

/**

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

 * and returning the results it produces.

 * <P>

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

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

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

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

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

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

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

 *

 * @see Connection#createStatement

 * @see ResultSet

 */

public interface Statement extends Wrapper {

    /**

     * Executes the given SQL statement, which returns a single

     * <code>ResultSet</code> object.

     *

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

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

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

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

     * @exception SQLException if a database access error occurs,

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

     *            SQL statement produces anything other than a single

     *            <code>ResultSet</code> object

     */

    ResultSet executeQuery(String sql) throws SQLException;

    /**

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

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

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

     *

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

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

     * such as a DDL statement.

     *

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

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

     *

     * @exception SQLException if a database access error occurs,

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

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

     */

    int executeUpdate(String sql) throws SQLException;

    /**

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

     * and JDBC resources immediately instead of waiting for

     * this to happen when it is automatically closed.

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

     * you are finished with them to avoid tying up database

     * resources.

     * <P>

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

     * object that is already closed has no effect.

     * <P>

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

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

     * also closed.

     *

     * @exception SQLException if a database access error occurs

     */

    void close() throws SQLException;

    //----------------------------------------------------------------------

    /**

     * Retrieves the maximum number of bytes that can be

     * returned for character and binary column values in a <code>ResultSet</code>

     * object produced by this <code>Statement</code> object.

     * This limit applies only to  <code>BINARY</code>, <code>VARBINARY</code>,

     * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,

     * <code>NCHAR</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code>

     * and <code>LONGVARCHAR</code> columns.  If the limit is exceeded, the

     * excess data is silently discarded.

     *

     * @return the current column size limit for columns storing character and

     *         binary values; zero means there is no limit

     * @exception SQLException if a database access error occurs or

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

     * @see #setMaxFieldSize

     */

    int getMaxFieldSize() throws SQLException;

    /**

     * Sets the limit for the maximum number of bytes that can be returned for

     * character and binary column values in a <code>ResultSet</code>

     * object produced by this <code>Statement</code> object.

     *

     * This limit applies

     * only to <code>BINARY</code>, <code>VARBINARY</code>,

     * <code>LONGVARBINARY</code>, <code>CHAR</code>, <code>VARCHAR</code>,

     * <code>NCHAR</code>, <code>NVARCHAR</code>, <code>LONGNVARCHAR</code> and

     * <code>LONGVARCHAR</code> fields.  If the limit is exceeded, the excess data

     * is silently discarded. For maximum portability, use values

     * greater than 256.

     *

     * @param max the new column size limit in bytes; zero means there is no limit

     * @exception SQLException if a database access error occurs,

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

     *            or the condition max >= 0 is not satisfied

     * @see #getMaxFieldSize

     */

    void setMaxFieldSize(int max) throws SQLException;

    /**

     * Retrieves the maximum number of rows that a

     * <code>ResultSet</code> object produced by this

     * <code>Statement</code> object can contain.  If this limit is exceeded,

     * the excess rows are silently dropped.

     *

     * @return the current maximum number of rows for a <code>ResultSet</code>

     *         object produced by this <code>Statement</code> object;

     *         zero means there is no limit

     * @exception SQLException if a database access error occurs or

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

     * @see #setMaxRows

     */

    int getMaxRows() throws SQLException;

    /**

     * Sets the limit for the maximum number of rows that any

     * <code>ResultSet</code> object  generated by this <code>Statement</code>

     * object can contain to the given number.

     * If the limit is exceeded, the excess

     * rows are silently dropped.

     *

     * @param max the new max rows limit; zero means there is no limit

     * @exception SQLException if a database access error occurs,

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

     *            or the condition max >= 0 is not satisfied

     * @see #getMaxRows

     */

    void setMaxRows(int max) throws SQLException;

    /**

     * Sets escape processing on or off.

     * If escape scanning is on (the default), the driver will do

     * escape substitution before sending the SQL statement to the database.

     *

     * Note: Since prepared statements have usually been parsed prior

     * to making this call, disabling escape processing for

     * <code>PreparedStatements</code> objects will have no effect.

     *

     * @param enable <code>true</code> to enable escape processing;

     *       <code>false</code> to disable it

     * @exception SQLException if a database access error occurs or

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

     */

    void setEscapeProcessing(boolean enable) throws SQLException;

    /**

     * Retrieves the number of seconds the driver will

     * wait for a <code>Statement</code> object to execute.

     * If the limit is exceeded, a

     * <code>SQLException</code> is thrown.

     *

     * @return the current query timeout limit in seconds; zero means there is

     *         no limit

     * @exception SQLException if a database access error occurs or

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

     * @see #setQueryTimeout

     */

    int getQueryTimeout() throws SQLException;

    /**

     * Sets the number of seconds the driver will wait for a

     * <code>Statement</code> object to execute to the given number of seconds.

     * If the limit is exceeded, an <code>SQLException</code> is thrown. A JDBC

     * driver must apply this limit to the <code>execute</code>,

     * <code>executeQuery</code> and <code>executeUpdate</code> methods. JDBC driver

     * implementations may also apply this limit to <code>ResultSet</code> methods

     * (consult your driver vendor documentation for details).

     *

     * @param seconds the new query timeout limit in seconds; zero means

     *        there is no limit

     * @exception SQLException if a database access error occurs,

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

     *            or the condition seconds >= 0 is not satisfied

     * @see #getQueryTimeout

     */

    void setQueryTimeout(int seconds) throws SQLException;

    /**

     * Cancels this <code>Statement</code> object if both the DBMS and

     * driver support aborting an SQL statement.

     * This method can be used by one thread to cancel a statement that

     * is being executed by another thread.

     *

     * @exception SQLException if a database access error occurs or

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

     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

     * this method

     */

    void cancel() throws SQLException;

    /**

     * Retrieves the first warning reported by calls on this <code>Statement</code> object.

     * Subsequent <code>Statement</code> object warnings will be chained to this

     * <code>SQLWarning</code> object.

     *

     * <p>The warning chain is automatically cleared each time

     * a statement is (re)executed. This method may not be called on a closed

     * <code>Statement</code> object; doing so will cause an <code>SQLException</code>

     * to be thrown.

     *

     * <P><B>Note:</B> If you are processing a <code>ResultSet</code> object, any

     * warnings associated with reads on that <code>ResultSet</code> object

     * will be chained on it rather than on the <code>Statement</code>

     * object that produced it.

     *

     * @return the first <code>SQLWarning</code> object or <code>null</code>

     *         if there are no warnings

     * @exception SQLException if a database access error occurs or

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

     */

    SQLWarning getWarnings() throws SQLException;

    /**

     * Clears all the warnings reported on this <code>Statement</code>

     * object. After a call to this method,

     * the method <code>getWarnings</code> will return

     * <code>null</code> until a new warning is reported for this

     * <code>Statement</code> object.

     *

     * @exception SQLException if a database access error occurs or

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

     */

    void clearWarnings() throws SQLException;

    /**

     * Sets the SQL cursor name to the given <code>String</code>, which

     * will be used by subsequent <code>Statement</code> object

     * <code>execute</code> methods. This name can then be

     * used in SQL positioned update or delete statements to identify the

     * current row in the <code>ResultSet</code> object generated by this

     * statement.  If the database does not support positioned update/delete,

     * this method is a noop.  To insure that a cursor has the proper isolation

     * level to support updates, the cursor's <code>SELECT</code> statement

     * should have the form <code>SELECT FOR UPDATE</code>.  If

     * <code>FOR UPDATE</code> is not present, positioned updates may fail.

     *

     * <P><B>Note:</B> By definition, the execution of positioned updates and

     * deletes must be done by a different <code>Statement</code> object than

     * the one that generated the <code>ResultSet</code> object being used for

     * positioning. Also, cursor names must be unique within a connection.

     *

     * @param name the new cursor name, which must be unique within

     *             a connection

     * @exception SQLException if a database access error occurs or

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

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

     */

    void setCursorName(String name) throws SQLException;

    //----------------------- Multiple Results --------------------------

    /**

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

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

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

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

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

     * unknown SQL string.

     * <P>

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

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

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

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

     * move to any subsequent result(s).

     *

     * @param sql any SQL statement

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

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

     *         no results

     * @exception SQLException if a database access error occurs or

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

     * @see #getResultSet

     * @see #getUpdateCount

     * @see #getMoreResults

     */

    boolean execute(String sql) throws SQLException;

    /**

     *  Retrieves the current result as a <code>ResultSet</code> object.

     *  This method should be called only once per result.

     *

     * @return the current result as a <code>ResultSet</code> object or

     * <code>null</code> if the result is an update count or there are no more results

     * @exception SQLException if a database access error occurs or

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

     * @see #execute

     */

    ResultSet getResultSet() throws SQLException;

    /**

     *  Retrieves the current result as an update count;

     *  if the result is a <code>ResultSet</code> object or there are no more results, -1

     *  is returned. This method should be called only once per result.

     *

     * @return the current result as an update count; -1 if the current result is a

     * <code>ResultSet</code> object or there are no more results

     * @exception SQLException if a database access error occurs or

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

     * @see #execute

     */

    int getUpdateCount() throws SQLException;

    /**

     * Moves to this <code>Statement</code> object's next result, returns

     * <code>true</code> if it is a <code>ResultSet</code> object, and

     * implicitly closes any current <code>ResultSet</code>

     * object(s) obtained with the method <code>getResultSet</code>.

     *

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

     * <PRE>

     *     // stmt is a Statement object

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

     * </PRE>

     *

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

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

     *         no more results

     * @exception SQLException if a database access error occurs or

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

     * @see #execute

     */

    boolean getMoreResults() throws SQLException;

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

    /**

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

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

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

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

     * <P>

     * Note that this method sets the default fetch direction for

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

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

     * its own fetch direction.

     *

     * @param direction the initial direction for processing rows

     * @exception SQLException if a database access error occurs,

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

     * or the given direction

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

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

     * @since 1.2

     * @see #getFetchDirection

     */

    void setFetchDirection(int direction) throws SQLException;

    /**

     * Retrieves the direction for fetching rows from

     * database tables that is the default for result sets

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

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

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

     * the return value is implementation-specific.

     *

     * @return the default fetch direction for result sets generated

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

     * @exception SQLException if a database access error occurs or

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

     * @since 1.2

     * @see #setFetchDirection

     */

    int getFetchDirection() throws SQLException;

    /**

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

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

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

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

     * The default value is zero.

     *

     * @param rows the number of rows to fetch

     * @exception SQLException if a database access error occurs,

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

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

     * @since 1.2

     * @see #getFetchSize

     */

    void setFetchSize(int rows) throws SQLException;

    /**

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

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

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

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

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

     * the return value is implementation-specific.

     *

     * @return the default fetch size for result sets generated

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

     * @exception SQLException if a database access error occurs or

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

     * @since 1.2

     * @see #setFetchSize

     */

    int getFetchSize() throws SQLException;

    /**

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

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

     *

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

     * <code>ResultSet.CONCUR_UPDATABLE</code>

     * @exception SQLException if a database access error occurs or

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

     * @since 1.2

     */

    int getResultSetConcurrency() throws SQLException;

    /**

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

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

     *

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

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

     * <code>ResultSet.TYPE_SCROLL_SENSITIVE</code>

     * @exception SQLException if a database access error occurs or

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

     * @since 1.2

     */

    int getResultSetType()  throws SQLException;

    /**

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

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

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

     * <P>

     *

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

     * <code>UPDATE</code> statement

     * @exception SQLException if a database access error occurs,

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

     * driver does not support batch updates

     * @see #executeBatch

     * @see DatabaseMetaData#supportsBatchUpdates

     * @since 1.2

     */

    void addBatch( String sql ) throws SQLException;

    /**

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

     * SQL commands.

     * <P>

     * @exception SQLException if a database access error occurs,

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

     * driver does not support batch updates

     * @see #addBatch

     * @see DatabaseMetaData#supportsBatchUpdates

     * @since 1.2

     */

    void clearBatch() throws SQLException;

    /**

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

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

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

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

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

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

     * may be one of the following:

     * <OL>

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

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

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

     * execution

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

     * processed successfully but that the number of rows affected is

     * unknown

     * <P>

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

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

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

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

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

     * continuing to process commands.  If the driver continues processing

     * after a failure, the array returned by the method

     * <code>BatchUpdateException.getUpdateCounts</code>

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

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

     * <P>

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

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

     * process commands after a command fails

     * </OL>

     * <P>

     * The possible implementations and return values have been modified in

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

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