/*

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

import java.math.BigDecimal;

import java.util.Calendar;

import java.io.Reader;

import java.io.InputStream;

/**

 * An object that represents a precompiled SQL statement.

 * <P>A SQL statement is precompiled and stored in a

 * <code>PreparedStatement</code> object. This object can then be used to

 * efficiently execute this statement multiple times.

 *

 * <P><B>Note:</B> The setter methods (<code>setShort</code>, <code>setString</code>,

 * and so on) for setting IN parameter values

 * must specify types that are compatible with the defined SQL type of

 * the input parameter. For instance, if the IN parameter has SQL type

 * <code>INTEGER</code>, then the method <code>setInt</code> should be used.

 *

 * <p>If arbitrary parameter type conversions are required, the method

 * <code>setObject</code> should be used with a target SQL type.

 * <P>

 * In the following example of setting a parameter, <code>con</code> represents

 * an active connection:

 * <PRE>

 *   PreparedStatement pstmt = con.prepareStatement("UPDATE EMPLOYEES

 *                                     SET SALARY = ? WHERE ID = ?");

 *   pstmt.setBigDecimal(1, 153833.00)

 *   pstmt.setInt(2, 110592)

 * </PRE>

 *

 * @see Connection#prepareStatement

 * @see ResultSet

 */

public interface PreparedStatement extends Statement {

    /**

     * Executes the SQL query in this <code>PreparedStatement</code> object

     * and returns the <code>ResultSet</code> object generated by the query.

     *

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

     *         query; never <code>null</code>

     * @exception SQLException if a database access error occurs;

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

     *            statement does not return a <code>ResultSet</code> object

     */

    ResultSet executeQuery() throws SQLException;

    /**

     * Executes the SQL statement in this <code>PreparedStatement</code> object,

     * which must be 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>PreparedStatement</code>

     * or the SQL

     *            statement returns a <code>ResultSet</code> object

     */

    int executeUpdate() throws SQLException;

    /**

     * Sets the designated parameter to SQL <code>NULL</code>.

     *

     * <P><B>Note:</B> You must specify the parameter's SQL type.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param sqlType the SQL type code defined in <code>java.sql.Types</code>

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     * @exception SQLFeatureNotSupportedException if <code>sqlType</code> is

     * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,

     * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,

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

     *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>

     * or  <code>STRUCT</code> data type and the JDBC driver does not support

     * this data type

     */

    void setNull(int parameterIndex, int sqlType) throws SQLException;

    /**

     * Sets the designated parameter to the given Java <code>boolean</code> value.

     * The driver converts this

     * to an SQL <code>BIT</code> or <code>BOOLEAN</code> value when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement;

     * if a database access error occurs or

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

     */

    void setBoolean(int parameterIndex, boolean x) throws SQLException;

