Skip Headers

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

Previous | Next |

# 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.
`PostDelete` `Event` | Occurs after an object is deleted from the data source.
Insert | `PreInsert` `Event` | Occurs before an object is inserted in the data source.
`AboutToInsert` `Event` | 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 | `PreUpdate` `Event` | 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` `Event` | 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 | `PreWrite` `Event` | Occurs before an object is inserted or updated in the data source. This occurs before `PreInsertEvent` and `PreUpdateEvent`.
`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:

1. 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.

2. Click the Event tab in the Editor.

   Figure 28-36 Events Tab

3. 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.
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.
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");