java.sql
Interface PreparedStatement

All Superinterfaces:

Statement

All Known Subinterfaces:

CallableStatement

public interface PreparedStatement
extends Statement

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.

Since:

Android 1.0

Field Summary

Fields inherited from interface java.sql.Statement

CLOSE_ALL_RESULTS, CLOSE_CURRENT_RESULT, EXECUTE_FAILED, KEEP_CURRENT_RESULT, NO_GENERATED_KEYS, RETURN_GENERATED_KEYS, SUCCESS_NO_INFO

Method Summary

void	addBatch() Add a set of parameters to the PreparedStatement's command batch.
void	clearParameters() Clear the current parameter values.
boolean	execute() Executes the SQL statement in this PreparedStatement.
ResultSet	executeQuery() Executes the SQL query in the PreparedStatement and returns the ResultSet generated by the query.
int	executeUpdate() Invokes the SQL command contained within the prepared statement.
ResultSetMetaData	getMetaData() Returns a ResultSetMetaData describing the ResultSet that would be produced by execution of the PreparedStatement.
ParameterMetaData	getParameterMetaData() Gets information about the parameters of the PreparedStatement.
void	setArray(int parameterIndex, Array theArray) Sets the value of a specified parameter to the supplied Array.
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.
void	setBigDecimal(int parameterIndex, BigDecimal theBigDecimal) Sets the value of a specified parameter to a supplied java.math.BigDecimal value.
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.
void	setBlob(int parameterIndex, Blob theBlob) Sets the value of a specified parameter to the given Blob object.
void	setBoolean(int parameterIndex, boolean theBoolean) Sets the value of a specified parameter to a supplied boolean value.
void	setByte(int parameterIndex, byte theByte) Sets the value of a specified parameter to a supplied byte value.
void	setBytes(int parameterIndex, byte[] theBytes) Sets the value of a specified parameter to a supplied array of bytes.
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.
void	setClob(int parameterIndex, Clob theClob) Sets the value of a specified parameter to the given Clob object.
void	setDate(int parameterIndex, Date theDate) Sets the value of a specified parameter to a supplied java.sql.Date value.
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.
void	setDouble(int parameterIndex, double theDouble) Sets the value of a specified parameter to a supplied double value.
void	setFloat(int parameterIndex, float theFloat) Sets the value of a specified parameter to to a supplied float value.
void	setInt(int parameterIndex, int theInt) Sets the value of a specified parameter to a supplied int value.
void	setLong(int parameterIndex, long theLong) Sets the value of a specified parameter to a supplied long value.
void	setNull(int parameterIndex, int sqlType) Sets the value of a specified parameter to SQL NULL.
void	setNull(int paramIndex, int sqlType, String typeName) Sets the value of a specified parameter to SQL NULL.
void	setObject(int parameterIndex, Object theObject) Sets the value of a specified parameter using a supplied object.
void	setObject(int parameterIndex, Object theObject, int targetSqlType) Sets the value of a specified parameter using a supplied object.
void	setObject(int parameterIndex, Object theObject, int targetSqlType, int scale) Sets the value of a specified parameter using a supplied object.
void	setRef(int parameterIndex, Ref theRef) Sets the value of a specified parameter to a supplied REF(<structured-type>) value.
void	setShort(int parameterIndex, short theShort) Sets the value of a specified parameter to a supplied short value.
void	setString(int parameterIndex, String theString) Sets the value of a specified parameter to a supplied string.
void	setTime(int parameterIndex, Time theTime) Sets the value of a specified parameter to a supplied java.sql.Time value.
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.
void	setTimestamp(int parameterIndex, Timestamp theTimestamp) Sets the value of a specified parameter to a supplied java.sql.Timestamp value.
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.
void	setUnicodeStream(int parameterIndex, InputStream theInputStream, int length) Deprecated. Use setCharacterStream(int, Reader, int)
void	setURL(int parameterIndex, URL theURL) Sets the value of a specified parameter to a supplied java.net.URL.

Methods inherited from interface java.sql.Statement

addBatch, cancel, clearBatch, clearWarnings, close, execute, execute, execute, execute, executeBatch, executeQuery, executeUpdate, executeUpdate, executeUpdate, executeUpdate, getConnection, getFetchDirection, getFetchSize, getGeneratedKeys, getMaxFieldSize, getMaxRows, getMoreResults, getMoreResults, getQueryTimeout, getResultSet, getResultSetConcurrency, getResultSetHoldability, getResultSetType, getUpdateCount, getWarnings, setCursorName, setEscapeProcessing, setFetchDirection, setFetchSize, setMaxFieldSize, setMaxRows, setQueryTimeout

Method Detail

addBatch

void addBatch()
              throws SQLException

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

Throws:

SQLException - if a database error happens.

Since:

Android 1.0

clearParameters

void clearParameters()
                     throws SQLException

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.

Since:

Android 1.0

