Skip Headers

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

Previous | Next |

# 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());