Configuring a Descriptor Event Listener as an Event Handler

You can create your own DescriptorEventListner and register it with a DescriptorEventManger in a descriptor amendment method. You can also configure a DescriptorEventListner to be notified of events through the Java event model.

You can register any object that implements the DescriptorEventListener interface with the DescriptorEventManager owned by a domain object's descriptor to handle any descriptor event type (see Table 28-27). To quickly implement this interface, you can extend abstract class DescriptorEventAdapter and override only the methods for the events you are interested in.

Table 28-26 summarizes which descriptors support descriptor event listener configuration.

Table 28-26 Descriptor Support for Descriptor Event Listener Configuration

Descriptor	Using TopLink Workbench	Using Java
Relational Descriptors
Object-Relational Descriptors
EIS Descriptors
XML Descriptors

For example, you create a DescriptorEventListener to handle PostBuildEvent descriptor events for Employee objects. After you register this DescriptorEventListener with the DescriptorEventManager owned by the Employee object's descriptor, whenever the TopLink runtime performs a post-build operation on an instance of Employee, the runtime dispatches a PostBuilEvent to the event listener's postBuild method.

Table 28-27 lists the DescriptorEventListener methods associated with each descriptor event. The Descriptor Event Listener Method column lists the DescriptorEventListener methods associated with each DescriptorEvent.

Table 28-27 Descriptor Events

Category	Descriptor Event Listener Method	Description
Delete	preDelete	Occurs before an object is deleted from the data source.
	aboutToDelete	Occurs when an object is deleted from the data source.
	postDelete	Occurs after an object is deleted from the data source.
Insert	preInsert	Occurs before an object is inserted in the data source.
	aboutToInsert	Occurs when an object is inserted in the data source.
	postInsert	Occurs after an object is inserted into the data source.
Post-X	postBuild	Occurs after an object is built from the data source.
	postClone	Occurs after an object has been cloned into a unit of work.
	postMerge	Occurs after an object has been merged from a unit of work.
	postRefresh	Occurs after an object is refreshed from the data source.
Update	preUpdate	Occurs before an object is updated in the data source. This may be called in a unit of work even if the object has no changes and does not require updating.
	aboutToUpdate	Occurs when an object is updated in the data source. This method is called only if the object has changes in the unit of work.
	postUpdate	Occurs after an object is updated in the data source.
Write	preWrite	Occurs before an object is inserted or updated in the data source. This occurs before PreInsertEvent and PreUpdateEvent.
	postWrite	Occurs after an object is inserted or updated in the data source. This occurs after PostInsertEvent and PostUpdateEvent.

Alternatively, you can configure a domain object method as an event handler (see "Configuring a Domain Object Method as an Event Handler").

Using Java

Example 28-17 shows a DescriptorEventListener that handles PostBuildEvent descriptor events. Example 28-18 shows how to register this DescriptorEventListener with the Employee object's descriptor. Whenever the TopLink runtime performs a post-build operation on an instance of Employee, the runtime will dispatch a post build event to the corresponding DescriptorEventListener method on each registered event listener (in this case, it calls the postBuild method).

Example 28-17 DescriptorEventListener

public class MyDescriptorEventListener extends DescriptorEventAdapter {
    public void postBuild(DescriptorEvent event) {
        // handler implementation
    }
}

Example 28-18 Registering a DescriptorEventListener with the DescriptorEventManager

descriptor.getEventManager().addListener(new MyDescriptorEventListener());