44 Using Business Events and the Event Delivery Network

This chapter describes how to publish and subscribe to business events in a SOA composite application. Business events consist of message data sent as the result of an occurrence in a business environment. When a business event is published, other service components can subscribe to it.

This chapter includes the following sections:

Section 44.1, "Introduction to Business Events"
Section 44.2, "Creating Business Events in Oracle JDeveloper"

For samples that show how to use business events with Oracle Mediator, visit the following URL:

http://www.oracle.com/technology/sample_code/products/mediator

For additional information on creating business events in a SOA composite application, see Oracle Fusion Middleware Tutorial for Running and Building an Application with Oracle SOA Suite.

44.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 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). EDL is a schema used to build business event definitions. Applications work with instances of the business event definition.

EDL consists of the following:

Global name

Typically a Java package name (for example, com.acme.ExpenseReport.created), though this is not required.
Custom headers

Used for fast routing. For example, if an event named Expense Report Created has a Currency header, the component that creates the event at runtime is responsible for populating the Currency header. The event can be routed based on the value of the header more quickly than doing an XPath query into the event payload.
Payload definition

The most common use for a definition is an XML Schema (XSD). The payload of a business event is defined using an XSD. The schema URI is contained in the root element of the payload.

Example 44-1 shows an EDL file with two business events in the BugReport event definition: bugUpdated and bugCreated. The namespace (BugReport) and associated schema file (BugReport.xsd) are referenced.

Example 44-1 EDL File with Two Business Events

<?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.

Business events are deployed to the metadata service (MDS) repository. Deploying a business event to MDS 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 MDS. An object in an MDS shared area is visible to all applications in the Resource Palette of Oracle JDeveloper. After an EDL is published, it can be subscribed to by other applications. EDLs cannot be unpublished; the definition always exists.

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 in the Event Delivery Network (EDN). The EDN runs within every SOA instance. Raised events are delivered by EDN to the subscribing service components.

For this release, the following SOA service components and actions are supported:

Oracle Mediator can subscribe to and publish events.
Oracle Mediator can subscribe to events that are then wired to the BPEL process. This feature enables you to pass the principal through the security interceptor for component-level authorization policy enforcement.

Notes:

There are two implementations of the EDN: JMS and AQ (provides support for PL/SQL APIs).

44.1.1 Local and Remote Events Boundaries

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. In this scenario, synchronous subscriptions are executed synchronously.
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. Only asynchronous subscriptions are supported for remote event connections.

You can also raise events through PL/SQL APIs.

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. The boundary for events is the application instance. When an event is raised in the application instance, subscriptions registered in the application instance are executed. Events are not propagated from one application instance to another. Propagation can be achieved through an Oracle Mediator in both instances, which listens to events and publishes them to a JMS queue.

44.2 Creating Business Events in Oracle JDeveloper

This section provides a high-level overview of how to create and subscribe to a business event. In this scenario, a business event named NewOrderSubmitted is created when a user places an order in a store front application (StoreFrontService service). You then create an Oracle Mediator service component to subscribe to this business event.

This scenario is part of the larger WebLogic Fusion Order Demo application. For additional details about this application, see the Oracle Fusion Middleware Tutorial for Running and Building an Application with Oracle SOA Suite.

44.2.1 How to Create a Business Event

To create a business event:

Create a SOA project as an empty composite.
Launch the Event Definition Creation wizard in either of two ways:
1. In the SOA Composite Editor, click the icon above the designer. Figure 44-1 provides an example.
  
  Figure 44-1 Event Definition Creation
  
  Description of "Figure 44-1 Event Definition Creation"
2. From the File main menu, select New > SOA Tier > Service Components > Event Definition.
The Event Definition Creation dialog appears.

Enter the details described in Table 44-1.

Table 44-1 Event Definition Creation Wizard Fields and Values

Field Value

Field	Value
Event Definition Name	Enter a name. 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.
Namespace	Accept the default namespace or enter a value for the namespace in which to place the event.

Event Definition Name

Enter a name.

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

44.2.2 How to Subscribe to a Business Event

To subscribe to a business event:

From the Component Palette, drag a Mediator service component into the SOA Composite Editor. This service component enables you to subscribe to the business event.
In the Name field, enter a name.
From the Options list, select Subscribe to Event.

The window is refreshed to display an events table.
Click the Add icon to select an event.

The Event Chooser window appears.
Select the event you created and click OK.

You are returned to the Create Mediator dialog.
Select a level of delivery consistency for the event.
- one and only one
  
  Events are delivered to the subscriber in its own global (that is, JTA) transaction. Any changes made by the subscriber within that transaction are committed after the event processing is complete. If the subscriber fails, the transaction is rolled back. Failed events are retried a configured number of times.
- guaranteed
  
  Events are delivered to the subscriber asynchronously without a global transaction. The subscriber can choose to create its own local transaction for processing, but it is committed independently of the rest of the event processing. The event is guaranteed to be handed to the subscriber, but because there is no global transaction, there is a possibility that a system failure can cause an event to be delivered more than once. If the subscriber throws an exception (or fails in any way), the exception is logged, but the event is not resent.
