42 Using Business Events and the Event Delivery Network
This chapter includes the following sections:
-
Subscribing to or Publishing a Business Event from an Oracle Mediator Service Component
-
Subscribing to or Publishing a Business Event from a BPEL Process Service Component
-
How to Integrate Oracle ADF Business Component Business Events with Oracle Mediator
For information about creating composite sensors on service components that subscribe to business events, see Defining Composite Sensors.
For information about troubleshooting business events, including specifying the number of threads, stopping event delivery, and specifying the maximum number of deliveries, see Troubleshooting Oracle SOA Suite and Oracle BPM Suite in Administering Oracle SOA Suite and Oracle Business Process Management Suite.
For information about managing business events from Oracle Enterprise Manager Fusion Middleware Control, see Managing Business Events in Administering Oracle SOA Suite and Oracle Business Process Management Suite.
42.1 Introduction to Business Events
You can raise business events when a situation of interest occurs. For example, in a loan flow scenario, a BPEL process service component executing a loan process can raise a loan completed event at the completion of the process. Other systems within the infrastructure of this application can listen for these events and, upon receipt of one instance of an event:
-
Use the event context to derive business intelligence or dashboard data.
-
Signal to a mail department that a loan package must be sent to a customer.
-
Invoke another business process.
-
Send information to Oracle Business Activity Monitoring (BAM).
Business events are typically a one-way, fire-and-forget, asynchronous way to send a notification of a business occurrence. The business process does not:
-
Rely on any service component receiving the business event to complete.
-
Care if any other service components receive the business event.
-
Need to know where subscribers (if any) are and what they do with the data.
These are important distinctions between business events and direct service invocations that rely on the Web Services Description Language (WSDL) file contract (for example, a SOAP service client). If the author of the event depends on the receiver of the event, then messaging typically must be accomplished through service invocation rather than through a business event. Unlike direct service invocation, the business event separates the client from the server.
A business event is defined using the event definition language (EDL). The EDL is a schema used to build business event definitions. Applications work with instances of the business event definition.
The EDL consists of the following:
-
Defined events
One or more event definitions (
event-definition
element) with the same namespace (targetNamespace
attribute ofdefinitions
root element), each having a local name (name
attribute of theevent-definition
element). The namespace and local name constitute an event name (QName
). -
Payload definition
The most common use for a definition is an XML Schema (XSD). The payload of a business event is defined in an XSD that is imported (through the
schema-import
element) into the EDL. Each defined event (that is,event-definition
element) can have a reference to an imported payload XSD element (theelement
attribute of thecontent
element). The schema URI is contained in the root element of the payload.
The following example shows an EDL file with two business events in the BugReport
event definition: bugUpdated
and bugCreated
. The namespace (/model/events/edl/BugReport
) and associated schema file (BugReport.xsd
) are referenced.
<?xml version = '1.0' encoding = 'UTF-8'?> <definitions targetNamespace="/model/events/edl/BugReport" xmlns:ns0="/model/events/schema/BugReport" xmlns="http://schemas.oracle.com/events/edl"> <schema-import namespace="/model/events/schema/BugReport" location="BugReport.xsd"/> <event-definition name="bugCreated"> <content element="ns0:bugCreatedInfo"/> </event-definition> <event-definition name="bugUpdated"> <content element="ns0:bugUpdatedInfo"/> </event-definition> </definitions>
These two events are available for subscription in Oracle Mediator and a BPEL process.
Business events are deployed to the Oracle Metadata Services Repository (MDS Repository). Deploying a business event to the MDS Repository along with its artifacts (for example, the XSDs) is known as publishing the EDL (or event definition). This action transfers the EDL and its artifacts to a shared area in the MDS Repository. An object in an MDS Repository shared area is visible to all applications in the Resources window of Oracle JDeveloper. After an EDL is published, it can be subscribed to by SOA components such as Oracle Mediator or a BPEL process.
A subscription is for a specific qualified name (QName) (for example, x.y.z/newOrders
). A QName is a tuple (URI
, localName
) that may be derived from a string prefix:localName
with a namespace declaration such as xmlns:prefix=URI
or a namespace context. In addition, subscriptions can be further narrowed down by using content-based filters.
Business events are published to the EDN. The EDN runs within every Oracle SOA Suite instance. Raised events are delivered by EDN to the subscribing service components. Oracle Mediator service components and BPEL process service components can subscribe to and publish events.
The EDN is based on a standard JMS messaging infrastructure that supports business event-based interactions among Oracle SOA Suite components and non-Oracle SOA Suite components. The EDN provides two JMS-based types:
-
Oracle WebLogic Server JMS: By default, all business events use a single, default Oracle WebLogic Server JMS topic.
-
Oracle Advanced Queueing (AQ) JMS
You can create additional JMS topics (Oracle WebLogic Server JMS or AQ JMS) and map different event types to these additional JMS topics in Oracle Enterprise Manager Fusion Middleware Control.
42.1.1 EDN Integration with Oracle SOA Suite
Oracle SOA Suite EDN provides the following features:
-
A standard JMS-based messaging infrastructure that provides the following:
-
A JMS-based event publish and subscribe architecture for Oracle SOA Suite and non-Oracle SOA Suite clients.
-
Support for bidirectional interactions (can both publish to and subscribe from Oracle SOA Suite and non-Oracle SOA Suite clients).
-
Support for both the Oracle AQ JMS and Oracle WebLogic Server JMS providers. An Oracle WebLogic Server JMS topic (default) and an AQ JMS topic are automatically configured for EDN use after installation. The default JMS type can be switched from Oracle WebLogic Server JMS (default) to AQ JMS in Oracle Enterprise Manager Fusion Middleware Control. For more information, see "Mapping Business Events to JMS Topic Destinations on the Business Events Page" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
-
EDN support as a lightweight manager above both JMS providers.
-
A plain JMS API and an Oracle SOA Suite, value-added EDN API for remote, non-Oracle SOA Suite clients to use for integrating with Oracle SOA Suite. For more information, see Java API Reference for Oracle SOA Suite Event Delivery Network.
-
JMS transactions to guarantee EDN delivery (for both the one-and-only-one (OAOO) and guaranteed consistency methods).
-
Durable and persistent publishing delivery options to prevent message loss. These default options are beneficial for interactions with remote, non-Oracle SOA Suite clients.
-
A JMS adapter used internally for implementing many JMS features. For information about the JMS adapter, see the "Oracle JCA Adapter for JMS" chapter of Understanding Technology Adapters.
-
No duplicate event processing in a multinode cluster.
-
-
Scalability at a fine-grained level. This enables different events to map to different JMS topic destinations, thereby eliminating the need for a single location to handle all events. This reduces potential bottlenecks. Mapping is performed by an administrator in Oracle Enterprise Manager Fusion Middleware Control. For more information, see the "Mapping Business Events to JMS Topic Destinations" section of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
-
Support for the following publish and subscribe scenarios:
-
Publish and subscribe to events across the same composite or different composites.
-
Use the default EDN Oracle WebLogic Server JMS topic automatically provided.
-
Use the custom event-to-JMS-topic mapping provided in Oracle Enterprise Manager Fusion Middleware Control.
-
-
Publish and subscribe to events with remote, non-Oracle SOA Suite participants through one of the following APIs:
-
Plain JMS API (for J2SE client environments)
-
EDI API
EdnJmsConnection
(for J2SE and J2EE client environments)
-
-
-
Instance tracking and fault recovery support in the Error Hospital. For more information, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.
-
The storage of EDL files in the MDS Repository. This makes the files available for browsing in the Resources window in Oracle JDeveloper. For more information, see Managing Shared Data with the Design-Time .
Note:
For memory recommendations on sending large payloads in the event delivery network (EDN) with Oracle AQ JMS, see JVM Memory Sizing Recommendations for SOA Composite Applications.
42.1.2 Business Event API Support for Remote Clients
For remote clients to publish and subscribe to events in Oracle SOA Suite, there are several API options. Table 42-1 provides details.
Table 42-1 Remote API Options
Option | Description | Supported By | Advantages/Disadvantages |
---|---|---|---|
Plain JMS API |
Use to directly interact with EDN JMS topics. This is typically a J2SE client with raw JMS access. The remote client must configure JNDI properties to point to the SOA server. |
|
The advantages are:
The disadvantages are:
|
EDN API - |
For a J2SE client, such as Oracle Event Processing. This option provides all standard publish and subscribe options. The remote client must perform the following tasks:
|
|
The advantages are:
The disadvantages are:
For information about the JMS adapter, see the "Oracle JCA Adapter for JMS" chapter of Understanding Technology Adapters. |
For more information about the EDN APIs, see Java API Reference for Oracle SOA Suite Event Delivery Network.
42.1.2.1 Guidelines for Manually Setting Event Delivery Network Properties When Invoking the BusinessEvent.setProperty API
When publishing an event delivery network (EDN) business event, most properties cannot be manually set by invoking the BusinessEvent.setProperty(String name, Object value)
API.
42.1.2.1.1 Properties That Cannot Be Manually Set
Do not set the following EDN business event properties. The values for these properties are internally set and used by EDN.
-
General properties:
-
BusinessEvent.EVENT_ID ("id")
-
BusinessEvent.PARENT_ID ("parent-id")
-
BusinessEvent.PUBLISHED_TIME ("published-time")
-
BusinessEvent.OWNER ("owner")
-
BusinessEvent.SOURCE ("source")
-
BusinessEvent.MODE ("mode")
-
-
All tracking properties, for example:
-
BusinessEvent.PROPERTY_ECID ("tracking.ecid")
-
BusinessEvent.PROPERTY_COMPOSITE_INSTANCE_ID ("tracking.compositeInstanceId")
-
BusinessEvent.PROPERTY_PARENT_COMPONENT_INSTANCE_ID ("tracking.parentComponentInstanceId")
-
BusinessEvent.PROPERTY_CONVERSATION_ID ("tracking.conversationId")
-
tracking.compositeInstanceCreatedTime"
-
42.1.3 Local and Remote Event Connections
A single SOA composite application instance can reside in a single container or can be clustered across multiple containers. Another application (for example, an Oracle Application Development Framework (ADF) Business Component application) can be configured to run in the same container as the SOA composite application instance or in a different container.
Raising an event from a Java EE application can be done through a local event connection or a remote event connection:
-
Local event connection
If the publisher resides on the same Oracle WebLogic Server as the application and the publisher uses a local business event connection factory, the event is raised through a local event connection.
-
Remote event connection
If the caller resides in a different container (different JVM) then the application, the event is raised through a remote event connection.
If another application (for example, an Oracle ADF Business Component application) is configured to run in the same container as the SOA composite application, it is optimized to use local event connections.
42.2 Creating Business Events in Oracle JDeveloper
This section provides a high-level overview of how to create and subscribe to a business event.
42.2.1 How to Create a Business Event
To create a business event:
-
Create a SOA project as an empty composite.
-
Launch the Create Event Definition wizard in either of the following ways:
-
From the File main menu, select New > Event Definition.
-
From the File main menu, select New > Application > SOA Tier > Service Components > Event Definition.
The Create Event Definition dialog appears.
-
-
Enter the details described in Table 42-2.
Table 42-2 Create Event Definition Dialog Fields and Values
Field Value Name
Enter a name or accept the default name of
EventDefinition
number
. The name you enter here becomes the EDL file name in the Applications window.Note: Do not enter a forward slash (
/
) as the event name. This creates an event definition file consisting of only an extension for a name (.edn
).Directory
Displays the directory path in which to create the event definition file.
Namespace
Accept the default namespace or enter a value for the namespace in which to place the event. This enables the subscriber to receives events of the indicated namespace.
-
Click the Add icon to add an event.
The Create Event dialog appears.
-
Click the Search icon to select the payload, and click OK. Figure 42-1 provides details.
You are returned to the Create Event dialog.
-
In the Name field, enter a name.
-
Click OK.
The added event now appears in the Events section. Figure 42-2 provides details.
-
Above the editor, click the cross icon (x) next to
event_definition_name
.edl
to close the editor. -
Click Yes when prompted to save your changes. If you do not save your changes, the event is not created and cannot be selected in the Event Chooser window.
The business event is published to the MDS Repository and you are returned to the SOA Composite Editor. The business event displays for browsing in the Resources window.
42.3 Subscribing to or Publishing a Business Event from an Oracle Mediator Service Component
This section describes how to subscribe to a business event or publish a business event from an Oracle Mediator service component.
42.3.2 How to Publish a Business Event
You can create a second Oracle Mediator to publish the event that you subscribed to in How to Subscribe to a Business Event. While not shown here, you can also create a BPEL component to publish the event.
To publish a business event:
- Create a second Oracle Mediator service component that publishes the event to which the first Oracle Mediator subscribes.
- Return to the first Oracle Mediator service component.
- In the Routing Rules section, click the Add icon.
- Click Service when prompted by the Target Type window.
- Select the second Oracle Mediator service component.
- From the File main menu, select Save All.
42.3.3 What Happens When You Create and Subscribe to a Business Event
The source code in the following example provides details about the subscribed event of the Oracle Mediator service component.
<component name="OrderPendingEvent"> <implementation.mediator src="OrderPendingEvent.mplan"/> <business-events> <subscribe xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO" name="sub1:NewOrderSubmitted" consistency="oneAndOnlyOne" durable="true" runAsRoles="$publisher"/> </business-events> </component>
While not explicitly demonstrated in this example, you can define XPath filters on events. In the following example, the event is accepted for delivery only if the initial deposit is greater than 50000
:
<business-events>
. . .
. . .
<filter>
<xpath xmlns:be="http://oracle.com/fabric/businessEvent"
xmlns:ns1="http://xmlns.oracle.com/singleString"
<xpath expression= "/be:business-event/be:content/
sub1:AccountInfo/Details[@initialDeposit > 50000]" />
</filter>
. . .
. . .
</business-events>
42.3.4 What Happens When You Publish a Business Event
Two Oracle Mediator service components appear in the following example. One service component (OrderPendingEvent
) subscribes to the event and the other service component (PublishOrderPendingEvent
) publishes the event.
<component name="PublishOrderPendingEvent"> <implementation.mediator src="PublishOrderPendingEvent.mplan"/> <business-events> <publishes xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO" name="pub1:NewOrderSubmitted" persistent="true" priority="7" timeToLive="36000000"/> </business-events> </component> <component name="OrderPendingEvent"> <implementation.mediator src="OrderPendingEvent.mplan"/> <business-events> <subscribe xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO" name="sub1:NewOrderSubmitted" consistency="oneAndOnlyOne" durable="true" runAsRoles="$publisher"/> </business-events> </component>
42.3.5 What You May Need to Know About Subscribing to a Business Event
Only subscribers in default revisions of the SOA composite applications can receive business events. For example, note the following behavior.
To subscribe to a business event:
42.3.6 What You May Need to Know About Publishing Events Across Domains Using SAF
When publishing events across domains using Store-and-Forward (SAF), local subscribers cannot subscribe to the event. For example, assume you have the following subscribers:
-
Local subscriber (deployed on the same domain as the event publisher)
-
Remote subscriber (deployed on a domain external to the event publisher)
Both subscribe to the same event (for this example, named E), which has been configured to listen to the SAF topic. In this environment, only the remote subscriber can subscribe to the event. The local subscriber cannot subscribe to the event.
The JMS topic for EDN must be provisioned as a physical JMS topic instead of as an imported SAF topic. This is because an imported SAF topic has its own rules of context lookup and security checking that EDN does not natively support.
42.3.6.1 Workaround for Local Subscribers
As a workaround, you must perform the following procedures:
-
Create a local JMS topic that the publisher can locate. For example, in local domain A, which the event publisher can locate, you provision a regular Oracle WebLogic Server JMS topic (for example, named Ta) to which to publish events, and a subscriber (local in domain A) to listen for this topic.
-
In remote domain B, which a remote subscriber can locate, you create an imported SAF topic (for example, named safTb) that maps to topic Ta from domain A, and have the remote subscriber listen to safTb.
As an alternative to Step 2, you can provision another JMS topic (for example, named Tb) in domain B to which a remote subscriber listens, and create a JMS bridge that bridges source topic Ta to destination topic Tb.
42.3.7 How to Configure a Foreign JNDI Provider to Enable Administration Server Applications to Publish Events to the SOA Server
This section describes how to configure a foreign JNDI provider when the publishing application (for example, an ADF EAR file) is deployed on the administration server instead of the SOA server.
To configure a foreign JNDI provider to enable administration server applications to publish events to the SOA Server:
42.3.8 How to Configure the Connection Factory When the Oracle WebLogic Server JMS Runs in the Same Local JVM as the JMS Adapter
If Oracle WebLogic Server JMS is running in the local JVM (the same JVM as the JMS adapter), you must correctly configure the isTransacted
connector factory property. For your servlet client, which is locally colocated with the Oracle WebLogic Server JMS server to work, perform the following steps:
42.4 Subscribing to or Publishing a Business Event from a BPEL Process Service Component
This section describes how to subscribe to a business event or publish a business event from a BPEL process service component.
42.4.3 What Happens When You Subscribe to and Publish a Business Event
The source code in the following example shows how the composite.xml
source changes for the subscribed and published events of a BPEL process service component.
<component name="EventBPELProcess"> <implementation.bpel src="EventBPELProcess.bpel"/> <property name="configuration.monitorLocation" type="xs:string" many="false">EventBPELProcess.monitor</property> <business-events> <subscribe xmlns:sub1="http://mycompany.com/events/orders" name="sub1:OrderReceivedEvent" consistency="oneAndOnlyOne" durable="true" runAsRoles="$publisher"/> <publishes xmlns:pub1="http://mycompany.com/events/orders" name="pub1:ProductSoldAlert" persistent="true" priority="7" timeToLive="36000000"/>/> </business-events> </component> <business-events> <publishes xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO" name="pub1:NewOrderSubmitted" persistent="true" priority="7" timeToLive="36000000"/> </business-events> </component>
While not explicitly demonstrated in this example, you can define XPath filters on events. A filter is typically present in event subscriptions. The subscribe
element limits the type of event to which this service component is subscribed, and the filter
section further limits the event to specific content in which the component is interested. In the following example, the event is accepted for delivery only if the initial deposit is greater than 50000
.
<business-events>
. . .
. . .
<filter>
<xpath xmlns:be="http://oracle.com/fabric/businessEvent"
xmlns:ns1="http://xmlns.oracle.com/singleString"
<xpath expression= "/be:business-event/be:content/
sub1:AccountInfo/Details[@initialDeposit > 50000]" />
</filter>
. . .
. . .
</business-events>
The standard BPEL activities such as receive, invoke, onMessage, and onEvent (in BPEL 2.0) are extended with an extra attribute bpelx:eventName
, so that the BPEL process service component can receive events from the EDN event bus. The schema for the eventName
attribute is shown in the following example:
<xs:attribute name="eventName" type="xs:QName"> <xs:annotation> <xs:appinfo> <tns:parent> <bpel11:onMessage/> <bpel11:receive/> <bpel11:invoke/> </tns:parent> </xs:appinfo> </xs:annotation> </xs:attribute>
The following example shows how the eventName
attribute is used in the BPEL source file:
<receive name="OrderPendingEvent" createInstance="yes" bpelx:eventName="ns1:OrderReceivedEvent"/> <invoke name="Invoke_1" bpelx:eventName="ns1:ProductSoldAlert"/>
If the bpelx:eventName
attribute is used in a receive, invoke, onMessage, or onEvent (in BPEL 2.0) activity, then the standard attributes such as partnerLink
, operation
, or portType
are not present. This is because the existence of the bpelx:eventName
attribute shows that the activity is only interested in receiving events from the EDN event bus or publishing events to the EDN event bus.
The XSD file for the BPEL process service component is slightly modified, so that the partnerLink
, operation
, and portType
attributes are no longer mandatory. The Oracle JDeveloper validation logic enforces the presence of either the bpelx:eventName
attribute or the partnerLink
, operation
, and portType
attributes, but not both. The following example shows the modified schema definition of a BPEL receive activity:
<complexType name="tReceive"> <complexContent> <extension base="bpws:tExtensibleElements"> <sequence> <element name="correlations" type="bpws:tCorrelations" minOccurs="0"/> <group ref="bpws:activity"/> </sequence> <!- BPEL mandatory attributes relaxed to optional for supporting BPEL-EDN -> <attribute name="partnerLink" type="NCName" use="optional"/> <attribute name="portType" type="QName" use="optional"/> <attribute name="operation" type="NCName" use="optional"/> <attribute name="variable" type="NCName" use="optional"/> </extension> </complexContent> </complexType>
The schema definition for the invoke and onMessage activities are modified similarly.
42.5 How to Integrate Oracle ADF Business Component Business Events with Oracle Mediator
This section provides a high-level overview of how to integrate Oracle ADF Business Component event conditions with SOA components. The SOA components include Oracle Mediator service components and BPEL process service components.
To integrate Oracle ADF Business Component business events with SOA components: