Working with Events

Use the event manager to specify specific events to occur whenever OracleAS TopLink performs a read, update, delete, or insert on the database.

Note: OracleAS TopLink uses the Java event model.

Applications can receive descriptor events in the following ways:

• Implement the DescriptorEventListener interface

• Subclass the DescriptorEventAdapter adapter class

• Register an event method with a descriptor

Objects that implement the DescriptorEventListener interface can be registered with the descriptor event manager to be notified when any event occurs for that descriptor.

Alternately, you may wish to use the DescriptorEventAdapter class if your application does not require all the methods defined in the interface. The DescriptorEventAdapter implements the DescriptorEventListener interface and defines an empty method for each method in the interface. To use the adapter, first subclass it, then register your new object with the descriptor event manager.

You can use descriptor events in many ways, including:

• Synchronizing the persistent objects with other systems, services and frameworks

• Maintaining non-persistent attributes of which OracleAS TopLink is not aware

• Notifying other parts of the application when the persistent state of objects is changed

• Performing complex mappings or optimizations not directly supported by OracleAS TopLink mappings

Use the descriptor's Event tab (see Figure 4–18) to specify events for a descriptor.

Example 4-5 Event Example

To invoke a method called postBuild() for an Employee object, the postBuild() method must be implemented in the Employee class. This method must also accept one parameter that is an instance of DescriptorEvent fully qualified with a package name.

Registering an Event with a Descriptor

A persistent class can register a public method as an event method. A descriptor calls the event method when a particular database operation occurs.

Event methods:

• Must be public so that OracleAS TopLink can call them

• Must return void

• Must take a DescriptorEvent as a parameter

Registering an Event

The following code illustrates an event method definition:

public void myEventHandler(DescriptorEvent event);

Supported Events

Events the DescriptorEventManager supports include:

Post-X Methods:  

• Post-Build — occurs after an object is built from the database.

• Post-Clone — occurs after an object has been cloned into a unit of work.

• Post-Merge — occurs after an object has been merged from a unit of work.

• Post-Refresh — occurs after an object is refreshed from the database.

Updating Methods:  

• Pre-Update — occurs before an object is updated in the database. This may be called in a unit of work even if the object has no changes and does not require an update.

• About-to-Update — occurs when an object's row is updated in the database. This is called only if the object has changes in the unit of work.

• Post-Update — occurs after an object is updated in the database. This may be called in a unit of work even if the object has no changes and does not require an update.

Inserting Methods:  

• Pre-Insert — occurs before an object is inserted in the database.

• About-to-Insert — occurs when an object's row is inserted in the data­base.

• Post-Insert — occurs after an object is inserted in the database.

Writing Methods:  

• Pre-Write — occurs before an object is inserted or updated in the database. This occurs before Pre-Insert/Update.

• Post-Write — occurs after an object is inserted or updated in the database. This occurs after Pre-Insert/Update.

Deleting Methods:  

• Pre-Delete — occurs before an object is deleted from the database.

• Post-Delete — occurs after an object is deleted from the database.