    /**

     * Sets the designated parameter to the given Java <code>byte</code> value.

     * The driver converts this

     * to an SQL <code>TINYINT</code> value when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setByte(int parameterIndex, byte x) throws SQLException;

    /**

     * Sets the designated parameter to the given Java <code>short</code> value.

     * The driver converts this

     * to an SQL <code>SMALLINT</code> value when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setShort(int parameterIndex, short x) throws SQLException;

    /**

     * Sets the designated parameter to the given Java <code>int</code> value.

     * The driver converts this

     * to an SQL <code>INTEGER</code> value when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setInt(int parameterIndex, int x) throws SQLException;

    /**

     * Sets the designated parameter to the given Java <code>long</code> value.

     * The driver converts this

     * to an SQL <code>BIGINT</code> value when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setLong(int parameterIndex, long x) throws SQLException;

    /**

     * Sets the designated parameter to the given Java <code>float</code> value.

     * The driver converts this

     * to an SQL <code>REAL</code> value when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setFloat(int parameterIndex, float x) throws SQLException;

    /**

     * Sets the designated parameter to the given Java <code>double</code> value.

     * The driver converts this

     * to an SQL <code>DOUBLE</code> value when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setDouble(int parameterIndex, double x) throws SQLException;

    /**

     * Sets the designated parameter to the given <code>java.math.BigDecimal</code> value.

     * The driver converts this to an SQL <code>NUMERIC</code> value when

     * it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException;

    /**

     * Sets the designated parameter to the given Java <code>String</code> value.

     * The driver converts this

     * to an SQL <code>VARCHAR</code> or <code>LONGVARCHAR</code> value

     * (depending on the argument's

     * size relative to the driver's limits on <code>VARCHAR</code> values)

     * when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setString(int parameterIndex, String x) throws SQLException;

    /**

     * Sets the designated parameter to the given Java array of bytes.  The driver converts

     * this to an SQL <code>VARBINARY</code> or <code>LONGVARBINARY</code>

     * (depending on the argument's size relative to the driver's limits on

     * <code>VARBINARY</code> values) when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setBytes(int parameterIndex, byte x[]) throws SQLException;

    /**

     * Sets the designated parameter to the given <code>java.sql.Date</code> value

     * using the default time zone of the virtual machine that is running

     * the application.

     * The driver converts this

     * to an SQL <code>DATE</code> value when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setDate(int parameterIndex, java.sql.Date x)

            throws SQLException;

    /**

     * Sets the designated parameter to the given <code>java.sql.Time</code> value.

     * The driver converts this

     * to an SQL <code>TIME</code> value when it sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setTime(int parameterIndex, java.sql.Time x)

            throws SQLException;

    /**

     * Sets the designated parameter to the given <code>java.sql.Timestamp</code> value.

     * The driver

     * converts this to an SQL <code>TIMESTAMP</code> value when it sends it to the

     * database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

    void setTimestamp(int parameterIndex, java.sql.Timestamp x)

            throws SQLException;

    /**

     * Sets the designated parameter to the given input stream, which will have

     * the specified number of bytes.

     * When a very large ASCII value is input to a <code>LONGVARCHAR</code>

     * parameter, it may be more practical to send it via a

     * <code>java.io.InputStream</code>. Data will be read from the stream

     * as needed until end-of-file is reached.  The JDBC driver will

     * do any necessary conversion from ASCII to the database char format.

     *

     * <P><B>Note:</B> This stream object can either be a standard

     * Java stream object or your own subclass that implements the

     * standard interface.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the Java input stream that contains the ASCII parameter value

     * @param length the number of bytes in the stream

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setAsciiStream(int parameterIndex, java.io.InputStream x, int length)

            throws SQLException;

    /**

     * Sets the designated parameter to the given input stream, which

     * will have the specified number of bytes.

     *

     * When a very large Unicode value is input to a <code>LONGVARCHAR</code>

     * parameter, it may be more practical to send it via a

     * <code>java.io.InputStream</code> object. The data will be read from the

     * stream as needed until end-of-file is reached.  The JDBC driver will

     * do any necessary conversion from Unicode to the database char format.

     *

     *The byte format of the Unicode stream must be a Java UTF-8, as defined in the

     *Java Virtual Machine Specification.

     *

     * <P><B>Note:</B> This stream object can either be a standard

     * Java stream object or your own subclass that implements the

     * standard interface.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x a <code>java.io.InputStream</code> object that contains the

     *        Unicode parameter value

     * @param length the number of bytes in the stream

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support

     * this method

     * @deprecated

     */

    void setUnicodeStream(int parameterIndex, java.io.InputStream x,

                          int length) throws SQLException;

    /**

     * Sets the designated parameter to the given input stream, which will have

     * the specified number of bytes.

     * When a very large binary value is input to a <code>LONGVARBINARY</code>

     * parameter, it may be more practical to send it via a

     * <code>java.io.InputStream</code> object. The data will be read from the

     * stream as needed until end-of-file is reached.

     *

     * <P><B>Note:</B> This stream object can either be a standard

     * Java stream object or your own subclass that implements the

     * standard interface.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the java input stream which contains the binary parameter value

     * @param length the number of bytes in the stream

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     */

    void setBinaryStream(int parameterIndex, java.io.InputStream x,

                         int length) throws SQLException;

    /**

     * Clears the current parameter values immediately.

     * <P>In general, parameter values remain in force for repeated use of a

     * statement. Setting a parameter value automatically clears its

     * previous value.  However, in some cases it is useful to immediately

     * release the resources used by the current parameter values; this can

     * be done by calling the method <code>clearParameters</code>.

     *

     * @exception SQLException if a database access error occurs or

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

     */

    void clearParameters() throws SQLException;

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

    // Advanced features:

   /**

    * Sets the value of the designated parameter with the given object.

    * This method is like the method <code>setObject</code>

    * above, except that it assumes a scale of zero.

    *

    * @param parameterIndex the first parameter is 1, the second is 2, ...

    * @param x the object containing the input parameter value

    * @param targetSqlType the SQL type (as defined in java.sql.Types) to be

    *                      sent to the database

    * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

    * @exception SQLFeatureNotSupportedException if <code>targetSqlType</code> is

    * a <code>ARRAY</code>, <code>BLOB</code>, <code>CLOB</code>,

    * <code>DATALINK</code>, <code>JAVA_OBJECT</code>, <code>NCHAR</code>,

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

    *  <code>REF</code>, <code>ROWID</code>, <code>SQLXML</code>

    * or  <code>STRUCT</code> data type and the JDBC driver does not support

    * this data type

    * @see Types

    */

