Configuring a Domain Object Method as an Event Handler

You can associate a domain object method with any of the descriptor events shown in Table 28-25. You can register any domain object method that:

Is public.
Returns void.
Takes a single parameter of type DescriptorEvent

Table 28-24 summarizes which descriptors support domain object method event handler configuration.

Table 28-24 Descriptor Support for Domain Object Method Event Handler Configuration

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

For example, you can add a method handlePostDelete (that is public, returns void, and takes a single parameter of type DescriptorEvent) to your Employee object to handle PostDeleteEvent descriptor events. After you register that method with the DescriptorEventManager owned by the Employee object's descriptor as the handler for PostDeleteEvent descriptor events, whenever the Oracle TopLink runtime performs a post-delete operation on an instance of the Employee object, the runtime dispatches a PostDeleteEvent to the handlePostDelete method on the instance of the Employee object associated with that PostDeleteEvent.

The Descriptor Event ID column in Table 28-25 lists the DescriptorEventManager field name used to identify a particular event. The DescriptorEvent method getEventCode returns this value. For example:

if (descriptorEvent.getEventCode() == DescriptorEventManager.PreUpdateEvent) {
    // descriptorEvent represents a pre-update event
}

Table 28-25 Descriptor Events

Category	Descriptor Event ID	Description
Delete	`PreDeleteEvent`	Occurs before an object is deleted from the data source.
	`AboutToDeleteEvent`	Occurs when an object is deleted from the data source.
	`PostDeleteEvent`	Occurs after an object is deleted from the data source.
Insert	`PreInsertEvent`	Occurs before an object is inserted in the data source.
	`AboutToInsertEvent`	Occurs when an object is inserted in the data source.
	`PostInsertEvent`	Occurs after an object is inserted into the data source.
Post-X	`PostBuildEvent`	Occurs after an object is built from the data source.
	`PostCloneEvent`	Occurs after an object has been cloned into a unit of work.
	`PostMergeEvent`	Occurs after an object has been merged from a unit of work.
	`PostRefreshEvent`	Occurs after an object is refreshed from the data source.
Update	`PreUpdateEvent`	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.
	`AboutToUpdateEvent`	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.
	`PostUpdateEvent`	Occurs after an object is updated in the data source.
Write	`PreWriteEvent`	Occurs before an object is inserted or updated in the data source. This occurs before `PreInsertEvent` and `PreUpdateEvent`.
Write	`PostWriteEvent`	Occurs after an object is inserted or updated in the data source. This occurs after `PostInsertEvent` and `PostUpdateEvent`.

Alternatively, you can configure a descriptor event listener as an event handler (see "Configuring a Descriptor Event Listener as an Event Handler").

Using TopLink Workbench

To select event methods, use this procedure:

Select a descriptor in the Navigator. Its properties appear in the Editor.

If the Events advanced property is not visible for the descriptor, then right-click the descriptor and choose Select Advanced Properties > Events from context menu or from the Selected menu.
Click the Event tab in the Editor.

Figure 28-36 Events Tab
Select the appropriate method category from the list on the left.

Use this table to enter data in the following fields to select the appropriate domain object method:

Category	Option	Description
Deleting Methods	Pre	Select the domain object method that is invoked on an instance of its reference class before the instance is deleted from the data source.
Deleting Methods	Post	Select the domain object method that is invoked on an instance of its reference class after the instance is deleted from the data source.
Inserting Methods	Pre	Select the domain object method that is invoked on an instance of its reference class before the instance is inserted in the data source.
	About To	Select the domain object method that is invoked on an instance of its reference class when the instance is inserted in the data source.
	Post	Select the domain object method that is invoked on an instance of its reference class after the instance is inserted into the data source.
Post-X Methods	Build	Select the domain object method that is invoked on an instance of its reference class after the instance is built from the data source.
	Clone	Select the domain object method that is invoked on an instance of its reference class after the instance is cloned into a unit of work.
	Merge	Select the domain object method that is invoked on an instance of its reference class after the instance is merged from a unit of work.
	Refresh	Select the domain object method that is invoked on an instance of its reference class after the instance is refreshed from the data source.
Updating Methods	Pre	Select the domain object method that is invoked on an instance of its reference class before the instance 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.
	About to	Select the domain object method that is invoked on an instance of its reference class when the instance is updated in the data source. This method is called only if the object has changes in the unit of work.
	Post	Select the domain object method that is invoked on an instance of its reference class after the instance is updated in the data source.
Writing Methods	Pre	Select the domain object method that is invoked on an instance of its reference class before the instance is inserted or updated in the data source. Note: This occurs before Pre-Insert and Pre-Update event methods are invoked.
Writing Methods	Post	Select the domain object method that is invoked on an instance of its reference class after the instance is inserted or updated in the data source. Note: This occurs after Post-Insert or Post-Update event methods are invoked.

Using Java

Example 28-15 shows a domain object class with method handlePostDelete defined to handle PostDeleteEvent descriptor events. Example 28-16shows how to register this method as the PostDeleteEvent event handler. Whenever the TopLink runtime performs a post-delete operation on an instance of Employee, the runtime will dispatch a PostDeleteEvent to the DescriptorEventManager owned by the Employee object's descriptor. The DescriptorEventManager will then invoke the handlePostDelete method on the instance of Employee associated with that PostDeleteEvent.

Example 28-15 Domain Object Method as a Descriptor Event Handler

public class Employee {
    // domain object methods
    ...
    public void handlePostDelete(DescriptorEvent event) {
        // handler implementation
    }
}

Example 28-16 Registering a Domain Object Method as a Descriptor Event Handler

employeeDescriptor.getEventManager().setPostDeleteSelector("handlePostDelete");