- immediate
  
  Events are delivered to the subscriber in the same global transaction and same thread as the publisher. The publish call does not return until all immediate subscribers have completed processing. If any subscribers throw an exception, no additional subscribers are invoked and an exception is thrown to the publisher. The transaction is rolled back in case of any error during immediate processing.
If you want to filter the event, double-click the Filter column of the selected event or select the event and click the filter icon (first icon) above the table. This displays the Expression Builder dialog. This dialog enables you to specify an XPath filter expression. A filter expression specifies that the contents (payload or headers) of a message be analyzed before any service is invoked. For example, you can apply a filter expression that specifies that a service be invoked only if the message includes a customer ID.

When the expression logic is satisfied, the event is accepted for delivery.

For more information about filters, see Section 19.2.2.6, "Specifying Expression for Filtering Messages."

Figure 44-5 shows the Create Mediator dialog.

Figure 44-5 Create Mediator Dialog

Description of "Figure 44-5 Create Mediator Dialog"
Click OK.

Figure 44-6 shows an icon on the left side that indicates that Oracle Mediator is configured for an event subscription.

Figure 44-6 Configuration for Event Subscription

Description of "Figure 44-6 Configuration for Event Subscription"

44.2.3 What Happens When You Create and Subscribe to a Business Event

The source code in Example 44-2 provides details about the subscribed event of the Oracle Mediator service component.

Example 44-2 Subscribed Event

<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"
         runAsRoles="$publisher"/>
</business-events>
</component>

While not explicitly demonstrated in this example, you can define XPath filters on events. In Example 44-3, the event is accepted for delivery only if the initial deposit is greater than 50000:

Example 44-3 Definition of XPath Filters on Events

    <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>

44.2.4 What You May Need to Know About Subscribing to a Business Event

Note that subscribers in nondefault revisions of SOA composite applications can still get business events. For example, note the following behavior:

Create a composite application with an initial Oracle Mediator service component named M1 that publishes an event and a second Oracle Mediator service component named M2 that subscribes to the event. The output is written to a directory.
Deploy the composite application as revision 1.
Modify the composite application by adding a third Oracle Mediator service component named M3 that subscribes to the same event and writes the output to a different directory.
Deploy the composite application as revision 2 (the default).
Invoke revision 2 of the composite application.

Note that Oracle Mediator M2 writes the output to two files with the same content in the directory. As expected, Oracle Mediator M3 picks up the event and writes the output successfully to another directory. However, note that Oracle Mediator M2 (from revision 1) is also picking up and processing the published event from revision 2 of the composite application. Therefore, it creates one more output file in the same directory.

44.2.5 How to Publish a Business Event

You can create a second Oracle Mediator to publish the event that you subscribed to in Section 44.2.2, "How to Subscribe to a Business 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.
Select Save All from the File main menu.

44.2.6 What Happens When You Publish a Business Event

Note that the two Oracle Mediator service components appear in Example 44-4. One service component (OrderPendingEvent) subscribes to the event and the other service component (PublishOrderPendingEvent) publishes the event.

Example 44-4 Event Subscription and Publication

<component name="PublishOrderPendingEvent">
    <implementation.mediator src="PublishOrderPendingEvent.mplan"/>
    <business-events>
      <publishes xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO"
 name="pub1:NewOrderSubmitted"/>
    </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"
         runAsRoles="$publisher"/>
</business-events>
</component>

44.2.7 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 Oracle Mediator.

To integrate Oracle ADF Business Component business events with Oracle Mediator:

Create a business component project.
Add a business event definition to the project. This action generates an EDL file and an XSD file. The XSD file contains the definition of the payload. Ensure also that you specify that the event be raised by the Oracle ADF Business Component upon creation.
Create an SOA composite application and manually copy the EDL and XSD schema files to the SOA project's root directory. For example:
```
JDeveloper/mywork/SOA_application_name/SOA_project_name
```
Place schema files at the proper relative location from the EDL file based on the import.
Create an Oracle Mediator service component as described in Section 44.2.2, "How to Subscribe to a Business Event."
In the Event Chooser window, select the event's EDL file, as described in Section 44.2.2, "How to Subscribe to a Business Event."
Create a BPEL process service component in the same SOA composite application for the Oracle Mediator to invoke. In the Input Element field of the Advanced tab, ensure that you select the payload of the Business Component business event XSD created in Step 2.
Double-click the BPEL process.
Drag an Email activity into the BPEL process.
Use the payload of the business event XSD to complete the Subject and Body fields.
Return to the Oracle Mediator service component in the SOA Composite Editor.
Design a second service component to publish the event, such as a BPEL process or a second Oracle Mediator service component.

SOA composite application design is now complete.

For more information about creating and publishing Oracle ADF Business Component business events, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.