public interface

PreparedStatement

implements Statement
java.sql.PreparedStatement
Known Indirect Subclasses

Class Overview

An interface for a precompiled SQL Statement.

An SQL Statement is put into a PreparedStatement and is precompiled so that it can be executed efficiently multiple times.

Setter methods are supplied in the PreparedStatement interface for the setting of IN parameters for the statement. The setter method used for each IN parameter must match the parameter's type.

Summary

[Expand]
Inherited Constants
From interface java.sql.Statement
Public Methods
abstract void addBatch()
Add a set of parameters to the PreparedStatement's command batch.
abstract void clearParameters()
Clear the current parameter values.
abstract boolean execute()
Executes the SQL statement in this PreparedStatement.
abstract ResultSet executeQuery()
Executes the SQL query in the PreparedStatement and returns the ResultSet generated by the query.
abstract int executeUpdate()
Invokes the SQL command contained within the prepared statement.
abstract ResultSetMetaData getMetaData()
Returns a ResultSetMetaData describing the ResultSet that would be produced by execution of the PreparedStatement.
abstract ParameterMetaData getParameterMetaData()
Gets information about the parameters of the PreparedStatement.
abstract void setArray(int parameterIndex, Array theArray)
Sets the value of a specified parameter to the supplied Array.
abstract void setAsciiStream(int parameterIndex, InputStream theInputStream, int length)
Sets the value of a specified parameter to the content of a supplied InputStream, which has a specified number of bytes.
abstract void setBigDecimal(int parameterIndex, BigDecimal theBigDecimal)
Sets the value of a specified parameter to a supplied java.math.BigDecimal value.
abstract void setBinaryStream(int parameterIndex, InputStream theInputStream, int length)
Sets the value of a specified parameter to the content of a supplied binary InputStream, which has a specified number of bytes.
abstract void setBlob(int parameterIndex, Blob theBlob)
Sets the value of a specified parameter to the given Blob object.
abstract void setBoolean(int parameterIndex, boolean theBoolean)
Sets the value of a specified parameter to a supplied boolean value.
abstract void setByte(int parameterIndex, byte theByte)
Sets the value of a specified parameter to a supplied byte value.
abstract void setBytes(int parameterIndex, byte[] theBytes)
Sets the value of a specified parameter to a supplied array of bytes.
abstract void setCharacterStream(int parameterIndex, Reader reader, int length)
Sets the value of a specified parameter to the character content of a Reader object, with the specified length of character data.
abstract void setClob(int parameterIndex, Clob theClob)
Sets the value of a specified parameter to the given Clob object.
abstract void setDate(int parameterIndex, Date theDate, Calendar cal)
Sets the value of a specified parameter to a supplied java.sql.Date value, using a supplied Calendar to map the Date.
abstract void setDate(int parameterIndex, Date theDate)
Sets the value of a specified parameter to a supplied java.sql.Date value.
abstract void setDouble(int parameterIndex, double theDouble)
Sets the value of a specified parameter to a supplied double value.
abstract void setFloat(int parameterIndex, float theFloat)
Sets the value of a specified parameter to to a supplied float value.
abstract void setInt(int parameterIndex, int theInt)
Sets the value of a specified parameter to a supplied int value.
abstract void setLong(int parameterIndex, long theLong)
Sets the value of a specified parameter to a supplied long value.
abstract void setNull(int parameterIndex, int sqlType)
Sets the value of a specified parameter to SQL NULL.
abstract void setNull(int paramIndex, int sqlType, String typeName)
Sets the value of a specified parameter to SQL NULL.
abstract void setObject(int parameterIndex, Object theObject, int targetSqlType)
Sets the value of a specified parameter using a supplied object.
abstract void setObject(int parameterIndex, Object theObject, int targetSqlType, int scale)
Sets the value of a specified parameter using a supplied object.
abstract void setObject(int parameterIndex, Object theObject)
Sets the value of a specified parameter using a supplied object.
abstract void setRef(int parameterIndex, Ref theRef)
Sets the value of a specified parameter to a supplied REF() value.
abstract void setShort(int parameterIndex, short theShort)
Sets the value of a specified parameter to a supplied short value.
abstract void setString(int parameterIndex, String theString)
Sets the value of a specified parameter to a supplied string.
abstract void setTime(int parameterIndex, Time theTime, Calendar cal)
Sets the value of a specified parameter to a supplied java.sql.Time value, using a supplied Calendar.
abstract void setTime(int parameterIndex, Time theTime)
Sets the value of a specified parameter to a supplied java.sql.Time value.
abstract void setTimestamp(int parameterIndex, Timestamp theTimestamp, Calendar cal)
Sets the value of a specified parameter to a supplied java.sql.Timestamp value, using the supplied Calendar.
abstract void setTimestamp(int parameterIndex, Timestamp theTimestamp)
Sets the value of a specified parameter to a supplied java.sql.Timestamp value.
abstract void setURL(int parameterIndex, URL theURL)
Sets the value of a specified parameter to a supplied java.net.URL.
abstract void setUnicodeStream(int parameterIndex, InputStream theInputStream, int length)
This method is deprecated. Use setCharacterStream(int, Reader, int)
[Expand]
Inherited Methods
From interface java.sql.Statement

