bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Programming BPM Plug-Ins

Using Plug-In Notifications

This section explains how to use plug-in notifications. It includes the following topics:

- Overview

- Registering the Plug-In as a Notification Listener

- Getting Information About a Received Notification

- Unregistering the Plug-In as a Notification Listener

Overview

BPM communicates with plug-ins by broadcasting notifications. A notification is a message that the WebLogic Integration process engine sends to a plug-in, indicating that an event has occurred, as illustrated in the following figure.

Figure 5-1 Notification Sent by WebLogic Integration Process Engine to Plug-In

You can register a plug-in as a notification listener to receive up to four types of notifications, provided as part of the com.bea.wlpi.server.plugin package.

Note: To minimize the impact on performance, only register a plug-in for notifications that it absolutely needs to receive. In particular, use caution when registering to receive run-time instance and task notifications.

The following table defines:

- Four types of notifications

- Related events that cause a notification to be sent

- Integer values in the com.bea.wlpi.common.plugin.PluginConstants interface that correspond to each event. You can specify these values when registering the plug-in as a notification listener, as described in Registering the Plug-In as a Notification Listener.

Table 5-1 Notification Types and Related Events

Notification Type | Description | Related Events | PluginConstants Value
--- | --- | --- | ---
InstanceNotification | Workflow instance notification | Workflow instance is aborted | INSTANCE_ABORTED
Workflow instance is completed | INSTANCE_COMPLETED
Workflow instance is created | INSTANCE_CREATED
Workflow instance is deleted | INSTANCE_DELETED
Workflow instance is updated | INSTANCE_UPDATED
TaskNotification | Task notification | Task is assigned | TASK_ASSIGNED
Task is completed | TASK_COMPLETED
Task is executed | TASK_EXECUTED
Task is overdue | TASK_OVERDUE
Task is started | TASK_STARTED
Task is unassigned | TASK_UNASSIGNED
Task is unmarked as done | TASK_UNMARKED_DONE
Task is updated | TASK_UPDATED
TemplateDefinitionNotification | Template definition notification | Template definition is created | DEFINITION_CREATED
Template definition is deleted | DEFINITION_DELETED
Template definition is updated | DEFINITION_UPDATED
TemplateNotification | Template notification | Template is created | TEMPLATE_CREATED
Template is deleted | TEMPLATE_DELETED
Template is updated | TEMPLATE_UPDATED

The following sections describe how to register and unregister the plug-in as a notification listener, and get information about a received notification.

Registering the Plug-In as a Notification Listener

Typically, the plug-in should register itself as a notification listener at load time. For example, when implementing the load() method, as described in Lifecycle Management Methods, you should register the plug-in as a notification listener, if necessary.

To register the plug-in as a notification listener, use one (or more) of the com.bea.wlpi.server.plugin.PluginManager methods defined in the following table, based on the type of notifications that you want the plug-in to receive.

Note: For information about connecting to the Plug-in Manager, see Connecting to the Plug-In Manager.

Table 5-2 Plug-In Notification Registration Methods

To register the plug-in as . . . | Use the following method . . .
--- | ---
InstanceNotification listener | public void addInstanceListener( com.bea.wlpi.server.plugin.Plugin plugin, int mask) throws java.rmi.RemoteException
TaskNotification listener | public void addTaskListener( com.bea.wlpi.server.plugin.Plugin plugin, int mask) throws java.rmi.RemoteException
TemplateDefinitionNotification listener | public void addTemplateDefinitionListener( com.bea.wlpi.server.plugin.Plugin plugin, int mask) throws java.rmi.RemoteException
TemplateNotification listener | public void addTemplateListener( com.bea.wlpi.server.plugin.Plugin plugin, int mask) throws java.rmi.RemoteException

The following table defines the parameters for which you must specify values for the plug-in notification registration method.

Table 5-3 Plug-In Notification Registration Method Parameters

Parameter | Description
--- | ---
plugin | EJBObject implementing the plug-in remote interface.
mask | Integer bitmask specifying the events for which you want to register. For a list of valid values, see the notification com.bea.wlpi.common.plugin.PluginConstants values defined in the table Notification Types and Related Events. The mask value can also be set to EVENT_NOTIFICATION_ALL or EVENT_NOTIFICATION_NONE to globally register or unregister, respectively, all events in a particular category. This value is formed by performing a bitwise OR of the required event constants.

For more information about notification listener registration methods, see the com.bea.wlpi.server.plugin.PluginManagerCfg Javadoc.

The following code listing is an excerpt from the plug-in sample that shows how to register the plug-in as a notification listener for all notification types and all of their related events. This excerpt is taken from the SamplePluginBean.java file in the SAMPLES_HOME/integration/samples/bpm_api/plugin/src/com/bea/wlpi/tour/po/plugin directory. Notable lines of code are shown in bold.

Listing 5-1 Registering the Plug-In as a Notification Listener