    void setObject(int parameterIndex, Object x, int targetSqlType)

      throws SQLException;

    /**

     * <p>Sets the value of the designated parameter using the given object.

     * The second parameter must be of type <code>Object</code>; therefore, the

     * <code>java.lang</code> equivalent objects should be used for built-in types.

     *

     * <p>The JDBC specification specifies a standard mapping from

     * Java <code>Object</code> types to SQL types.  The given argument

     * will be converted to the corresponding SQL type before being

     * sent to the database.

     *

     * <p>Note that this method may be used to pass datatabase-

     * specific abstract data types, by using a driver-specific Java

     * type.

     *

     * If the object is of a class implementing the interface <code>SQLData</code>,

     * the JDBC driver should call the method <code>SQLData.writeSQL</code>

     * to write it to the SQL data stream.

     * If, on the other hand, the object is of a class implementing

     * <code>Ref</code>, <code>Blob</code>, <code>Clob</code>,  <code>NClob</code>,

     *  <code>Struct</code>, <code>java.net.URL</code>, <code>RowId</code>, <code>SQLXML</code>

     * or <code>Array</code>, the driver should pass it to the database as a

     * value of the corresponding SQL type.

     * <P>

     *<b>Note:</b> Not all databases allow for a non-typed Null to be sent to

     * the backend. For maximum portability, the <code>setNull</code> or the

     * <code>setObject(int parameterIndex, Object x, int sqlType)</code>

     * method should be used

     * instead of <code>setObject(int parameterIndex, Object x)</code>.

     *<p>

     * <b>Note:</b> This method throws an exception if there is an ambiguity, for example, if the

     * object is of a class implementing more than one of the interfaces named above.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x the object containing the input parameter value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs;

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

     * or the type of the given object is ambiguous

     */

    void setObject(int parameterIndex, Object x) throws SQLException;

    /**

     * Executes the SQL statement in this <code>PreparedStatement</code> object,

     * which may be any kind of SQL statement.

     * Some prepared statements return multiple results; the <code>execute</code>

     * method handles these complex statements as well as the simpler

     * form of statements handled by the methods <code>executeQuery</code>

     * and <code>executeUpdate</code>.

     * <P>

     * The <code>execute</code> method returns a <code>boolean</code> to

     * indicate the form of the first result.  You must call either the method

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

     * to retrieve the result; you must call <code>getMoreResults</code> to

     * move to any subsequent result(s).

     *

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

     *         object; <code>false</code> if the first result is an update

     *         count or there is no result

     * @exception SQLException if a database access error occurs;

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

     * or an argument is supplied to this method

     * @see Statement#execute

     * @see Statement#getResultSet

     * @see Statement#getUpdateCount

     * @see Statement#getMoreResults

     */

    boolean execute() throws SQLException;

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

    /**

     * Adds a set of parameters to this <code>PreparedStatement</code>

     * object's batch of commands.

     *

     * @exception SQLException if a database access error occurs or

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

     * @see Statement#addBatch

     * @since 1.2

     */

    void addBatch() throws SQLException;

    /**

     * Sets the designated parameter to the given <code>Reader</code>

     * object, which is the given number of characters long.

     * When a very large UNICODE value is input to a <code>LONGVARCHAR</code>

     * parameter, it may be more practical to send it via a

     * <code>java.io.Reader</code> object. The data will be read from the stream

     * as needed until end-of-file is reached.  The JDBC driver will

     * do any necessary conversion from UNICODE to the database char format.

     *

     * <P><B>Note:</B> This stream object can either be a standard

     * Java stream object or your own subclass that implements the

     * standard interface.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param reader the <code>java.io.Reader</code> object that contains the

     *        Unicode data

     * @param length the number of characters in the stream

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

     * @since 1.2

     */

    void setCharacterStream(int parameterIndex,

                          java.io.Reader reader,

                          int length) throws SQLException;

    /**

     * Sets the designated parameter to the given

     *  <code>REF(&lt;structured-type&gt;)</code> value.

     * The driver converts this to an SQL <code>REF</code> value when it

     * sends it to the database.

     *

     * @param parameterIndex the first parameter is 1, the second is 2, ...

     * @param x an SQL <code>REF</code> value

     * @exception SQLException if parameterIndex does not correspond to a parameter

     * marker in the SQL statement; if a database access error occurs or

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

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

     * @since 1.2

     */

    void setRef (int parameterIndex, Ref x) throws SQLException;

    /**