Skip Headers

Oracle TopLink Developer's Guide 10g Release 3 (10.1.3) B13593-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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`.