Public Methods

public abstract void addBatch ()

Since: API Level 1

Add a set of parameters to the PreparedStatement's command batch.

Throws
SQLException if a database error happens.

public abstract void clearParameters ()

Since: API Level 1

Clear the current parameter values.

Typically, parameter values are retained for multiple executions of the 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 abstract boolean execute ()

Since: API Level 1

Executes the SQL statement in this PreparedStatement.

A PreparedStatement may return multiple results. The execute method executes the PreparedStatement and returns a flag indicating the kind of result produced by the action. The methods getResultSet or getUpdateCount are used to retrieve the first result, and the second and subsequent results are retrieved with getMoreResults.

Returns
  • true if the result of the execution is a ResultSet, false if there is no result or if the result is an update count.
Throws
SQLException if a database error happens.

public abstract ResultSet executeQuery ()

Since: API Level 1

Executes the SQL query in the PreparedStatement and returns the ResultSet generated by the query.

Returns
  • the ResultSet generated by the query, never null.
Throws
SQLException if a database error happens or if the SQL statement does not produce a ResultSet.

public abstract int executeUpdate ()

Since: API Level 1

Invokes the SQL command contained within the prepared statement. This must be INSERT, UPDATE, DELETE, or a command that returns nothing.

Returns
  • the number of affected rows for INSERT, UPDATE or DELETE statements, 0 for statements that return nothing.
Throws
SQLException if a database error happens or if the SQL statement returns a ResultSet.

public abstract ResultSetMetaData getMetaData ()

Since: API Level 1

Returns a ResultSetMetaData describing the ResultSet that would be produced by execution of the PreparedStatement.

It is possible to know the metadata for the ResultSet without executing the PreparedStatement, because the PreparedStatement is precompiled. As a result the metadata can be queried ahead of time without actually executing the statement.

Returns
  • a ResultSetMetaData object with the information about the columns of the ResultSet, if the driver can return a ResultSetMetaData. null otherwise.
Throws
SQLException if there is a database error.

public abstract ParameterMetaData getParameterMetaData ()

Since: API Level 1

Gets information about the parameters of the PreparedStatement.

Returns
  • a ParameterMetaData object which holds information about the number, type, and properties of the parameters of this PreparedStatement.
Throws
SQLException if a database error happens.

public abstract void setArray (int parameterIndex, Array theArray)

Since: API Level 1

Sets the value of a specified parameter to the supplied Array.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theArray a java.sql.Array giving the new value of the parameter at parameterIndex.
Throws
SQLException if a database error happens.
See Also

public abstract void setAsciiStream (int parameterIndex, InputStream theInputStream, int length)

Since: API Level 1

Sets the value of a specified parameter to the content of a supplied InputStream, which has a specified number of bytes.

This is a good method for setting an SQL LONGVARCHAR parameter where the length of the data is large. Data is read from the InputStream until end-of-file is reached or the specified number of bytes is copied.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theInputStream the ASCII InputStream carrying the data to which the parameter at parameterIndex is set.
length the number of bytes in the InputStream to copy to the parameter.
Throws
SQLException if a database error happens.

public abstract void setBigDecimal (int parameterIndex, BigDecimal theBigDecimal)

Since: API Level 1

Sets the value of a specified parameter to a supplied java.math.BigDecimal value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theBigDecimal the value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.
See Also

public abstract void setBinaryStream (int parameterIndex, InputStream theInputStream, int length)

