Skip Headers

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

Previous | Next |

# Configuring Locking Policy

You can configure a descriptor with a locking policy that prevents one user writing over another user's work.

Table 28-28 summarizes which descriptors support locking policies.

Table 28-28 Descriptor Support for Locking Policy

Descriptor | Optimistic Version Locking Policies | Optimistic Field Locking Policies | Pessimistic Locking Policy | Using TopLink Workbench | Using Java
--- | --- | --- | --- | --- | ---
Relational DescriptorsFoot 1 |  |  |  |  |
Object-Relational Descriptors |  |  |  |  |
EIS DescriptorsFoot 2 |  |  |  |  |
XML Descriptors |  |  |  |  |

Footnote 1 Relational class descriptors only (see "Relational Class Descriptors").

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

Oracle recommends that you use a locking policy. You should use a locking policy in any multiuser environment to prevent one user writing over another user's changes. Although locking can be particularly important if multiple servers or multiple applications access the same data, even in a single server application, the same locking issue still exists. In a multiple-server environment, locking is still relevant even if your application uses cache refreshing or cache coordination.

If you are building a three-tier application, in order to correctly lock an object, you must obtain the lock before the object is sent to client to be edited. The type of locking you choose has an influence on how you can achieve this (see "Locking in a Three-Tier Application").

## Using TopLink Workbench

To specify a descriptor's locking policy, use this procedure:

1. In the Navigator, select a relational or EIS root descriptor.

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

2. Click the Locking tab.

   Figure 28-37 Locking Tab for a Descriptor

   Figure 28-38 Locking Tab for an EIS Root Descriptor

Use this table to enter data in the following fields on the tab of the appropriate type:

Field | Description
--- | ---
Optimistic Locking | Specify that the descriptor uses optimistic locking.
By Version | Specify to use optimistic locking, based on versioning.
Database Field | Select the database field that contains the version value used for optimistic locking. This field appears for relational descriptors only.
XPath | Click Browse to define the path to the element or attribute that stores the version value. This field appears for EIS root descriptors only. Ensure that the attribute's type corresponds to the type of locking policy you choose (`numeric` for Version Locking and `timestamp` for Timestamp Locking).
Version Locking | Specify that the descriptor uses numeric version locking. The version field (defined by the Database Field, for relational descriptors, or the XPath, for EIS root descriptors) must be a `numeric` type
Timestamp Locking | Specify that the descriptor uses time stamp version locking, based on time stamp. The version field (defined by the Database Field, for relational descriptors, or the XPath, for EIS root descriptors) must be a `timestamp` type.
Store Version in Cache | Specify whether or not you want to store the version information in the cache. If you choose not to define a mapping for the version field, then you must enable this option to configure the descriptor to store the version value in the Oracle TopLink cache. If you choose to define a mapping for the version field, then you must disable this option in order to store the version value in the object. For more information, see "Optimistic Locking in a Three-Tier Application".
By Fields Foot 1 | Specify to use optimistic locking, based on database fields. These fields appear for relational descriptors only.
All Fields | Select all fields for optimistic locking.
Changed Fields | Select only the changed fields for optimistic locking.
Selected Fields | Click Add to select specific database fields for optimistic locking.
Pessimistic Locking | Specify to use pessimistic locking for this descriptor. This applies only to descriptors that have had EJB information configured for them (see "Configuring a Descriptor With EJB Information").
Wait for Lock | Specify whether or not TopLink should wait for a data source lock. When not selected, the thread of execution will immediately throw a `DatabaseException` if it cannot acquire a read lock on the object. When selected, the thread of execution will wait indefinitely until the read lock is released, at which time, it will attempt to acquire it. Use this option with care as it can lead to application deadlocks.

Footnote 1 You cannot use field locking with the `AttributeChangeTrackingPolicy` (see "Attribute Change Tracking Policy").

## Using Java

This section describes:

- Configuring an Optimistic Locking Policy

- Configuring Optimistic Locking Policy Cascading

- Configuring a Pessimistic Locking Policy

### Configuring an Optimistic Locking Policy

Use the `ClassDescriptor` method `setOptimisticLockingPolicy` to set an instance of the appropriate optimistic field locking policy:

- `FieldsLockingPolicy`

- `AllFieldsLockingPolicy`

- `ChangedFieldsLockingPolicy`

- `SelectedFieldsLockingPolicy`

- `VersionLockingPolicy`

- `TimestampLockingPolicy`

Use the `ClassDescriptor` method `getOptimisticLockingPolicy` to get the selected locking policy type and configure it.

### Configuring Optimistic Locking Policy Cascading

If you are using a `VersionLockingPolicy`, you can enable cascading to configure TopLink to automatically force a version field update on a parent object when its privately owned child object's version field changes. Use `VersionLockingPolicy` method `setIsCascaded` passing in a `boolean` of `true` to enable cascading, or `false` to disable cascading.

For more information, see "Optimistic Version Locking Policies and Cascading".

### Configuring a Pessimistic Locking Policy

You can configure a descriptor with a `PessimisticLockingPolicy` only when using a `CMPPolicy`. That is, you only can configure a `PessimisticLockingPolicy` for descriptors that support EJB information (see "Configuring a Descriptor With EJB Information") in a CMP project.

Instantiate a `CMPPolicy` and use `CMPPolicy` method `setPessimisticLockingPolicy` to set an instance of `PessimisticLockingPolicy`. Then use the `ClassDescriptor` method `setCMPPolicy` to set the `CMPPolicy`.