JDBC 3.0's auto-generated keys feature provides a way to retrieve values
from columns that are part of an index or have a default value assigned. supports the auto-increment
feature, which allows users to create columns in tables for which the database
system automatically assigns increasing integer values. In JDBC 3.0, the method Statement.getGeneratedKeys can
be called to retrieve the value of such a column. This method returns a ResultSet object
with a column for the automatically generated key. Calling ResultSet.getMetaData on
the ResultSet object returned by getGeneratedKeys produces a ResultSetMetaData object
that is similar to that returned by IDENTITY_VAL_LOCAL.
Users can indicate that auto-generated columns should be made available
for retrieval by passing one of the following values as a second argument
to the Connection.prepareStatement, Statement.execute, or Statement.executeUpdate methods:
- A constant indicating that auto-generated keys should be made available.
The specific constant to use is Statement.RETURN_GENERATED_KEYS.
- An array of the names of the columns in the inserted row that should be
made available. If any column name in the array does not designate
an auto-increment column,
will throw an error with the embedded
driver. With the client driver, the one element column name is ignored currently and the value returned corresponds to the identity column. To ensure compatibility with future changes an application should ensure the column described is the identity column. If the column name corresponds to another column or a non-existent column then future changes may result in a value for a different column being returned or an exception being thrown.
- An array of the positions of the columns in the inserted row that should
be made available. If any column position in the array does not correlate
to an auto-increment column, will
throw an error with the embedded
driver. With the client driver, the one element position array is ignored currently and the value returned corresponds to the identity column. To ensure compatibility with future changes an application should ensure the column described is the identity column. If the position corresponds to another column or a non-existent column then future changes may result in a value for a different column being returned or an exception being thrown.
Example Assume that we have a table TABLE1 defined
as follows:
CREATE TABLE TABLE1 (C11 int, C12 int GENERATED ALWAYS AS IDENTITY)
The following three code fragments will all do the same thing:
that is, they will create a ResultSet that contains the value of C12
that is inserted into TABLE1.
Code fragment 1:
Statement stmt = conn.createStatement();
stmt.execute(
"INSERT INTO TABLE1 (C11) VALUES (1)",
Statement.RETURN_GENERATED_KEYS);
ResultSet rs = stmt.getGeneratedKeys();
Code fragment 2:
Statement stmt = conn.createStatement();
String [] colNames = new String [] { "C12" };
stmt.execute(
"INSERT INTO TABLE1 (C11) VALUES (1)",
colNames);
ResultSet rs = stmt.getGeneratedKeys();
Code fragment 3:
Statement stmt = conn.createStatement();
int [] colIndexes = new int [] { 2 };
stmt.execute(
"INSERT INTO TABLE1 (C11) VALUES (1)",
colIndexes);
ResultSet rs = stmt.getGeneratedKeys();
If there is no indication that auto-generated columns should
be made available for retrieval, a call to Statement.getGeneratedKeys will
return a null ResultSet.