Configuring Returning Policy

Using a ReturningPolicy, you can obtain field values from the data source when inserting or updating an object. TopLink uses the values that the data source returns to update the object attributes that map to these fields. You can specify which fields to return for inserts and updates. For insert fields, you can also specify whether or not to include the field value in the insert operation.

A ReturningPolicy is useful when the data source provides default or initial field values through defaults, triggers, or stored procedures. You can also use a ReturningPolicy to allow the data source to assign a sequence or primary key value.

Any object attribute that you do not configure in a descriptor's ReturningPolicy receives the default behavior: in the context of a unit of work, if the attribute has changed, its value is written to the database. If the SQL statement invokes a trigger or stored procedure that modifies the database field, the database generated value is not reflected by the object.

Use caution when deciding on whether or not to use a ReturningPolicy, as doing so may effect insert or update performance and is not compatible with batch writing (see "Batch Writing").

By default, you can use a ReturningPolicy with an Oracle Database, in which case, TopLink uses the Oracle RETURNING clause (see "Using TopLink Workbench").

You can use a ReturningPolicy with a non-Oracle database if you configure your descriptor's insert or update query to use a stored procedure that returns the desired returned values as output parameters (see "Using Java").

Table 28-38 summarizes which descriptors support returning policy configuration.

Table 28-29 Descriptor Support for Fetch Group Configuration

Descriptor	Using TopLink Workbench	Using Java
Relational Descriptors
Object-Relational Descriptors
EIS DescriptorsFoot 1
XML Descriptors

^Footnote 1 EIS root descriptors only (see "EIS Root Descriptors").

Using TopLink Workbench

To specify the return policy for a descriptor, use this procedure:

1. Select a descriptor in the Navigator. Its properties appear in the Editor.

   If the Returning advanced property is not visible for the descriptor, right-click the descriptor and choose Select Advanced Properties > Returning from the context menu or from the Selected menu.

2. Click the Returning tab in the Editor.

   Figure 28-39 Returning Tab

   
   Description of "Figure 28-39 Returning Tab"
   
   

Field	Description
Insert	These options apply to insert operations:
Name	Click Add to add a database field to this ReturningPolicy for insert operations.
Return-only	When selected, TopLink only returns a value for this field; it will not include the field in the insert. When not selected, TopLink returns a value for this field and includes the value in the insert.
Update	These options apply to update operations:
Name	Click Add to add a database field to this ReturningPolicy for update operations

To remove a database field from the descriptor's ReturningPolicy, select the field in the Insert or Update window and click Remove.

Note: If you are using TopLink Workbench, you cannot configure a returning policy for an attribute mapped with a transformation mapping (see "Transformation Mapping").

Using Java

You use a ReturningPolicy to configure how TopLink handles returning with the attributes of an object on a field-by-field basis. Table 28-30 describes the ReturnPolicy methods you use to tell TopLink how to handle a particular database field. Each method takes a String or a DatabaseField type parameter as field name.

Table 28-30 Return Policy Methods

Method	Applies to SQL Statements of Type...	Writes Current Value of Field to Database?	Returns Database- Generated Result?
addFieldForInsert	INSERT	Yes	Yes
addFieldForInsertReturnOnly	INSERT	No	Yes
addFieldForUpdate	UPDATE	Yes	Yes

You configure a descriptor with a ReturningPolicy using ClassDescriptor method setReturningPolicy.