![]() |
![]() |
|
|
Processing Plug-In Events
This section explains how to process plug-in events. It includes the following topics:
Overview of Plug-In Events
An event is an asynchronous notification from another workflow or from an external source, such as another application. You can define an event to start a workflow, initialize variables, activate a node in the workflow, or execute an action. You define events and event properties when defining Start and Event nodes using the WebLogic Integration Studio. For more information about defining events and event properties, refer to Using the WebLogic Integration Studio.
The BPM framework supports event messages in XML format that are delivered via JMS. To support event messages in both XML and non-XML format, you must define a plug-in event.
The following figure illustrates the data flow for plug-in events.
Figure 6-1 Plug-In Event Data Flow
As shown in the previous figure, the plug-in event messages are passed to the system in one of the following two ways:
At run time, the event listener listens for events (via the JMS eventQueue) which are received in XML format and delivered using JMS.
For more information about setting up JMS event listeners for the eventQueue, see Establishing JMS Connections in Programming BPM Client Applications.
At run time, the Plug-in Manager onEvent() method accepts any data format specified by the plug-in.
The WebLogic Integration process engine stores an incoming plug-in event message as a com.bea.wlpi.server.eventprocessor.EventData object, and passes that object to the Event Processor. For more information about the EventData object, see EventData Class.
Upon receipt of an EventData object, the Event Processor first checks to see if the WLPIPlugin property is defined as part of the message.
The WLPIPlugin message property can be defined in either of the following ways:
If the WLPIPlugin property is defined, the Event Processor pre-processes the plug-in event data by passing the EventData object to the plug-in event handler. The pre-processed event data is returned to the Event Processor as an array of EventData objects. For more information about defining the plug-in event handler, see Defining the Plug-In Event Handler.
Next, the Event Processor checks to see if the resulting data is in XML format, and, if so, performs the following steps:
At this time, the Event Processor retrieves the content type and event descriptor supplied by the EventData object.
The content type refers to the MIME (Multi-Purpose Internet Mail Exensions) content type, and describes the basic data type of the message. The content type defaults to text/xml, indicating that the data is in text format and obeys the rules of XML.
The event descriptor provides a precise definition of the data format, and is interpreted in the context of the content type.
For example, if the content type is set to text/xml, the event descriptor is the XML document type. If the DOCTYPE tag is set, the XML document type is the public ID or system ID, if defined, or the document element name. If, on the other hand, the content type is set to application/x-java-object (specifying a serialized Java object), the event descriptor is the fully-qualified Java class name.
An event key specifies the incoming data field that should be treated as the primary key, and is associated with a particular content type and event descriptor. An event key provides a filtering mechanism for incoming event data to improve performance. For more information about defining event keys, see Using the WebLogic Integration Studio.
Note: If a plug-in Event or Start node uses the activateEvent() method or the postStartWatch() method, respectively, to the com.bea.wlpi.server.plugin.EventContext interface, and passes a content type other than text/xml, it is the plug-in's responsibility to ensure that a matching event key expression is registered in the event key table. This can be accomplished using the addEventKey() method to the com.bea.wlpi.server.admin.Admin interface. The plug-in should also provide a plug-in field to evaluate a key value from incoming data of this content type and format. For more information about defining a plug-in field, see Defining the Run-Time Component Class for a Message Type.
For more information about how plug-in events are added as entries to the event watch table, see Defining an Event Watch Entry.
A condition consists of an expression that evaluates to true or false. A condition enables users to define multiple workflows for the same event data that they want to process differently, based on the content of the message. For example, the following provides a valid condition if the event data contains a field called Order Amount: "Order Amount > $500.00". For more information about defining conditions, see Using the WebLogic Integration Studio.
Each of these tasks are performed for each consumer subscribed to the event.
To support plug-in events, you must perform the following steps:
The following sections describe each of these steps in detail, and explain how to send a message to the plug-in event handler.
Before you can create an event handler, you need to understand how to create and access information about the EventData container class, which stores the incoming plug-in event message.
EventData Class
As shown in the figure Plug-In Event Data Flow, the com.bea.wlpi.server.eventprocessor.EventData object provides the container class for incoming data messages.
The following table defines the constructors that can be used to create an EventData object.
Table 6-1 EventData Object Constructors
The following table describes the EventData object information, the constructor parameters used to define the information, and the methods that can be used to access that information after the object is defined, if applicable.
Table 6-2 EventData Object Information
The following table lists the methods that can be used to parse the XML data.
The following section explains how to define the plug-in event handler to pre-process the incoming EventData object.
Defining the Plug-In Event Handler
As shown in the figure Plug-In Event Data Flow, you must define the plug-in event handler to pre-process plug-in event data, and enable the Event Processor to parse the data.
To define the plug-in event handler, you must perform the following tasks.
The following sections describe each of these steps in more detail.
Defining the Event Handler Component Class
To define a plug-in event handler component class, implement the com.bea.wlpi.server.plugin.EventHandler interface.
The following table defines the EventHandler interface method that you must implement to pre-process the incoming plug-in event data.
Table 6-4 EventHandler Interface Method
Creating an Event Handler Value Object
To create an event handler value object, com.bea.wlpi.common.plugin.EventHandlerInfo, use the constructor defined in EventHandlerInfo Object. You must pass the name of the event handler component class, defined in the previous section, as the classNames constructor parameter value.
For example, the following code excerpt creates a new event handler value object, passing the name of the event handler class, sample.MyEventHandler. The event handler class implements the EventHandler com.bea.wlpi.server.plugin.EventHandler interface, as described in Defining the Event Handler Component Class.
eh = new EventHandlerInfo(SamplePluginConstants.PLUGIN_NAME,
bundle.getString("startOrderName"),
bundle.getString("startOrderDesc")
sample.MyEventHandler);
eventHandler = new EventHandlerInfo[]{ eh };
For more information about the EventHandlerInfo object, see EventHandlerInfo Object.
Registering an Event Handler
To register the event handler, create a com.bea.wlpi.common.plugin.PluginCapabilitiesInfo value object, as defined in PluginCapabilitiesInfo Object, and pass the EventHandlerInfo object (defined in the previous section) as the eventHandler constructor parameter value.
For example, the following code excerpt creates a new PluginCapabilitiesInfo value object, passing the name of the com.bea.wlpi.common.plugin.EventHandlerInfo object as an argument.
PluginCapabilitiesInfo pci = new PluginCapabilitiesInfo(pi,
getCategoryInfo(bundle), eventInfo, fieldInfo, functionInfo,
startInfo, null, null, null, null, eventHandler);
For more information about the PluginCapabilitiesInfo object, see PluginCapabilitiesInfo Object.
Defining Plug-In Message Types
You must define plug-in message types, or plug-in fields, to enable the process engine to extract information from the plug-in com.bea.wlpi.server.eventprocessor.EventData objects. The extracted values can be assigned to workflow variables or used as part of an expression, such as in key value or conditional expressions.
For more information about defining plug-in message types, see Defining the Run-Time Component Class for a Message Type.
Defining an Event Watch Entry
An event watch entry enables the Event Processor to match an incoming event to the plug-in node.
The following table describes how the process engine adds plug-in event entries to the event watch table for each plug-in node type.
Table 6-5 How Event Watch Entries Are Added Based on Plug-In Node Type
Sending an Event to the Plug-In Event Handler
To send an event to the plug-in event handler, the message sender must set the com.bea.wlpi.server.eventprocessor.EventData object WLPIPlugin string property to the event handler name.
For example, the following code segment demonstrates how to build a properties map, setting the WLPIPlugin property to the name of the event handler, SamplePlugin, and passing this information to the EventData constructor.
Map props = new HashMap();
props.put("WLPIPlugin","SamplePlugin");
EventData eventData = new EventData(data,
"text/x-appplication/sample",
"Order", 0, null, null, props);
![]() |
![]() |
![]() |
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|