Since: API Level 1

Sets the value of a specified parameter to the content of a supplied binary InputStream, which has a specified number of bytes.

Use this method when a large amount of data needs to be set into a LONGVARBINARY parameter.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theInputStream the binary InputStream carrying the data to update the parameter.
length the number of bytes in the InputStream to copy to the parameter.
Throws
SQLException if a database error happens.

public abstract void setBlob (int parameterIndex, Blob theBlob)

Since: API Level 1

Sets the value of a specified parameter to the given Blob object.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theBlob the java.sql.Blob to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.
See Also

public abstract void setBoolean (int parameterIndex, boolean theBoolean)

Since: API Level 1

Sets the value of a specified parameter to a supplied boolean value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theBoolean the boolean value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setByte (int parameterIndex, byte theByte)

Since: API Level 1

Sets the value of a specified parameter to a supplied byte value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theByte the byte value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setBytes (int parameterIndex, byte[] theBytes)

Since: API Level 1

Sets the value of a specified parameter to a supplied array of bytes. The array is mapped to a VARBINARY or LONGVARBINARY in the database.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theBytes the array of bytes to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setCharacterStream (int parameterIndex, Reader reader, int length)

Since: API Level 1

Sets the value of a specified parameter to the character content of a Reader object, with the specified length of character data.

Data is read from the Reader until end-of-file is reached or the specified number of characters are copied.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1
reader the java.io.Reader containing the character data.
length the number of characters to be read.
Throws
SQLException if a database error happens.

public abstract void setClob (int parameterIndex, Clob theClob)

Since: API Level 1

Sets the value of a specified parameter to the given Clob object.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theClob a java.sql.Clob holding the data to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setDate (int parameterIndex, Date theDate, Calendar cal)

Since: API Level 1

Sets the value of a specified parameter to a supplied java.sql.Date value, using a supplied Calendar to map the Date. The Calendar allows the application to control the timezone used to compute the SQL DATE in the database - without the supplied Calendar, the driver uses the default timezone of the Java virtual machine.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theDate a java.sql.Date to which the parameter at parameterIndex is set.
cal a Calendar to use to construct the SQL DATE value.
Throws
SQLException if a database error happens.
See Also

public abstract void setDate (int parameterIndex, Date theDate)

Since: API Level 1

Sets the value of a specified parameter to a supplied java.sql.Date value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theDate a java.sql.Date to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setDouble (int parameterIndex, double theDouble)

Since: API Level 1

Sets the value of a specified parameter to a supplied double value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theDouble the double value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setFloat (int parameterIndex, float theFloat)

Since: API Level 1

Sets the value of a specified parameter to to a supplied float value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theFloat the float value to update the parameter.
Throws
SQLException if a database error happens.

public abstract void setInt (int parameterIndex, int theInt)

Since: API Level 1

Sets the value of a specified parameter to a supplied int value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theInt the int value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setLong (int parameterIndex, long theLong)

Since: API Level 1

Sets the value of a specified parameter to a supplied long value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theLong the long value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setNull (int parameterIndex, int sqlType)

Since: API Level 1

Sets the value of a specified parameter to SQL NULL. Don't use this version of setNull for User Defined Types (UDT) or for REF type parameters.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
sqlType the SQL type of the parameter, as defined in java.sql.Types.
Throws
SQLException if a database error happens.

public abstract void setNull (int paramIndex, int sqlType, String typeName)

Since: API Level 1

Sets the value of a specified parameter to SQL NULL. This version of setNull should be used for User Defined Types (UDTs) and also REF types. UDTs can be STRUCT, DISTINCT, JAVA_OBJECT and named array types.

Applications must provide the SQL type code and also a fully qualified SQL type name when supplying a 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.

Parameters
paramIndex the parameter number index, where the first parameter has index 1.
sqlType the SQL type of the parameter, as defined in java.sql.Types.
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 Also

public abstract void setObject (int parameterIndex, Object theObject, int targetSqlType)

Since: API Level 1

Sets the value of a specified parameter using a supplied object.

The object is converted to the given targetSqlType before it is sent to the database. If the object has a custom mapping (its class implements the interface SQLData), the JDBC driver will call the method SQLData.writeSQL to write it to the SQL data stream. If the object's class implements Ref, Blob, Clob, Struct, or Array, the driver will pass it to the database in the form of the relevant SQL type.

