/* * Copyright (c) 1996, 2010, 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; import java.math.BigDecimal; import java.util.Calendar; import java.io.Reader; import java.io.InputStream; /** * An object that represents a precompiled SQL statement. *

A SQL statement is precompiled and stored in a * PreparedStatement object. This object can then be used to * efficiently execute this statement multiple times. * *

Note: The setter methods (setShort, setString, * 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 * INTEGER, then the method setInt should be used. * *

If arbitrary parameter type conversions are required, the method * setObject should be used with a target SQL type. *

* In the following example of setting a parameter, con represents * an active connection: *

 *   PreparedStatement pstmt = con.prepareStatement("UPDATE EMPLOYEES
 *                                     SET SALARY = ? WHERE ID = ?");
 *   pstmt.setBigDecimal(1, 153833.00)
 *   pstmt.setInt(2, 110592)
 * 
* * @see Connection#prepareStatement * @see ResultSet */ public interface PreparedStatement extends Statement { /** * Executes the SQL query in this PreparedStatement object * and returns the ResultSet object generated by the query. * * @return a ResultSet object that contains the data produced by the * query; never null * @exception SQLException if a database access error occurs; * this method is called on a closed PreparedStatement or the SQL * statement does not return a ResultSet object * @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() throws SQLException; /** * Executes the SQL statement in this PreparedStatement object, * which must be an SQL Data Manipulation Language (DML) statement, such as INSERT, UPDATE or * DELETE; 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 PreparedStatement * or the SQL statement returns a ResultSet object * @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() throws SQLException; /** * Sets the designated parameter to SQL NULL. * *

Note: 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 java.sql.Types * @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 PreparedStatement * @exception SQLFeatureNotSupportedException if sqlType is * a ARRAY, BLOB, CLOB, * DATALINK, JAVA_OBJECT, NCHAR, * NCLOB, NVARCHAR, LONGNVARCHAR, * REF, ROWID, SQLXML * or STRUCT 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 boolean value. * The driver converts this * to an SQL BIT or BOOLEAN 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 PreparedStatement */ void setBoolean(int parameterIndex, boolean x) throws SQLException; /** * Sets the designated parameter to the given Java byte value. * The driver converts this * to an SQL TINYINT 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 PreparedStatement */ void setByte(int parameterIndex, byte x) throws SQLException; /** * Sets the designated parameter to the given Java short value. * The driver converts this * to an SQL SMALLINT 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 PreparedStatement */ void setShort(int parameterIndex, short x) throws SQLException; /** * Sets the designated parameter to the given Java int value. * The driver converts this * to an SQL INTEGER 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 PreparedStatement */ void setInt(int parameterIndex, int x) throws SQLException; /** * Sets the designated parameter to the given Java long value. * The driver converts this * to an SQL BIGINT 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 PreparedStatement */ void setLong(int parameterIndex, long x) throws SQLException; /** * Sets the designated parameter to the given Java float value. * The driver converts this * to an SQL REAL 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 PreparedStatement */ void setFloat(int parameterIndex, float x) throws SQLException; /** * Sets the designated parameter to the given Java double value. * The driver converts this * to an SQL DOUBLE 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 PreparedStatement */ void setDouble(int parameterIndex, double x) throws SQLException; /** * Sets the designated parameter to the given java.math.BigDecimal value. * The driver converts this to an SQL NUMERIC 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 PreparedStatement */ void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException; /** * Sets the designated parameter to the given Java String value. * The driver converts this * to an SQL VARCHAR or LONGVARCHAR value * (depending on the argument's * size relative to the driver's limits on VARCHAR 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 PreparedStatement */ 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 VARBINARY or LONGVARBINARY * (depending on the argument's size relative to the driver's limits on * VARBINARY 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 PreparedStatement */ void setBytes(int parameterIndex, byte x[]) throws SQLException; /** * Sets the designated parameter to the given java.sql.Date value * using the default time zone of the virtual machine that is running * the application. * The driver converts this * to an SQL DATE 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 PreparedStatement */ void setDate(int parameterIndex, java.sql.Date x) throws SQLException; /** * Sets the designated parameter to the given java.sql.Time value. * The driver converts this * to an SQL TIME 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 PreparedStatement */ void setTime(int parameterIndex, java.sql.Time x) throws SQLException; /** * Sets the designated parameter to the given java.sql.Timestamp value. * The driver * converts this to an SQL TIMESTAMP 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 PreparedStatement */ 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 LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.InputStream. 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. * *

Note: 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 PreparedStatement */ 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 LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.InputStream 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. * *

Note: 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 java.io.InputStream 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 PreparedStatement * @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 LONGVARBINARY * parameter, it may be more practical to send it via a * java.io.InputStream object. The data will be read from the * stream as needed until end-of-file is reached. * *

Note: 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 PreparedStatement */ void setBinaryStream(int parameterIndex, java.io.InputStream x, int length) throws SQLException; /** * Clears the current parameter values immediately. *

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 clearParameters. * * @exception SQLException if a database access error occurs or * this method is called on a closed PreparedStatement */ void clearParameters() throws SQLException; //---------------------------------------------------------------------- // Advanced features: /** * Sets the value of the designated parameter with the given object. * This method is like the method setObject * 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 PreparedStatement * @exception SQLFeatureNotSupportedException if targetSqlType is * a ARRAY, BLOB, CLOB, * DATALINK, JAVA_OBJECT, NCHAR, * NCLOB, NVARCHAR, LONGNVARCHAR, * REF, ROWID, SQLXML * or STRUCT data type and the JDBC driver does not support * this data type * @see Types */ void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException; /** *

Sets the value of the designated parameter using the given object. * The second parameter must be of type Object; therefore, the * java.lang equivalent objects should be used for built-in types. * *

The JDBC specification specifies a standard mapping from * Java Object types to SQL types. The given argument * will be converted to the corresponding SQL type before being * sent to the database. * *

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 SQLData, * the JDBC driver should call the method SQLData.writeSQL * to write it to the SQL data stream. * If, on the other hand, the object is of a class implementing * Ref, Blob, Clob, NClob, * Struct, java.net.URL, RowId, SQLXML * or Array, the driver should pass it to the database as a * value of the corresponding SQL type. *

*Note: Not all databases allow for a non-typed Null to be sent to * the backend. For maximum portability, the setNull or the * setObject(int parameterIndex, Object x, int sqlType) * method should be used * instead of setObject(int parameterIndex, Object x). *

* Note: 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 PreparedStatement * or the type of the given object is ambiguous */ void setObject(int parameterIndex, Object x) throws SQLException; /** * Executes the SQL statement in this PreparedStatement object, * which may be any kind of SQL statement. * Some prepared statements return multiple results; the execute * method handles these complex statements as well as the simpler * form of statements handled by the methods executeQuery * and executeUpdate. *

* The execute method returns a boolean to * indicate the form of the first result. You must call either the method * getResultSet or getUpdateCount * to retrieve the result; you must call getMoreResults to * move to any subsequent result(s). * * @return true if the first result is a ResultSet * object; false 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 PreparedStatement * or an argument is supplied to this method * @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 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 PreparedStatement * object's batch of commands. * * @exception SQLException if a database access error occurs or * this method is called on a closed PreparedStatement * @see Statement#addBatch * @since 1.2 */ void addBatch() throws SQLException; /** * Sets the designated parameter to the given Reader * object, which is the given number of characters long. * When a very large UNICODE value is input to a LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.Reader 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. * *

Note: 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 java.io.Reader 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 PreparedStatement * @since 1.2 */ void setCharacterStream(int parameterIndex, java.io.Reader reader, int length) throws SQLException; /** * Sets the designated parameter to the given * REF(<structured-type>) value. * The driver converts this to an SQL REF value when it * sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x an SQL REF 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 PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.2 */ void setRef (int parameterIndex, Ref x) throws SQLException; /** * Sets the designated parameter to the given java.sql.Blob object. * The driver converts this to an SQL BLOB value when it * sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x a Blob object that maps an SQL BLOB 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 PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.2 */ void setBlob (int parameterIndex, Blob x) throws SQLException; /** * Sets the designated parameter to the given java.sql.Clob object. * The driver converts this to an SQL CLOB value when it * sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x a Clob object that maps an SQL CLOB 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 PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.2 */ void setClob (int parameterIndex, Clob x) throws SQLException; /** * Sets the designated parameter to the given java.sql.Array object. * The driver converts this to an SQL ARRAY value when it * sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x an Array object that maps an SQL ARRAY 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 PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.2 */ void setArray (int parameterIndex, Array x) throws SQLException; /** * Retrieves a ResultSetMetaData object that contains * information about the columns of the ResultSet object * that will be returned when this PreparedStatement object * is executed. *

* Because a PreparedStatement object is precompiled, it is * possible to know about the ResultSet object that it will * return without having to execute it. Consequently, it is possible * to invoke the method getMetaData on a * PreparedStatement object rather than waiting to execute * it and then invoking the ResultSet.getMetaData method * on the ResultSet object that is returned. *

* NOTE: Using this method may be expensive for some drivers due * to the lack of underlying DBMS support. * * @return the description of a ResultSet object's columns or * null if the driver cannot return a * ResultSetMetaData object * @exception SQLException if a database access error occurs or * this method is called on a closed PreparedStatement * @exception SQLFeatureNotSupportedException if the JDBC driver does not support * this method * @since 1.2 */ ResultSetMetaData getMetaData() throws SQLException; /** * Sets the designated parameter to the given java.sql.Date value, * using the given Calendar object. The driver uses * the Calendar object to construct an SQL DATE value, * which the driver then sends to the database. With * a Calendar object, the driver can calculate the date * taking into account a custom timezone. If no * Calendar object is specified, the driver uses the default * timezone, which is that of the virtual machine running the application. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @param cal the Calendar object the driver will use * to construct the date * @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 PreparedStatement * @since 1.2 */ void setDate(int parameterIndex, java.sql.Date x, Calendar cal) throws SQLException; /** * Sets the designated parameter to the given java.sql.Time value, * using the given Calendar object. The driver uses * the Calendar object to construct an SQL TIME value, * which the driver then sends to the database. With * a Calendar object, the driver can calculate the time * taking into account a custom timezone. If no * Calendar object is specified, the driver uses the default * timezone, which is that of the virtual machine running the application. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @param cal the Calendar object the driver will use * to construct the time * @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 PreparedStatement * @since 1.2 */ void setTime(int parameterIndex, java.sql.Time x, Calendar cal) throws SQLException; /** * Sets the designated parameter to the given java.sql.Timestamp value, * using the given Calendar object. The driver uses * the Calendar object to construct an SQL TIMESTAMP value, * which the driver then sends to the database. With a * Calendar object, the driver can calculate the timestamp * taking into account a custom timezone. If no * Calendar object is specified, the driver uses the default * timezone, which is that of the virtual machine running the application. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @param cal the Calendar object the driver will use * to construct the timestamp * @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 PreparedStatement * @since 1.2 */ void setTimestamp(int parameterIndex, java.sql.Timestamp x, Calendar cal) throws SQLException; /** * Sets the designated parameter to SQL NULL. * This version of the method setNull should * be used for user-defined types and REF type parameters. Examples * of user-defined types include: STRUCT, DISTINCT, JAVA_OBJECT, and * named array types. * *

Note: To be portable, applications must give the * SQL type code and the fully-qualified SQL type name when specifying * a NULL user-defined or REF parameter. In the case of a user-defined type * the name is the type name of the parameter itself. For a REF * parameter, the name is the type name of the referenced type. If * a JDBC driver does not need the type code or type name information, * it may ignore it. * * Although it is intended for user-defined and Ref parameters, * this method may be used to set a null parameter of any JDBC type. * If the parameter does not have a user-defined or REF type, the given * typeName is ignored. * * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param sqlType a value from java.sql.Types * @param typeName the fully-qualified name of an SQL user-defined type; * ignored if the parameter is not a user-defined type or REF * @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 PreparedStatement * @exception SQLFeatureNotSupportedException if sqlType is * a ARRAY, BLOB, CLOB, * DATALINK, JAVA_OBJECT, NCHAR, * NCLOB, NVARCHAR, LONGNVARCHAR, * REF, ROWID, SQLXML * or STRUCT data type and the JDBC driver does not support * this data type or if the JDBC driver does not support this method * @since 1.2 */ void setNull (int parameterIndex, int sqlType, String typeName) throws SQLException; //------------------------- JDBC 3.0 ----------------------------------- /** * Sets the designated parameter to the given java.net.URL value. * The driver converts this to an SQL DATALINK value * when it sends it to the database. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the java.net.URL object to be set * @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 PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.4 */ void setURL(int parameterIndex, java.net.URL x) throws SQLException; /** * Retrieves the number, types and properties of this * PreparedStatement object's parameters. * * @return a ParameterMetaData object that contains information * about the number, types and properties for each * parameter marker of this PreparedStatement object * @exception SQLException if a database access error occurs or * this method is called on a closed PreparedStatement * @see ParameterMetaData * @since 1.4 */ ParameterMetaData getParameterMetaData() throws SQLException; //------------------------- JDBC 4.0 ----------------------------------- /** * Sets the designated parameter to the given java.sql.RowId object. The * driver converts this to a SQL ROWID value when it sends it * to the database * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the parameter value * @throws 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 PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * * @since 1.6 */ void setRowId(int parameterIndex, RowId x) throws SQLException; /** * Sets the designated paramter to the given String object. * The driver converts this to a SQL NCHAR or * NVARCHAR or LONGNVARCHAR value * (depending on the argument's * size relative to the driver's limits on NVARCHAR values) * when it sends it to the database. * * @param parameterIndex of the first parameter is 1, the second is 2, ... * @param value the parameter value * @throws SQLException if parameterIndex does not correspond to a parameter * marker in the SQL statement; if the driver does not support national * character sets; if the driver can detect that a data conversion * error could occur; if a database access error occurs; or * this method is called on a closed PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.6 */ void setNString(int parameterIndex, String value) throws SQLException; /** * Sets the designated parameter to a Reader object. The * Reader reads the data till end-of-file is reached. The * driver does the necessary conversion from Java character format to * the national character set in the database. * @param parameterIndex of the first parameter is 1, the second is 2, ... * @param value the parameter value * @param length the number of characters in the parameter data. * @throws SQLException if parameterIndex does not correspond to a parameter * marker in the SQL statement; if the driver does not support national * character sets; if the driver can detect that a data conversion * error could occur; if a database access error occurs; or * this method is called on a closed PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.6 */ void setNCharacterStream(int parameterIndex, Reader value, long length) throws SQLException; /** * Sets the designated parameter to a java.sql.NClob object. The driver converts this to a * SQL NCLOB value when it sends it to the database. * @param parameterIndex of the first parameter is 1, the second is 2, ... * @param value the parameter value * @throws SQLException if parameterIndex does not correspond to a parameter * marker in the SQL statement; if the driver does not support national * character sets; if the driver can detect that a data conversion * error could occur; if a database access error occurs; or * this method is called on a closed PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.6 */ void setNClob(int parameterIndex, NClob value) throws SQLException; /** * Sets the designated parameter to a Reader object. The reader must contain the number * of characters specified by length otherwise a SQLException will be * generated when the PreparedStatement is executed. *This method differs from the setCharacterStream (int, Reader, int) method * because it informs the driver that the parameter value should be sent to * the server as a CLOB. When the setCharacterStream method is used, the * driver may have to do extra work to determine whether the parameter * data should be sent to the server as a LONGVARCHAR or a CLOB * @param parameterIndex index of the first parameter is 1, the second is 2, ... * @param reader An object that contains the data to set the parameter value to. * @param length the number of characters in the parameter data. * @throws 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 PreparedStatement or if the length specified is less than zero. * * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.6 */ void setClob(int parameterIndex, Reader reader, long length) throws SQLException; /** * Sets the designated parameter to a InputStream object. The inputstream must contain the number * of characters specified by length otherwise a SQLException will be * generated when the PreparedStatement is executed. * This method differs from the setBinaryStream (int, InputStream, int) * method because it informs the driver that the parameter value should be * sent to the server as a BLOB. When the setBinaryStream method is used, * the driver may have to do extra work to determine whether the parameter * data should be sent to the server as a LONGVARBINARY or a BLOB * @param parameterIndex index of the first parameter is 1, * the second is 2, ... * @param inputStream An object that contains the data to set the parameter * value to. * @param length the number of bytes in the parameter data. * @throws 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 PreparedStatement; * if the length specified * is less than zero or if the number of bytes in the inputstream does not match * the specfied length. * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * * @since 1.6 */ void setBlob(int parameterIndex, InputStream inputStream, long length) throws SQLException; /** * Sets the designated parameter to a Reader object. The reader must contain the number * of characters specified by length otherwise a SQLException will be * generated when the PreparedStatement is executed. * This method differs from the setCharacterStream (int, Reader, int) method * because it informs the driver that the parameter value should be sent to * the server as a NCLOB. When the setCharacterStream method is used, the * driver may have to do extra work to determine whether the parameter * data should be sent to the server as a LONGNVARCHAR or a NCLOB * @param parameterIndex index of the first parameter is 1, the second is 2, ... * @param reader An object that contains the data to set the parameter value to. * @param length the number of characters in the parameter data. * @throws SQLException if parameterIndex does not correspond to a parameter * marker in the SQL statement; if the length specified is less than zero; * if the driver does not support national character sets; * if the driver can detect that a data conversion * error could occur; if a database access error occurs or * this method is called on a closed PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * * @since 1.6 */ void setNClob(int parameterIndex, Reader reader, long length) throws SQLException; /** * Sets the designated parameter to the given java.sql.SQLXML object. * The driver converts this to an * SQL XML value when it sends it to the database. *

* * @param parameterIndex index of the first parameter is 1, the second is 2, ... * @param xmlObject a SQLXML object that maps an SQL XML value * @throws 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 PreparedStatement * or the java.xml.transform.Result, * Writer or OutputStream has not been closed for * the SQLXML object * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * * @since 1.6 */ void setSQLXML(int parameterIndex, SQLXML xmlObject) throws SQLException; /** *

Sets the value of the designated parameter with the given object. The second * argument must be an object type; for integral values, the * java.lang equivalent objects should be used. * * If the second argument is an InputStream then the stream must contain * the number of bytes specified by scaleOrLength. If the second argument is a * Reader then the reader must contain the number of characters specified * by scaleOrLength. If these conditions are not true the driver will generate a * SQLException when the prepared statement is executed. * *

The given Java object will be converted to the given targetSqlType * before being sent to the database. * * If the object has a custom mapping (is of a class implementing the * interface SQLData), * the JDBC driver should call the method SQLData.writeSQL to * write it to the SQL data stream. * If, on the other hand, the object is of a class implementing * Ref, Blob, Clob, NClob, * Struct, java.net.URL, * or Array, the driver should pass it to the database as a * value of the corresponding SQL type. * *

Note that this method may be used to pass database-specific * abstract data types. * * @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. The scale argument may further qualify this type. * @param scaleOrLength for java.sql.Types.DECIMAL * or java.sql.Types.NUMERIC types, * this is the number of digits after the decimal point. For * Java Object types InputStream and Reader, * this is the length * of the data in the stream or reader. For all other types, * this value will be ignored. * @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 PreparedStatement or * if the Java Object specified by x is an InputStream * or Reader object and the value of the scale parameter is less * than zero * @exception SQLFeatureNotSupportedException if targetSqlType is * a ARRAY, BLOB, CLOB, * DATALINK, JAVA_OBJECT, NCHAR, * NCLOB, NVARCHAR, LONGNVARCHAR, * REF, ROWID, SQLXML * or STRUCT data type and the JDBC driver does not support * this data type * @see Types * * @since 1.6 */ void setObject(int parameterIndex, Object x, int targetSqlType, int scaleOrLength) 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 LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.InputStream. 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. * *

Note: 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 PreparedStatement * @since 1.6 */ void setAsciiStream(int parameterIndex, java.io.InputStream x, long 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 LONGVARBINARY * parameter, it may be more practical to send it via a * java.io.InputStream object. The data will be read from the * stream as needed until end-of-file is reached. * *

Note: 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 PreparedStatement * @since 1.6 */ void setBinaryStream(int parameterIndex, java.io.InputStream x, long length) throws SQLException; /** * Sets the designated parameter to the given Reader * object, which is the given number of characters long. * When a very large UNICODE value is input to a LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.Reader 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. * *

Note: 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 java.io.Reader 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 PreparedStatement * @since 1.6 */ void setCharacterStream(int parameterIndex, java.io.Reader reader, long length) throws SQLException; //----- /** * Sets the designated parameter to the given input stream. * When a very large ASCII value is input to a LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.InputStream. 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. * *

Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. *

Note: Consult your JDBC driver documentation to determine if * it might be more efficient to use a version of * setAsciiStream which takes a length parameter. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the Java input stream that contains the ASCII 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 PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.6 */ void setAsciiStream(int parameterIndex, java.io.InputStream x) throws SQLException; /** * Sets the designated parameter to the given input stream. * When a very large binary value is input to a LONGVARBINARY * parameter, it may be more practical to send it via a * java.io.InputStream object. The data will be read from the * stream as needed until end-of-file is reached. * *

Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. *

Note: Consult your JDBC driver documentation to determine if * it might be more efficient to use a version of * setBinaryStream which takes a length parameter. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param x the java input stream which contains the binary 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 PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.6 */ void setBinaryStream(int parameterIndex, java.io.InputStream x) throws SQLException; /** * Sets the designated parameter to the given Reader * object. * When a very large UNICODE value is input to a LONGVARCHAR * parameter, it may be more practical to send it via a * java.io.Reader 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. * *

Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. *

Note: Consult your JDBC driver documentation to determine if * it might be more efficient to use a version of * setCharacterStream which takes a length parameter. * * @param parameterIndex the first parameter is 1, the second is 2, ... * @param reader the java.io.Reader object that contains the * Unicode data * @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 PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.6 */ void setCharacterStream(int parameterIndex, java.io.Reader reader) throws SQLException; /** * Sets the designated parameter to a Reader object. The * Reader reads the data till end-of-file is reached. The * driver does the necessary conversion from Java character format to * the national character set in the database. *

Note: This stream object can either be a standard * Java stream object or your own subclass that implements the * standard interface. *

Note: Consult your JDBC driver documentation to determine if * it might be more efficient to use a version of * setNCharacterStream which takes a length parameter. * * @param parameterIndex of the first parameter is 1, the second is 2, ... * @param value the parameter value * @throws SQLException if parameterIndex does not correspond to a parameter * marker in the SQL statement; if the driver does not support national * character sets; if the driver can detect that a data conversion * error could occur; if a database access error occurs; or * this method is called on a closed PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.6 */ void setNCharacterStream(int parameterIndex, Reader value) throws SQLException; /** * Sets the designated parameter to a Reader object. * This method differs from the setCharacterStream (int, Reader) method * because it informs the driver that the parameter value should be sent to * the server as a CLOB. When the setCharacterStream method is used, the * driver may have to do extra work to determine whether the parameter * data should be sent to the server as a LONGVARCHAR or a CLOB * *

Note: Consult your JDBC driver documentation to determine if * it might be more efficient to use a version of * setClob which takes a length parameter. * * @param parameterIndex index of the first parameter is 1, the second is 2, ... * @param reader An object that contains the data to set the parameter value to. * @throws 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 PreparedStatementor if parameterIndex does not correspond to a parameter * marker in the SQL statement * * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * @since 1.6 */ void setClob(int parameterIndex, Reader reader) throws SQLException; /** * Sets the designated parameter to a InputStream object. * This method differs from the setBinaryStream (int, InputStream) * method because it informs the driver that the parameter value should be * sent to the server as a BLOB. When the setBinaryStream method is used, * the driver may have to do extra work to determine whether the parameter * data should be sent to the server as a LONGVARBINARY or a BLOB * *

Note: Consult your JDBC driver documentation to determine if * it might be more efficient to use a version of * setBlob which takes a length parameter. * * @param parameterIndex index of the first parameter is 1, * the second is 2, ... * @param inputStream An object that contains the data to set the parameter * value to. * @throws 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 PreparedStatement or * if parameterIndex does not correspond * to a parameter marker in the SQL statement, * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * * @since 1.6 */ void setBlob(int parameterIndex, InputStream inputStream) throws SQLException; /** * Sets the designated parameter to a Reader object. * This method differs from the setCharacterStream (int, Reader) method * because it informs the driver that the parameter value should be sent to * the server as a NCLOB. When the setCharacterStream method is used, the * driver may have to do extra work to determine whether the parameter * data should be sent to the server as a LONGNVARCHAR or a NCLOB *

Note: Consult your JDBC driver documentation to determine if * it might be more efficient to use a version of * setNClob which takes a length parameter. * * @param parameterIndex index of the first parameter is 1, the second is 2, ... * @param reader An object that contains the data to set the parameter value to. * @throws SQLException if parameterIndex does not correspond to a parameter * marker in the SQL statement; * if the driver does not support national character sets; * if the driver can detect that a data conversion * error could occur; if a database access error occurs or * this method is called on a closed PreparedStatement * @throws SQLFeatureNotSupportedException if the JDBC driver does not support this method * * @since 1.6 */ void setNClob(int parameterIndex, Reader reader) throws SQLException; }