36 Using Business Events and the Event Delivery Network

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

36.2.1 How to Create a Business Event

To create a business event:

1. Create a SOA project as an empty composite.

2. Launch the Event Definition Creation wizard in either of two ways:

   1. In the SOA Composite Editor, click the icon above the designer. Figure 36-1 provides an example.

      Figure 36-1 Event Definition Creation

      
      Description of "Figure 36-1 Event Definition Creation"
      
      

   2. From the File main menu, select New > SOA Tier > Service Components > Event Definition.

   The Event Definition Creation dialog appears.

3. Enter the details described in Table 36-1.

   Table 36-1 Event Definition Creation Wizard Fields and Values

   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.

   
   

4. Click the Add icon to add an event.

   The Add an Event dialog appears.

5. Click the Search icon to select the payload, and click OK. Figure 36-2 provides details.

   Figure 36-2 Select the Payload

   
   Description of "Figure 36-2 Select the Payload"
   
   

6. In the Name field, enter a name, as shown in Figure 36-3.

   Figure 36-3 Add an Event Dialog

   
   Description of "Figure 36-3 Add an Event Dialog"
   
   

7. Click OK.

   The added event now appears in the Events section, as shown in Figure 36-4.

   Figure 36-4 Event Definition Creation Dialog

   
   Description of "Figure 36-4 Event Definition Creation Dialog"
   
   

8. Above the editor, click the cross icon (x) next to event_definition_name.edl to close the Events editor.

9. 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 MDS and you are returned to the SOA Composite Editor. The business event displays for browsing in the Resource Palette.

36.3.1 How to Subscribe to a Business Event

To subscribe to a business event:

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

2. In the Name field, enter a name.

3. From the Options list, select Subscribe to Event.

   The window is refreshed to display an events table.

4. Click the Add icon to select an event.

   The Event Chooser window appears.

5. Select the event you created and click OK.

   You are returned to the Create Mediator dialog.

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

7. 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 20.2.2.6, "Specifying Expression for Filtering Messages."

   Figure 36-5 shows the Create Mediator dialog.

   Figure 36-5 Create Mediator Dialog

   
   Description of "Figure 36-5 Create Mediator Dialog"
   
   

8. Click OK.

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

   Figure 36-6 Configuration for Event Subscription

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

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

The source code in Example 36-2 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"
         runAsRoles="$publisher"/>
</business-events>
</component>

While not explicitly demonstrated in this example, you can define XPath filters on events. In Example 36-3, 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>

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

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

2. Deploy the composite application as revision 1.

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

4. Deploy the composite application as revision 2 (the default).

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

36.3.4 How to Publish a Business Event

You can create a second Oracle Mediator to publish the event that you subscribed to in Section 36.3.1, "How to Subscribe to a Business Event."

To publish a business event:

1. Create a second Oracle Mediator service component that publishes the event to which the first Oracle Mediator subscribes.

2. Return to the first Oracle Mediator service component.

3. In the Routing Rules section, click the Add icon.

4. Click Service when prompted by the Target Type window.

5. Select the second Oracle Mediator service component.

6. Select Save All from the File main menu.

36.3.5 What Happens When You Publish a Business Event

Note that the two Oracle Mediator service components appear in Example 36-4. 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"/>
    </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>

36.4.1 How to Subscribe to a Business Event

To subscribe to a business event:

1. Drag a BPEL Process service component into the SOA Composite Editor from the Component Palette.

2. In the Name field, enter a name. Do not change any other default option and click OK.

   The BPEL Process service component is created.

3. Double-click the BPEL Process service component. The Oracle BPEL Designer is opened. Alternatively, you can also right-click the BPEL Process service component and click Edit.

4. Drag a Receive activity from the Component Palette into the SOA Composite Editor, below the receiveInput activity.

   Note:

   The onMessage node of a pick activity can also be set up to receive events from the EDN. For more information about the onMessage node, refer to Section 5.4, "Introduction to Asynchronous Interactions with a Timeout".

5. Double-click the Receive activity. The Receive dialog opens, as shown in Figure 36-7. Alternatively, you can also right-click the Receive activity and click Edit.

   Figure 36-7 Receive Dialog

   
   

6. In the Name field, enter a name.

7. From Interaction Type list, select Event. The layout of the Receive dialog changes, as shown in Figure 36-8.

   Figure 36-8 Receive Dialog with Interaction Pattern as Event

   
   

8. Click the Browse Events... icon to the right of the Event field. The Subscribed Events dialog appears, as shown in Figure 36-9.

   Figure 36-9 Subscribed Events Dialog

   
   

9. Click the Add icon to select an event.

   The Event Chooser dialog appears, as shown in Figure 36-10.

   Figure 36-10 Event Chooser Dialog

   
   

10. Select the event you created and click OK.

    You are returned to the Subscribed Events dialog.

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

12. 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 order includes a order ID.

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

13. Click OK to close the Subscribed Events dialog. You are returned to the Receive dialog.

    Note:

    Optionally, you can select the Create Instance checkbox, if this receive activity is the initiating receive activity that starts the BPEL Process service component instance. This enables creation of a new BPEL Process service component instance for every invocation.

    If this receive activity is a midprocess receive activity in which the BPEL instance is already started, then this receive activity waits for another event to continue the execution of this BPEL instance.

14. Click OK.

    Figure 36-6 shows a BPEL Process service component that is configured for event subscription.

    Figure 36-11 BPEL Process Service component Configuration for Event Subscription

    
    Description of "Figure 36-11 BPEL Process Service component Configuration for Event Subscription"
    
    

36.4.2 How to Publish a Business Event

To publish a business event:

1. Drag an Invoke activity from the Component Palette into the SOA Composite Editor, below the Receive activity created in Section 36.4.1, "How to Subscribe to a Business Event".

2. Double-click the Invoke activity. The Invoke dialog opens, as shown in Figure 36-12. Alternatively, you can also right-click the Invoke activity and click Edit.

   Figure 36-12 Invoke Dialog

   
   

3. In the Name field, enter a name.

4. From Interaction Type list, select Event. The layout of the Invoke dialog changes, as shown in Figure 36-13.

   Figure 36-13 Invoke Dialog with Interaction Pattern as Event

   
   

5. Click the Browse Events... icon to the right of the Event field. The Event Chooser window appears.

6. Select the event you created and click OK.

   You are returned to the Invoke dialog.

7. Click OK.

   Figure 36-14 shows a BPEL Process service component that is configured for an event subscription and publication.

   Figure 36-14 BPEL Process Service Component Configuration for Event Subscription and Publishing

   
   Description of "Figure 36-14 BPEL Process Service Component Configuration for Event Subscription and Publishing"
   
   

36.4.3 What Happens When You Subscribe to and Publish a Business Event

The source code in Example 36-2 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"
                runAsRoles="$publisher"/>
     <publishes xmlns:pub1="http://mycompany.com/events/orders"
                name="pub1:ProductSoldAlert"/>
   </business-events>
</component>

While not explicitly demonstrated in this example, you can define XPath filters on events. In Example 36-6, 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, and onMessage 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 Example 36-7:

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

Example 36-8 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, or onMessage element, then the standard attributes such as partnerLink, operation, or portType attributes should not be 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 portTyp attributes are no longer mandatory. The JDeveloper validation logic should enforce the presence of either the bpelx:eventName attribute or the partnerLink, operation, and portTyp attributes, but not both. Example 36-9 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.