The DML returning feature provides more functionality compared to retrieval of auto-generated keys. It can be used to retrieve not only auto-generated keys, but also other columns or values that the application may use.
Note:
■The server-side internal driver does not support DML returning
and retrieval of auto-generated keys.
■You cannot use both DML returning and retrieval of
auto-generated keys in the same statement.
Oracle-Specific APIs
The OraclePreparedStatement interface is enhanced with Oracle-specific application programming interfaces (APIs) to support DML returning. The
registerReturnParameter and getReturnResultSet methods have been added to the oracle.jdbc.OraclePreparedStatement interface, to register
parameters that are returned and data retrieved by DML returning.
The registerReturnParameter method is used to register the return parameter for DML returning. The method throws a SQLException instance if an error occurs. You must pass a positive integer specifying the index of the return parameter. You also must specify the type of the return parameter. You can also specify the maximum bytes or characters of the return parameter. This method can be used only with char or RAW
types. You can also specify the fully qualified name of a SQL structure type.
If you do not know the maximum size of the return parameters, then you should use registerReturnParameter(int paramIndex, int externalType), which picks the default maximum size. If you know the maximum size of return parameters, using registerReturnParameter(int paramIndex, int externalType, int maxSize) can reduce memory consumption.
Note:
The getReturnResultSet method fetches the data returned from DML returning and returns it as a ResultSet object. The method throws a SQLException exception if an error occurs.
The Oracle-specific APIs for the DML returning feature are in ojdbc5.jar for Java Development Kit (JDK) 1.5 and in ojdbc6.jar for JDK 1.6.
Running DML Returning Statements
Before running a DML returning statement, the JDBC application must call one or more of the registerReturnParameter methods. The method provides the JDBC drivers with information, such as type and size, of the return parameters. The DML returning statement is then processed using one of the standard JDBC APIs, executeUpdate or execute. You can then fetch the returned parameters as a ResultSet object using the getReturnResultSet method of the oracle.jdbc.OraclePreparedStatement interface.
In order to read the values in the ResultSet object, the underlying Statement object must be open. When the underlying Statement object is closed, the returned ResultSet object is also closed. This is consistent with ResultSet objects that are retrieved by processing SQL query statements.
When a DML returning statement is run, the concurrency of the ResultSet object returned by the getReturnResultSet method must be CONCUR_READ_ONLY and the type of the ResultSet object must be TYPE_FORWARD_ONLY or TYPE_SCROLL_INSENSITIVE.
Example of DML Returning
This section provides two code examples of DML returning.
The following code example illustrates the use of DML returning. In this example, assume that the maximum size of the name column is 100 characters. Because the maximum size of the name column is known, the registerReturnParameter(int paramIndex, int externalType, int maxSize) method is used.
...
OraclePreparedStatement pstmt = (OraclePreparedStatement)conn.prepareStatement(
"delete from tab1 where age < ? returning name into ?");
pstmt.setInt(1,18);
/** register returned parameter
* in this case the maximum size of name is 100 chars
*/
pstmt.registerReturnParameter(2, OracleTypes.VARCHAR, 100);
// process the DML returning statement
count = pstmt.executeUpdate();
if (count>0)
{
ResultSet rset = pstmt.getReturnResultSet(); //rest is not null and not empty
while(rset.next())
{
String name = rset.getString(1);
...
}
}
...
The following code example also illustrates the use of DML returning. However, in this case, the maximum size of the return parameters is not known. Therefore, the registerReturnParameter(int paramIndex, int externalType) method is used.
..
OraclePreparedStatement pstmt = (OraclePreparedStatement)conn.prepareStatement(
"insert into lobtab values (100, empty_clob()) returning col1, col2 into ?, ?");
// register return parameters
pstmt.registerReturnParameter(1, OracleTypes.INTEGER);
pstmt.registerReturnParameter(2, OracleTypes.CLOB);
// process the DML returning SQL statement
pstmt.executeUpdate();
ResultSet rset = pstmt.getReturnResultSet();
int r;
CLOB clob;
if (rset.next())
{
r = rset.getInt(1);
System.out.println(r);
clob = (CLOB)rset.getClob(2);
...
}
...
Limitations of DML Returning
When using DML returning, be aware of the following:
■It is unspecified what the getReturnResultSet method returns when it is invoked more than once. You should not rely on any specific action in this regard.
■The ResultSet objects returned from the execution of DML returning statements do not support the ResultSetMetaData type. Therefore, the applications must know the information of return parameters before running DML returning statements.
■ Streams are not supported with DML returning.
■ DML returning cannot be combined with batch update.
■You cannot use both the auto-generated key feature and the DML returning feature in a single SQL DML statement. For example, the following is not allowed:
...
PreparedStatement pstmt = conn.prepareStatement(’insert into orders (?, ?, ?)
returning order_id into ?");
pstmt.setInt(1, seq01.NEXTVAL);
pstmt.setInt(2, 100);
pstmt.setInt(3, 966431502);
pstmt.registerReturnParam(4, OracleTypes.INTEGER);
pstmt.executeUpdate;
ResultSet rset = pstmt.getGeneratedKeys;
...