>           .
>           .
>           .
>     public void load(PluginObject pluginData) throws PluginException {
>           .
>           .
>           .
>        pm.addInstanceListener(plugin, PluginConstants.EVENT_NOTIFICATION_ALL);
>        pm.addTaskListener(plugin, PluginConstants.EVENT_NOTIFICATION_ALL);
>        pm.addTemplateDefinitionListener(plugin,
>           PluginConstants.EVENT_NOTIFICATION_ALL);
>        pm.addTemplateListener(plugin, PluginConstants.EVENT_NOTIFICATION_ALL);
>           .
>           .
>           .
>         }

For more information about the plug-in sample, see BPM Plug-In Sample.

Getting Information About a Received Notification

Once a notification is received, you can get information about it, including its source.

The following table defines methods available for getting information about any received notification. These methods can be accessed via the com.bea.wlpi.server.plugin.PluginNotification class which all notification types extend.

Table 5-4 General Plug-In Notification Information Methods

Method | Description
--- | ---
public int getEventType() | Gets the event type. This method returns a com.bea.wlpi.common.plugin.PluginConstants interface integer value corresponding to the related event, as defined in the table Notification Types and Related Events.
public java.lang.Object getSource() | Gets the workflow entity object that has changed. This method returns a java.lang.Object object specifying the workflow entity that has changed, and can be any of the following com.bea.wlpi.common.plugin value objects: InstanceInfo, TaskInfo, TemplateDefinitionInfo, or TemplateInfo. For information about the methods available for getting information about each value object, see Plug-In Value Object Summary.

For more information about these methods, see the com.bea.wlpi.server.plugin.PluginNotification Javadoc.

In addition, the following table defines the methods that are available to each notification type to obtain addition information about the source component that has changed.

Table 5-5 Plug-In Notification Information Methods Based on Notification Type

Notification Type

Method

Description

InstanceNotification

public com.bea.wlpi.common.InstanceInfo getInstance()

Gets information about the workflow instance that has changed.

This method returns a com.bea.wlpi.common.InstanceInfo object. To access information about the workflow instance, use the InstanceInfo object methods described in "InstanceInfo Object" in Value Object Summary in Programming BPM Client Applications.

TaskNotification

public com.bea.wlpi.common.TaskInfo getTask()

Gets information about the task that has changed.

This method returns a com.bea.wlpi.common.TaskInfo object. To access information about the task, use the TaskInfo object methods described in "TaskInfo Object" in Value Object Summary in Programming BPM Client Applications.

TemplateDefinitionNotification

public com.bea.wlpi.common.TemplateDefinitionInfo getTemplateDefinition()

Gets information about the template definition that has changed.

This method returns a com.bea.wlpi.common.TemplateDefinitionInfo object. To access information about the template definition, use the TemplateDefinitionInfo object methods described in "TemplateDefinitionInfo Object" in Value Object Summary in Programming BPM Client Applications.

TemplateNotification

public com.bea.wlpi.common.TemplateInfo getTemplate()

Gets information about the template that has changed.

This method returns a com.bea.wlpi.common.TemplateInfo object. To access information about the template, use the TemplateInfo object methods described in "TemplateInfo Object" in Value Object Summary in Programming BPM Client Applications.

Unregistering the Plug-In as a Notification Listener

Typically, the plug-in should unregister itself as a notification listener at unload time. For example, when implementing the unload() method, as described in Lifecycle Management Methods, you should unload the plug-in as a notification listener, if necessary.

To unregister the plug-in as a notification listener, use one (or more) of the com.bea.wlpi.server.plugin.PluginManager methods defined in the following table, based on the type of notification listener that you want to remove.

Note: For information about connecting to the Plug-in Manager, see Connecting to the Plug-In Manager.

Table 5-6 Plug-In Notification Unregistration Methods

To unregister the plug-in as . . . | Use the following method . . .
--- | ---
InstanceNotification listener | public void removeInstanceListener( com.bea.wlpi.server.plugin.Plugin plugin) throws java.rmi.RemoteException
TaskNotification listener | public void removeTaskListener( com.bea.wlpi.server.plugin.Plugin plugin) throws java.rmi.RemoteException
TemplateDefinitionNotification listener | public void removeTemplateDefinitionListener( com.bea.wlpi.server.plugin.Plugin plugin) throws java.rmi.RemoteException
TemplateNotification listener | public void removeTemplateListener( com.bea.wlpi.server.plugin.Plugin plugin) throws java.rmi.RemoteException

In each case, you must specify a com.bea.wlpi.server.plugin.Plugin object that identifies the plug-in that you are unregistering as a notification listener.

The following code listing shows how to unregister the plug-in as a notification listener for all notification types and all of their related events. Notable lines of code are shown in bold.

Listing 5-2 Unregistering the Plug-In as a Notification Listener

>     public void unload() throws PluginException {
>           .
>           .
>           .
>        pm.removeInstanceListener(plugin);
>        pm.removeTaskListener(plugin);
>        pm.removeTemplateDefinitionListener(plugin);
>        pm.removeTemplateListener(plugin);
>           .
>           .
>         }