Create and use PreparedStatements

The prepareStatement method is used to create new PreparedStatement objects. Unlike the createStatement method, the SQL statement must be supplied when the PreparedStatement object is created. At that time, the SQL statement is precompiled for use.

For example, assuming a Connection object named conn already exists, the following example creates a PreparedStatement object and prepares the SQL statement for processing within the database.

     PreparedStatement ps = conn.prepareStatement("SELECT * FROM EMPLOYEE_TABLE
                                                  WHERE LASTNAME = ?");

Specify ResultSet characteristics and auto-generated key support

As with the createStatement method, the prepareStatement method is overloaded to provide support for specifying ResultSet characteristics. The prepareStatement method also has variations for working with auto-generated keys. The following are some examples of valid calls to the prepareStatement method:

Example: The prepareStatement method

Note: Read the Code example disclaimer for important legal information.

     // New in JDBC 2.0

     PreparedStatement ps2 = conn.prepareStatement("SELECT * FROM
         EMPLOYEE_TABLE WHERE LASTNAME = ?",

     ResultSet.TYPE_SCROLL_INSENSITIVE,
     ResultSet.CONCUR_UPDATEABLE);

     // New in JDBC 3.0

     PreparedStatement ps3 = conn.prepareStatement("SELECT * FROM
         EMPLOYEE_TABLE WHERE LASTNAME = ?",
         ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_UPDATEABLE,
         ResultSet.HOLD_CURSOR_OVER_COMMIT);

     PreparedStatement ps4 = conn.prepareStatement("SELECT * FROM
         EMPLOYEE_TABLE WHERE LASTNAME = ?", Statement.RETURN_GENERATED_KEYS);

Handle parameters

Before a PreparedStatement object can be processed, each of the parameter markers must be set to some value. The PreparedStatement object provides a number of methods for setting parameters. All methods are of the form set<Type>, where <Type> is a Java™ data type. Some examples of these methods include setInt, setLong, setString, setTimestamp, setNull, and setBlob. Nearly all of these methods take two parameters:

The first parameter is the index of the parameter within the statement. Parameter markers are numbered, starting with 1.
The second parameter is the value to set the parameter to. There are a couple set<Type> methods that have additional parameters such as the length parameter on setBinaryStream.

Consult the Javadoc for the java.sql package for more information. Given the prepared SQL statement in the previous examples for the ps object, the following code illustrates how the parameter value is specified before processing:

ps.setString(1,'Dettinger');

If an attempt is made to process a PreparedStatement with parameter markers that have not been set, an SQLException is thrown.

Note: Once set, parameter markers hold the same value between processes unless the following situations occur:

The value is changed by another call to a set method.
The value is removed when the clearParameters method is called.

The clearParameters method flags all parameters as being unset. After the call to clearParameters has been made, all the parameters must have the set method called again before the next process.

ParameterMetaData support

A new ParameterMetaData interface allows you to retrieve information about a parameter. This support is the compliment to ResultSetMetaData and is similar. Information such as the precision, scale, data type, data type name, and whether the parameter allows the null value are all provided.

See Example: ParameterMetaData on how to use this new support in an application program.