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 multiple times efficiently.

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 type of the IN parameter being set.


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()
          Execute the SQL query in the PreparedStatement and return the ResultSet generated by the query.
 int executeUpdate()
          Invoke the SQL command contained within the Prepared Statement.
 ResultSetMetaData getMetaData()
          Returns a ResultSetMetaData containing data from the ResultSet that is produced when the PreparedStatement is invoked.
 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 object.
 void setAsciiStream(int parameterIndex, java.io.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, java.math.BigDecimal theBigDecimal)
          Sets the value of a specified parameter to a supplied java.math.BigDecimal value.
 void setBinaryStream(int parameterIndex, java.io.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, java.io.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, java.util.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, java.lang.String typeName)
          Sets the value of a specified parameter to SQL NULL.
 void setObject(int parameterIndex, java.lang.Object theObject)
          Sets the value of a specified parameter using a supplied object.
 void setObject(int parameterIndex, java.lang.Object theObject, int targetSqlType)
          Sets the value of a specified parameter using a supplied object.
 void setObject(int parameterIndex, java.lang.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() value.
 void setShort(int parameterIndex, short theShort)
          Sets the value of a specified parameter to a supplied short value.
 void setString(int parameterIndex, java.lang.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, java.util.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, java.util.Calendar cal)
          Sets the value of a specified parameter to a supplied java.sql.Timestamp value, using the supplied Calendar.
 void setUnicodeStream(int parameterIndex, java.io.InputStream theInputStream, int length)
          Deprecated. Sets the value of a specified parameter to the characters from a supplied InputStream, with a specified number of bytes.
 void setURL(int parameterIndex, java.net.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

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

execute

boolean execute()
                throws SQLException
Executes the SQL statement in this PreparedStatement.

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

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

executeQuery

ResultSet executeQuery()
                       throws SQLException
Execute the SQL query in the PreparedStatement and return 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.

executeUpdate

int executeUpdate()
                  throws SQLException
Invoke the SQL command contained within the Prepared Statement. This must be INSERT, UPDATE, DELETE, or a command that returns nothing.

Returns:
the count of 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.

getMetaData

ResultSetMetaData getMetaData()
                              throws SQLException
Returns a ResultSetMetaData containing data from the ResultSet that is produced when the PreparedStatement is invoked.

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

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

setArray

void setArray(int parameterIndex,
              Array theArray)
              throws SQLException
Sets the value of a specified parameter to the supplied Array object.

Parameters:
parameterIndex - the parameter number index, where the first parameter has index 1
theArray - a java.sql.Array holing the data to set.
Throws:
SQLException - if a database error happens

setAsciiStream

void setAsciiStream(int parameterIndex,
                    java.io.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 update the parameter
length - the number of bytes in the InputStream to copy to the parameter
Throws:
SQLException - if a database error happens

setBigDecimal

void setBigDecimal(int parameterIndex,
                   java.math.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 java.math.BigInteger value to set
Throws:
SQLException - if a database error happens

setBinaryStream

void setBinaryStream(int parameterIndex,
                     java.io.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

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 - a java.sql.Blob holding the data to update the parameter
Throws:
SQLException - if a database error happens

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 update the parameter
Throws:
SQLException - if a database error happens

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 update the parameter
Throws:
SQLException - if a database error happens

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 update the parameter
Throws:
SQLException - if a database error happens

setCharacterStream

void setCharacterStream(int parameterIndex,
                        java.io.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.

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

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 update the parameter
Throws:
SQLException - if a database error happens

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 update the parameter
Throws:
SQLException - if a database error happens

setDate

void setDate(int parameterIndex,
             Date theDate,
             java.util.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 update the parameter
cal - a Calendar to use to construct the SQL DATE value
Throws:
SQLException - if a database error happens

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 update the parameter
Throws:
SQLException - if a database error happens

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

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 update the parameter
Throws:
SQLException - if a database error happens

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 update the parameter
Throws:
SQLException - if a database error happens

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

setNull

void setNull(int paramIndex,
             int sqlType,
             java.lang.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

setObject

void setObject(int parameterIndex,
               java.lang.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 update the parameter
Throws:
SQLException - if a database error happens

setObject

void setObject(int parameterIndex,
               java.lang.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 update the parameter
targetSqlType - the SQL Type to send to the database, as defined in java.sql.Types
Throws:
SQLException - if a database error happens

setObject

void setObject(int parameterIndex,
               java.lang.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 update the parameter
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

setRef

void setRef(int parameterIndex,
            Ref theRef)
            throws SQLException
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 update the parameter
Throws:
SQLException - if a database error happens

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 update the parameter
Throws:
SQLException - if a database error happens

setString

void setString(int parameterIndex,
               java.lang.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 - a String value to update the parameter
Throws:
SQLException - if a database error happens

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 update the parameter
Throws:
SQLException - if a database error happens

setTime

void setTime(int parameterIndex,
             Time theTime,
             java.util.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 update the parameter
cal - a Calendar to use to construct the SQL TIME value
Throws:
SQLException - if a database error happens

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 update the parameter
Throws:
SQLException - if a database error happens

setTimestamp

void setTimestamp(int parameterIndex,
                  Timestamp theTimestamp,
                  java.util.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 update the parameter
cal - a Calendar to use to construct the SQL TIMESTAMP value
Throws:
SQLException - if a database error happens

setUnicodeStream

@Deprecated
void setUnicodeStream(int parameterIndex,
                                 java.io.InputStream theInputStream,
                                 int length)
                      throws SQLException
Deprecated. 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 update the parameter
length - the number of bytes to read from the InputStream
Throws:
SQLException - if a database error happens

setURL

void setURL(int parameterIndex,
            java.net.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 update the parameter
Throws:
SQLException - if a database error happens

Built on Thu 2006-11-16 12:20:23-0800, from revision 475803M

Apache Derby 10.3 API Documentation - Copyright © 1997,2006 The Apache Software Foundation or its licensors, as applicable.