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);
      .
      .
    }