/* 
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package java.sql;

import java.util.Calendar;
import java.net.URL;
import java.io.InputStream;
import java.io.Reader;
import java.math.BigDecimal;

/**
 * An interface for a precompiled SQL Statement.
 * <p>
 * An SQL Statement is put into a {@code PreparedStatement} and is precompiled
 * so that it can be executed efficiently multiple times.
 * <p>
 * Setter methods are supplied in the {@code PreparedStatement} interface for
 * the setting of {@code IN} parameters for the statement. The setter method
 * used for each {@code IN} parameter must match the parameter's type.
 */
public interface PreparedStatement extends Statement {

    /**
     * Add a set of parameters to the {@code PreparedStatement}'s command batch.
     * 
     * @throws SQLException
     *             if a database error happens.
     */
    public void addBatch() throws SQLException;

    /**
     * Clear the current parameter values.
     * <p>
     * Typically, parameter values are retained for multiple executions of the
     * {@code Statement}. Setting a parameter value replaces the previous value. This
     * method clears the values for all parameters, releasing all resources used
     * by those parameters.
     *
     * @throws SQLException
     *             if a database error happens.
     */
    public void clearParameters() throws SQLException;

    /**
     * Executes the SQL statement in this {@code PreparedStatement}.
     * <p>
     * A {@code PreparedStatement} may return multiple results. The execute
     * method executes the {@code PreparedStatement} and returns a flag 
     * indicating the kind of result produced by the action. The methods 
     * {@code getResultSet} or {@code getUpdateCount} are used to retrieve 
     * the first result, and the second and subsequent results are 
     * retrieved with {@code getMoreResults}.
     *
     * @return {@code true} if the result of the execution is a {@code
     *         ResultSet}, {@code false} if there is no result or if the result
     *         is an update count.
     * @throws SQLException
     *             if a database error happens.
     */
    public boolean execute() throws SQLException;

    /**
     * Executes the SQL query in the {@code PreparedStatement} and returns the
     * {@code ResultSet} generated by the query.
     * 
     * @return the {@code ResultSet} generated by the query, never {@code null}.
     * @throws SQLException
     *             if a database error happens or if the SQL statement does not
     *             produce a {@code ResultSet}.
     */
    public ResultSet executeQuery() throws SQLException;

    /**
     * Invokes the SQL command contained within the prepared statement. This
     * must be {@code INSERT}, {@code UPDATE}, {@code DELETE}, or a command that
     * returns nothing.
     * 
     * @return the number of affected rows for {@code INSERT}, {@code UPDATE} or {@code
     *         DELETE} statements, {@code 0} for statements that return nothing.
     * @throws SQLException
     *             if a database error happens or if the SQL statement returns a
     *             {@code ResultSet}.
     */
    public int executeUpdate() throws SQLException;

    /**
     * Returns a {@code ResultSetMetaData} describing the {@code
     * ResultSet} that would be produced by execution of the {@code PreparedStatement}.
     * <p>
     * It is possible to know the metadata for the {@code ResultSet} without
     * executing the {@code PreparedStatement}, because the {@code
     * PreparedStatement} is precompiled. As a result the metadata can be
     * queried ahead of time without actually executing the statement.
     *
     * @return a {@code ResultSetMetaData} object with the information about the
     *         columns of the {@code ResultSet}, if the driver can return a
     *         {@code ResultSetMetaData}. {@code null} otherwise.
     * @throws SQLException
     *             if there is a database error.
     */
    public ResultSetMetaData getMetaData() throws SQLException;

    /**
     * Gets information about the parameters of the {@code PreparedStatement}.
     * 
     * @return a {@code ParameterMetaData} object which holds information about
     *         the number, type, and properties of the parameters of this {@code
     *         PreparedStatement}.
     * @throws SQLException
     *             if a database error happens.
     */
    public ParameterMetaData getParameterMetaData() throws SQLException;

