Derby currently supports the following JDBC methods for auto-generated keys:
// Indicate that we want to retrieve auto-generated key values.
Connection.prepareStatement(String sql, int autoGeneratedKeys);
Statement.execute(String sql, int autoGeneratedKeys);
Statement.executeUpdate(String sql, int autoGeneratedKeys);
// Retrieve the auto-generated values (only applies to INSERT statements).
ResultSet rs = Statement.getGeneratedKeys();
The current implementation of getGeneratedKeys() internally maps to the "IDENTITY_VAL_LOCAL()" method, which means that Derby's implementation only returns generated keys for autoincrement columns (no other default columns are supported). Further:
1. The generated key result set only ever has a single column. This is
because Derby only allows one autoincrement column per table.
2. The type of the single column in the result set will be DECIMAL(31,0).
This is defined by IDENTITY_VAL_LOCAL().
3. The generated key result set will only ever have a single row. This is
because IDENTITY_VAL_LOCAL() only returns values that were assigned as
the result of a single row INSERT statement using a VALUES clause.
For a single row INSERT statement, at most one autoincrement value
will be generated.
All of that said, JDBC 3.0 also defines the following methods, which allow the user to explicitly indicate, via column position or column name, the columns for which the auto-generated keys should be made available:
Connection.prepareStatement(String sql, String columnNames);
Connection.prepareStatement(String sql, int columnIndexes);
Statement.execute(String sql, String columNames);
Statement.execute(String sql, int columIndexes);
Statement.executeUpdate(String sql, String columnNames);
Statement.executeUpdate(String sql, int columnIndexes);
Derby currently throws a "Feature not supported" error for all of these methods. However, it seems like the above methods could be "mapped" onto the existing Derby behavior with relatively little effort (in embedded mode). Most of the required code is already in place.
Doing so would make it easier for applications that rely on the columnNames and/or columnIndexes APIs to work with Derby (assuming the app just wants generated keys for identity (autoincrement) columns).
Note that this Jira does not entail removing any of the restrictions nor changing any of the behavior outlined above. All of that will remain exactly as it is. This Jira simply exposes the existing functionality (restrictions and all) through additional (standard) API methods. In particular this means that any column specified by index (position) or name must be an auto-increment column for the INSERT table; otherwise Derby should throw an error. Or put differently, a user who specifies a column name/position will get-
in the absence of errors-the exact same results as s/he would get from invoking the "(String sql, int autoGeneratedKeys)" method.
Note also: This Jira is specifically for embedded mode. I think it would be harder to support these methods for Derby Client and so do not plan to address that.