Parameters
parameterIndex the parameter index, where the first parameter has index 1.
theObject the Object containing the value to which the parameter at parameterIndex is set.
targetSqlType the SQL type to send to the database, as defined in java.sql.Types.
Throws
SQLException if a database error happens.

public abstract void setObject (int parameterIndex, Object theObject, int targetSqlType, int scale)

Since: API Level 1

Sets the value of a specified parameter using a supplied object.

The object is converted to the given targetSqlType before it is sent to the database. If the object has a custom mapping (its class implements the interface SQLData), the JDBC driver will call the method SQLData.writeSQL to write it to the SQL data stream. If the object's class implements Ref, Blob, Clob, Struct, or Array, the driver will pass it to the database in the form of the relevant SQL type.

Parameters
parameterIndex the parameter index, where the first parameter has index 1.
theObject the Object containing the value to which the parameter at parameterIndex is set.
targetSqlType the SQL type to send to the database, as defined in java.sql.Types.
scale the number of digits after the decimal point - only applies to the types java.sql.Types.DECIMAL and java.sql.Types.NUMERIC - ignored for all other types.
Throws
SQLException if a database error happens.

public abstract void setObject (int parameterIndex, Object theObject)

Since: API Level 1

Sets the value of a specified parameter using a supplied object.

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. 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 SQLData, the JDBC driver calls SQLData.writeSQL to write it to the SQL data stream. If the object's class implements Ref, Blob, Clob, Struct, or Array, the driver passes it to the database as a value of the corresponding SQL type.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theObject the object containing the value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setRef (int parameterIndex, Ref theRef)

Since: API Level 1

Sets the value of a specified parameter to a supplied REF() value. This is stored as an SQL REF.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theRef a java.sql.Ref value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.
See Also

public abstract void setShort (int parameterIndex, short theShort)

Since: API Level 1

Sets the value of a specified parameter to a supplied short value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theShort a short value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setString (int parameterIndex, String theString)

Since: API Level 1

Sets the value of a specified parameter to a supplied string.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theString the value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setTime (int parameterIndex, Time theTime, Calendar cal)

Since: API Level 1

Sets the value of a specified parameter to a supplied java.sql.Time value, using a supplied Calendar.

The driver uses the supplied Calendar to create the SQL TIME value, which allows it to use a custom timezone - otherwise the driver uses the default timezone of the Java virtual machine.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theTime a java.sql.Time value to which the parameter at parameterIndex is set.
cal a Calendar to use to construct the SQL TIME value.
Throws
SQLException if a database error happens.
See Also

public abstract void setTime (int parameterIndex, Time theTime)

Since: API Level 1

Sets the value of a specified parameter to a supplied java.sql.Time value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theTime a java.sql.Time value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setTimestamp (int parameterIndex, Timestamp theTimestamp, Calendar cal)

Since: API Level 1

Sets the value of a specified parameter to a supplied java.sql.Timestamp value, using the supplied Calendar.

The driver uses the supplied Calendar to create the SQL TIMESTAMP value, which allows it to use a custom timezone - otherwise the driver uses the default timezone of the Java virtual machine.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theTimestamp the java.sql.Timestamp value to which the parameter at parameterIndex is set.
cal a Calendar to use to construct the SQL TIMESTAMP value
Throws
SQLException if a database error happens.
See Also

public abstract void setTimestamp (int parameterIndex, Timestamp theTimestamp)

Since: API Level 1

Sets the value of a specified parameter to a supplied java.sql.Timestamp value.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theTimestamp the java.sql.Timestamp value to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.

public abstract void setURL (int parameterIndex, URL theURL)

Since: API Level 1

Sets the value of a specified parameter to a supplied java.net.URL.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theURL the URL to which the parameter at parameterIndex is set.
Throws
SQLException if a database error happens.
See Also

public abstract void setUnicodeStream (int parameterIndex, InputStream theInputStream, int length)

Since: API Level 1

This method is deprecated.
Use setCharacterStream(int, Reader, int)

Sets the value of a specified parameter to the characters from a supplied InputStream, with a specified number of bytes.

Parameters
parameterIndex the parameter number index, where the first parameter has index 1.
theInputStream the InputStream with the character data to which the parameter at parameterIndex is set.
length the number of bytes to read from the InputStream.
Throws
SQLException if a database error happens.