    /**
     * Sets the value of a specified parameter to the supplied {@code Array}.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theArray
     *            a {@code java.sql.Array} giving the new value of the parameter at {@code
     *            parameterIndex}.
     * @throws SQLException
     *             if a database error happens.
     * @see Array
     */
    public void setArray(int parameterIndex, Array theArray)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to the content of a supplied
     * {@code InputStream}, which has a specified number of bytes.
     * <p>
     * This is a good method for setting an SQL {@code LONGVARCHAR} parameter
     * where the length of the data is large. Data is read from the {@code
     * InputStream} until end-of-file is reached or the specified number of
     * bytes is copied.
     *
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theInputStream
     *            the ASCII {@code InputStream} carrying the data to which the
     *            parameter at {@code parameterIndex} is set.
     * @param length
     *            the number of bytes in the {@code InputStream} to copy to the
     *            parameter.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setAsciiStream(int parameterIndex, InputStream theInputStream,
            int length) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code
     * java.math.BigDecimal} value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theBigDecimal
     *            the value to which the parameter at {@code parameterIndex} is
     *            set.
     * @throws SQLException
     *             if a database error happens.
     * @see java.math.BigDecimal
     */
    public void setBigDecimal(int parameterIndex, BigDecimal theBigDecimal)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to the content of a supplied
     * binary {@code InputStream}, which has a specified number of bytes.
     * <p>
     * Use this method when a large amount of data needs to be set into a
     * {@code LONGVARBINARY} parameter.
     *
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theInputStream
     *            the binary {@code InputStream} carrying the data to update the
     *            parameter.
     * @param length
     *            the number of bytes in the {@code InputStream} to copy to the
     *            parameter.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setBinaryStream(int parameterIndex, InputStream theInputStream,
            int length) throws SQLException;

    /**
     * Sets the value of a specified parameter to the given {@code Blob} object.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theBlob
     *            the {@code java.sql.Blob} to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     * @see Blob
     */
    public void setBlob(int parameterIndex, Blob theBlob) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code boolean}
     * value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theBoolean
     *            the boolean value to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setBoolean(int parameterIndex, boolean theBoolean)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code byte} value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theByte
     *            the byte value to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setByte(int parameterIndex, byte theByte) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied array of bytes. The
     * array is mapped to a {@code VARBINARY} or {@code LONGVARBINARY} in the
     * database.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theBytes
     *            the array of bytes to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setBytes(int parameterIndex, byte[] theBytes)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to the character content of a
     * {@code Reader} object, with the specified length of character data.
     * <p>
     * Data is read from the {@code
     * Reader} until end-of-file is reached or the specified number of
     * characters are copied.
     *
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1
     * @param reader
     *            the {@code java.io.Reader} containing the character data.
     * @param length
     *            the number of characters to be read.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setCharacterStream(int parameterIndex, Reader reader, int length)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to the given {@code Clob} object.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theClob
     *            a {@code java.sql.Clob} holding the data to which the
     *            parameter at {@code parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setClob(int parameterIndex, Clob theClob) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code
     * java.sql.Date} value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theDate
     *            a {@code java.sql.Date} to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setDate(int parameterIndex, Date theDate) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code
     * java.sql.Date} value, using a supplied {@code Calendar} to map the Date.
     * The {@code Calendar} allows the application to control the timezone used
     * to compute the SQL {@code DATE} in the database - without the supplied
     * {@code Calendar}, the driver uses the default timezone of the Java
     * virtual machine.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theDate
     *            a {@code java.sql.Date} to which the parameter at {@code
     *            parameterIndex} is set.
     * @param cal
     *            a {@code Calendar} to use to construct the SQL {@code DATE}
     *            value.
     * @throws SQLException
     *             if a database error happens.
     * @see Date
     * @see java.util.Calendar
     */
    public void setDate(int parameterIndex, Date theDate, Calendar cal)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code double}
     * value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theDouble
     *            the {@code double} value to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setDouble(int parameterIndex, double theDouble)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to to a supplied {@code float}
     * value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theFloat
     *            the {@code float} value to update the parameter.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setFloat(int parameterIndex, float theFloat)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code int} value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theInt
     *            the {@code int} value to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setInt(int parameterIndex, int theInt) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code long} value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theLong
     *            the {@code long} value to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setLong(int parameterIndex, long theLong) throws SQLException;

    /**
     * Sets the value of a specified parameter to SQL {@code NULL}. Don't use
     * this version of {@code setNull} for <i>User Defined Types</i> (UDT) or
     * for REF type parameters.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param sqlType
     *            the SQL type of the parameter, as defined in {@code
     *            java.sql.Types}.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setNull(int parameterIndex, int sqlType) throws SQLException;

    /**
     * Sets the value of a specified parameter to SQL {@code NULL}. This version
     * of {@code setNull} should be used for <i>User Defined Types</i> (UDTs)
     * and also REF types. UDTs can be {@code STRUCT}, {@code DISTINCT}, {@code
     * JAVA_OBJECT} and named array types.
     * <p>
     * Applications must provide the SQL type code and also a fully qualified
     * SQL type name when supplying a {@code NULL} UDT or REF. For a UDT, the
     * type name is the type name of the parameter itself, but for a REF
     * parameter the type name is the type name of the referenced type.
     *
     * @param paramIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param sqlType
     *            the SQL type of the parameter, as defined in {@code
     *            java.sql.Types}.
     * @param typeName
     *            the fully qualified name of a UDT or REF type - ignored if the
     *            parameter is not a UDT.
     * @throws SQLException
     *             if a database error happens.
     * @see Types
     */
    public void setNull(int paramIndex, int sqlType, String typeName)
            throws SQLException;

    /**
     * Sets the value of a specified parameter using a supplied object.
     * <p>
     * There is a standard mapping from Java types to SQL types, defined in the
     * JDBC specification. The passed object is then transformed into the
     * appropriate SQL type, and then transferred to the database. {@code
     * setObject} can be used to pass abstract data types unique to the
     * database, by using a JDBC driver specific Java type. If the object's
     * class implements the interface {@code SQLData}, the JDBC driver calls
     * {@code SQLData.writeSQL} to write it to the SQL data stream. If the
     * object's class implements {@code Ref}, {@code Blob}, {@code Clob},
     * {@code Struct}, or {@code Array}, the driver passes it to the database as
     * a value of the corresponding SQL type.
     *
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theObject
     *            the object containing the value to which the parameter at
     *            {@code parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setObject(int parameterIndex, Object theObject)
            throws SQLException;

    /**
     * Sets the value of a specified parameter using a supplied object.
     * <p>
     * The object is converted to the given {@code targetSqlType} before it is
     * sent to the database. If the object has a custom mapping (its class
     * implements the interface {@code SQLData}), the JDBC driver will call the method
     * {@code SQLData.writeSQL} to write it to the SQL data stream. If the
     * object's class implements {@code Ref}, {@code Blob}, {@code Clob},
     * {@code Struct}, or {@code Array}, the driver will pass it to the database
     * in the form of the relevant SQL type.
     *
     * @param parameterIndex
     *            the parameter index, where the first parameter has index 1.
     * @param theObject
     *            the Object containing the value to which the parameter at
     *            {@code parameterIndex} is set.
     * @param targetSqlType
     *            the SQL type to send to the database, as defined in {@code
     *            java.sql.Types}.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setObject(int parameterIndex, Object theObject,
            int targetSqlType) throws SQLException;

    /**
     * Sets the value of a specified parameter using a supplied object.
     * <p>
     * The object is converted to the given {@code targetSqlType} before it is
     * sent to the database. If the object has a custom mapping (its class
     * implements the interface {@code SQLData}), the JDBC driver will call the method
     * {@code SQLData.writeSQL} to write it to the SQL data stream. If the
     * object's class implements {@code Ref}, {@code Blob}, {@code Clob},
     * {@code Struct}, or {@code Array}, the driver will pass it to the database
     * in the form of the relevant SQL type.
     *
     * @param parameterIndex
     *            the parameter index, where the first parameter has index 1.
     * @param theObject
     *            the Object containing the value to which the parameter at
     *            {@code parameterIndex} is set.
     * @param targetSqlType
     *            the SQL type to send to the database, as defined in {@code
     *            java.sql.Types}.
     * @param scale
     *            the number of digits after the decimal point - only applies to
     *            the types {@code java.sql.Types.DECIMAL} and {@code
     *            java.sql.Types.NUMERIC} - ignored for all other types.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setObject(int parameterIndex, Object theObject,
            int targetSqlType, int scale) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code
     * REF(<structured-type>)} value. This is stored as an SQL {@code REF}.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theRef
     *            a {@code java.sql.Ref} value to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     * @see Ref
     */
    public void setRef(int parameterIndex, Ref theRef) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code short}
     * value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theShort
     *            a {@code short} value to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setShort(int parameterIndex, short theShort)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied string.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theString
     *            the value to which the parameter at {@code parameterIndex} is
     *            set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setString(int parameterIndex, String theString)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code
     * java.sql.Time} value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theTime
     *            a {@code java.sql.Time} value to which the parameter at
     *            {@code parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setTime(int parameterIndex, Time theTime) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code
     * java.sql.Time} value, using a supplied {@code Calendar}.
     * <p>
     * The driver uses the supplied {@code Calendar} to create the SQL {@code
     * TIME} value, which allows it to use a custom timezone - otherwise the
     * driver uses the default timezone of the Java virtual machine.
     *
     * @param parameterIndex
     *            the parameter number index, where the first parameter has 
     *            index 1.
     * @param theTime
     *            a {@code java.sql.Time} value to which the parameter at
     *            {@code parameterIndex} is set.
     * @param cal
     *            a {@code Calendar} to use to construct the SQL {@code TIME}
     *            value.
     * @throws SQLException
     *             if a database error happens.
     * @see Time
     * @see java.util.Calendar
     */
    public void setTime(int parameterIndex, Time theTime, Calendar cal)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied java.sql.Timestamp
     * value.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theTimestamp
     *            the java.sql.Timestamp value to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     */
    public void setTimestamp(int parameterIndex, Timestamp theTimestamp)
            throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code
     * java.sql.Timestamp} value, using the supplied {@code Calendar}.
     * <p>
     * The driver uses the supplied {@code Calendar} to create the SQL {@code
     * TIMESTAMP} value, which allows it to use a custom timezone - otherwise
     * the driver uses the default timezone of the Java virtual machine.
     *
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theTimestamp
     *            the {@code java.sql.Timestamp} value to which the parameter at
     *            {@code parameterIndex} is set.
     * @param cal
     *            a {@code Calendar} to use to construct the SQL {@code
     *            TIMESTAMP} value
     * @throws SQLException
     *             if a database error happens.
     * @see Timestamp
     * @see java.util.Calendar
     */
    public void setTimestamp(int parameterIndex, Timestamp theTimestamp,
            Calendar cal) throws SQLException;

    /**
     * Sets the value of a specified parameter to the characters from a supplied
     * {@code InputStream}, with a specified number of bytes.
     * 
     * @deprecated Use {@link #setCharacterStream(int, Reader, int)}
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theInputStream
     *            the {@code InputStream} with the character data to which the
     *            parameter at {@code parameterIndex} is set.
     * @param length
     *            the number of bytes to read from the {@code InputStream}.
     * @throws SQLException
     *             if a database error happens.
     */
    @Deprecated
    public void setUnicodeStream(int parameterIndex,
            InputStream theInputStream, int length) throws SQLException;

    /**
     * Sets the value of a specified parameter to a supplied {@code
     * java.net.URL}.
     * 
     * @param parameterIndex
     *            the parameter number index, where the first parameter has
     *            index 1.
     * @param theURL
     *            the {@code URL} to which the parameter at {@code
     *            parameterIndex} is set.
     * @throws SQLException
     *             if a database error happens.
     * @see URL
     */
    public void setURL(int parameterIndex, URL theURL) throws SQLException;
}