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;
       }
   ...
   }