/*

 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. 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.  Oracle designates this

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

 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.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, AutoCloseable {

    /**

     * Executes the given SQL statement, which returns a single

     * <code>ResultSet</code> object.

     *<p>

     * <strong>Note:</strong>This method cannot be called on a

     * <code>PreparedStatement</code> or <code>CallableStatement</code>.

     * @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>, the given

     *            SQL statement produces anything other than a single

     *            <code>ResultSet</code> object, the method is called on a

     * <code>PreparedStatement</code> or <code>CallableStatement</code>

     * @throws SQLTimeoutException when the driver has determined that the

     * timeout value that was specified by the {@code setQueryTimeout}

     * method has been exceeded and has at least attempted to cancel

     * the currently running {@code Statement}

     */

    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.

     *<p>

     * <strong>Note:</strong>This method cannot be called on a

     * <code>PreparedStatement</code> or <code>CallableStatement</code>.

     * @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>, the given

     * SQL statement produces a <code>ResultSet</code> object, the method is called on a

     * <code>PreparedStatement</code> or <code>CallableStatement</code>

     * @throws SQLTimeoutException when the driver has determined that the

     * timeout value that was specified by the {@code setQueryTimeout}

     * method has been exceeded and has at least attempted to cancel

     * the currently running {@code Statement}

     */

    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>

     * @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>

     * @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.

     *<p>

     * The {@code Connection} and {@code DataSource} property

     * {@code escapeProcessing} may be used to change the default escape processing

     * behavior.  A value of true (the default) enables escape Processing for

     * all {@code Statement} objects. A value of false disables escape processing

     * for all {@code Statement} objects.  The {@code setEscapeProcessing}

     * method may be used to specify the escape processing behavior for an

     * individual {@code Statement} object.

     * <p>

     * 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.

     *By default there is no limit on the amount of time allowed for a running

     * statement to complete. If the limit is exceeded, an

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

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

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

     * <p>

     * <strong>Note:</strong> JDBC driver implementations may also apply this

     * limit to {@code ResultSet} methods

     * (consult your driver vendor documentation for details).

     * <p>

     * <strong>Note:</strong> In the case of {@code Statement} batching, it is

     * implementation defined as to whether the time-out is applied to

     * individual SQL commands added via the {@code addBatch} method or to

     * the entire batch of SQL commands invoked by the {@code executeBatch}

     * method (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>

     * @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).

     * <p>

     *<strong>Note:</strong>This method cannot be called on a

     * <code>PreparedStatement</code> or <code>CallableStatement</code>.

     * @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,

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

     * the method is called on a

     * <code>PreparedStatement</code> or <code>CallableStatement</code>

     * @throws SQLTimeoutException when the driver has determined that the

     * timeout value that was specified by the {@code setQueryTimeout}

     * method has been exceeded and has at least attempted to cancel

     * the currently running {@code Statement}

     * @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:

     *     // stmt is a Statement object

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

     *

     * @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

     * @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>

     *<strong>Note:</strong>This method cannot be called on a

     * <code>PreparedStatement</code> or <code>CallableStatement</code>.

     * @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>, the

     * driver does not support batch updates, the method is called on a

     * <code>PreparedStatement</code> or <code>CallableStatement</code>

     * @see #executeBatch

     * @see DatabaseMetaData#supportsBatchUpdates

     * @since 1.2

     */

    void addBatch( String sql ) throws SQLException;