execute

boolean execute()
                throws SQLException

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.

Since:

Android 1.0

executeQuery

ResultSet executeQuery()
                       throws SQLException

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.

Since:

Android 1.0

executeUpdate

int executeUpdate()
                  throws SQLException

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.

Since:

Android 1.0

getMetaData

ResultSetMetaData getMetaData()
                              throws SQLException

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.

Since:

Android 1.0

getParameterMetaData

ParameterMetaData getParameterMetaData()
                                       throws SQLException

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.

Since:

Android 1.0

setArray

void setArray(int parameterIndex,
              Array theArray)
              throws SQLException

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.

Since:

Android 1.0

See Also:

Array

setAsciiStream

void setAsciiStream(int parameterIndex,
                    InputStream theInputStream,
                    int length)
                    throws SQLException

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

Since:

Android 1.0

setBigDecimal

void setBigDecimal(int parameterIndex,
                   BigDecimal theBigDecimal)
                   throws SQLException

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.

Since:

Android 1.0

See Also:

BigDecimal

setBinaryStream

void setBinaryStream(int parameterIndex,
                     InputStream theInputStream,
                     int length)
                     throws SQLException

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.

Since:

Android 1.0

setBlob

void setBlob(int parameterIndex,
             Blob theBlob)
             throws SQLException

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.

Since:

Android 1.0

See Also:

Blob

setBoolean

void setBoolean(int parameterIndex,
                boolean theBoolean)
                throws SQLException

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.

Since:

Android 1.0

setByte

void setByte(int parameterIndex,
             byte theByte)
             throws SQLException

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.

Since:

Android 1.0

setBytes

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

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.

Since:

Android 1.0

setCharacterStream

void setCharacterStream(int parameterIndex,
                        Reader reader,
                        int length)
                        throws SQLException

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.

Since:

Android 1.0

setClob

void setClob(int parameterIndex,
             Clob theClob)
             throws SQLException

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.

Since:

Android 1.0

setDate

void setDate(int parameterIndex,
             Date theDate)
             throws SQLException

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.

Since:

Android 1.0

setDate

void setDate(int parameterIndex,
             Date theDate,
             Calendar cal)
             throws SQLException

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.

Since:

Android 1.0

See Also:

Date, Calendar

setDouble

void setDouble(int parameterIndex,
               double theDouble)
               throws SQLException

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.

Since:

Android 1.0

setFloat

void setFloat(int parameterIndex,
              float theFloat)
              throws SQLException

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.

Since:

Android 1.0

setInt

void setInt(int parameterIndex,
            int theInt)
            throws SQLException

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.

Since:

Android 1.0

setLong

void setLong(int parameterIndex,
             long theLong)
             throws SQLException

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.

Since:

Android 1.0

setNull

void setNull(int parameterIndex,
             int sqlType)
             throws SQLException

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.

Since:

Android 1.0

setNull

void setNull(int paramIndex,
             int sqlType,
             String typeName)
             throws SQLException

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.

Since:

Android 1.0

See Also:

Types

setObject

void setObject(int parameterIndex,
               Object theObject)
               throws SQLException

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.

Since:

Android 1.0

setObject

void setObject(int parameterIndex,
               Object theObject,
               int targetSqlType)
               throws SQLException

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.

Since:

Android 1.0

setObject

void setObject(int parameterIndex,
               Object theObject,
               int targetSqlType,
               int scale)
               throws SQLException

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.

Since:

Android 1.0

setRef

void setRef(int parameterIndex,
            Ref theRef)
            throws SQLException

Sets the value of a specified parameter to a supplied REF(<structured-type>) 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.

Since:

Android 1.0

See Also:

Ref

setShort

void setShort(int parameterIndex,
              short theShort)
              throws SQLException

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.

Since:

Android 1.0

setString

void setString(int parameterIndex,
               String theString)
               throws SQLException

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.

Since:

Android 1.0

setTime

void setTime(int parameterIndex,
             Time theTime)
             throws SQLException

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.

Since:

Android 1.0

setTime

void setTime(int parameterIndex,
             Time theTime,
             Calendar cal)
             throws SQLException

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.

Since:

Android 1.0

See Also:

Time, Calendar

setTimestamp

void setTimestamp(int parameterIndex,
                  Timestamp theTimestamp)
                  throws SQLException

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.

Since:

Android 1.0

setTimestamp

void setTimestamp(int parameterIndex,
                  Timestamp theTimestamp,
                  Calendar cal)
                  throws SQLException

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.

Since:

Android 1.0

See Also:

Timestamp, Calendar

setUnicodeStream

@Deprecated
void setUnicodeStream(int parameterIndex,
                                 InputStream theInputStream,
                                 int length)
                      throws SQLException

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.

setURL

void setURL(int parameterIndex,
            URL theURL)
            throws SQLException

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.

Since:

Android 1.0

See Also:

URL