Skip Headers

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

Previous | Next |

# Configuring Change Policy

Use a change policy to specify how TopLink should track changes made to objects after you register them with a unit of work. Table 28-33 summarizes which descriptors support a change policy.

Table 28-33 Descriptor Support for Change Policy

Descriptor | Deferred Change Detection Policy | Object-Level Change Tracking Policy | Attribute Change Tracking 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").

By default, TopLink uses the deferred change detection policy.

TopLink supports alternative change policies (policies other than `DeferredChangeDetectionPolicy`) for attributes that use a subset of the mappings that TopLink supports (see "Change Policy Mapping Support").

For EJB 1.n, 2.n, and 3.0 CMP applications deployed to OC4J, TopLink automatically uses the attribute change tracking policy.

For more information, see "Unit of Work and Change Policy".

## Using Java

This section describes how to configure a descriptor with a change policy using Java, and how to implement persistent classes for those change policies that are intrusive. It includes information on configuring the following:

- Configuring Deferred Change Detection Policy

- Configuring Object Change Tracking Policy

- Configuring Attribute Change Tracking Policy

### Configuring Deferred Change Detection Policy

The `DeferredChangeDetectionPolicy` provides good unit of work commit performance for a wide range of object change characteristics. It is the default change policy. For more information, see "Deferred Change Detection Policy").

Because it is the default, you do not need to explicitly configure this policy.

To configure TopLink to use a `DeferredChangeDetectionPolicy`, create a descriptor amendment method (see "Configuring Amendment Methods") that sets the change policy, as Example 28-19 illustrates.

### Configuring Object Change Tracking Policy

The `ObjectChangeTrackingPolicy` provides improved unit of work commit performance for objects with few attributes, or with many attributes and many changed attributes. For more information, see "Object-Level Change Tracking Policy").

For EJB 2.n or 3.0 CMP applications deployed to an application server, for which TopLink provides CMP integration (see "Application Server Support"), when you configure a CMP entity bean's descriptor with an `ObjectLevelChangeTrackingPolicy`, TopLink automatically generates code of a concrete subclass to implement the TopLink `ChangeTracker` interface at deploy time. Configuring an `ObjectLevelChangeTrackingPolicy` prevents TopLink from automatically applying an `AttributeChangeTrackingPolicy` (see "Configuring Attribute Change Tracking Policy").

To configure TopLink to use an `ObjectChangeTrackingPolicy`, use this procedure:

1. Create a descriptor amendment method (see "Configuring Amendment Methods") that sets the change policy, as Example 28-19 illustrates.

   Example 28-19 Setting the ObjectChangeTrackingPolicy

       descriptor.setObjectChangePolicy(new ObjectChangeTrackingPolicy());

2. For CMP 1.n or plain Java objects, code each of your persistent classes to implement the `ChangeTracker` interface as Example 28-20 illustrates.

   Example 28-20 Implementing the ChangeTracker Interface for the ObjectChangeTrackingPolicy

       public class Employee implements ChangeTracker {

           PropertyChangeListener listener;

           public PropertyChangeListener getTopLinkPropertyChangeListener() {
             return listener;
           }

           public void setTopLinkPropertyChangeListener(PropertyChangeListener listener)
           {
             this.listener = listener;
           }
       ...
           public void setFirstName(String firstName) {
             propertyChange("firstName", getFirstName(), firstName);
             this.firstName = firstName;
           }
       ...
           public void propertyChange(String propertyName, Object oldValue, Object newValue) {
               if (listener != null) {
                   if (oldValue != newValue) {
                       listener.propertyChange(
                           new PropertyChangeEvent(
                               this, propertyName, oldValue, newValue
                           )
                       );
                   }
               }
           }
       }

### Configuring Attribute Change Tracking Policy

The `AttributeChangeTrackingPolicy` provides improved unit of work commit performance for objects with many attributes and few changed attributes. In general, this is the most efficient change policy. It is the default change policy for EJB 3.0 and 2.n CMP applications deployed to OC4J. For more information, see "Attribute Change Tracking Policy").

Note: You cannot use the `AttributeChangeTrackingPolicy` if you are using any instance of `FieldsLockingPolicy` (see "Optimistic Field Locking Policies").

When you deploy a TopLink-enabled EJB 3.0 or 2.n CMP application to OC4J, TopLink automatically configures your persistent classes to use the `AttributeChangeTrackingPolicy` and, using bytecode weaving (EJB 3.0) or code generation (EJB 2.n), configures your persistence classes to implement the TopLink `ChangeTracker` interface. In this case, you do not need to explicitly configure this change policy.

To configure TopLink to use an `AttributeChangeTrackingPolicy` for EJB 1.n CMP, plain Java objects, or other application servers, use this procedure:

1. Create a descriptor amendment method (see "Configuring Amendment Methods") that sets the change policy as Example 28-21 illustrates.

   Example 28-21 Setting the DeferredChangeDetectionPolicy

       descriptor.setObjectChangePolicy(new AttributeChangeTrackingPolicy());

2. Code each of your persistent classes to implement the `ChangeTracker` interface as Example 28-22 illustrates.

   Example 28-22 Implementing the ChangeTracker Interface for the AttributeChangeTrackingPolicy

       public class Employee implements ChangeTracker {

           PropertyChangeListener listener;

           public PropertyChangeListener getTopLinkPropertyChangeListener() {
             return listener;
           }

           public void setTopLinkPropertyChangeListener(PropertyChangeListener listener) {
             this.listener = listener;
           }
       ...
           public void setId(long id) {
               _id_change(id);
           }

           protected void _id_change(long id) {
               if (listener != null && this.id != id) { // throttle unnecessary events            listener.propertyChange(
                       new PropertyChangeEvent(
                           this,
                           "id",
                           new Long(getId()), // primitives must be wrapped
                           new Long(id)
                      )
                   );
               }
               this.id = id;
           }
       ...
       }