41 Using Business Events and the Event Delivery Network

This chapter describes how to subscribe to or publish business events from Oracle Mediator or a BPEL process 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.s

This chapter includes the following sections:

For samples that show how to use business events with Oracle Mediator, see the Oracle SOA Suite samples.

For information about creating composite sensors on service components that subscribe to business events, see Section 50, "Defining Composite Sensors."

For information about troubleshooting business events, see Appendix "Troubleshooting Oracle SOA Suite" of Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.

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

  • 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 41-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 41-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. Oracle Mediator service components and BPEL process service components can subscribe to and publish events.

The EDN has two different implementations:

  • EDN-DB: Uses an Oracle database as a back-end store and depends on Oracle-specific features.

  • EDN-JMS: Uses a generic JMS queue as a back-end store.

If you are using an Oracle database, Oracle recommends that you use EDN-DB instead of EDN-JMS.

Note:

The EDN does not support durable subscriptions (whether they are backed by native advanced queueing (AQ) or Oracle WebLogic Server JMS). The subscribing service component must be running to receive events.

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

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 for events and publishes them to a JMS queue.

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

41.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 41-1 provides an example.

      Figure 41-1 Event Definition Creation

      Description of Figure 41-1 follows
      Description of "Figure 41-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 41-1.

    Table 41-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 41-2 provides details.

    Figure 41-2 Select the Payload

    Description of Figure 41-2 follows
    Description of "Figure 41-2 Select the Payload"

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

    Figure 41-3 Add an Event Dialog

    Description of Figure 41-3 follows
    Description of "Figure 41-3 Add an Event Dialog"

  7. Click OK.

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

    Figure 41-4 Event Definition Creation Dialog

    Description of Figure 41-4 follows
    Description of "Figure 41-4 Event Definition Creation Dialog"

  8. Above the editor, click the cross icon (x) next to event_definition_name.edl to close the 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.

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

41.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.3.2.8, "How to Specify an Expression for Filtering Messages."

    Figure 41-5 shows the Create Mediator dialog.

    Figure 41-5 Create Mediator Dialog

    Description of Figure 41-5 follows
    Description of "Figure 41-5 Create Mediator Dialog"

  8. Click OK.

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

    Figure 41-6 Configuration for Event Subscription

    Description of Figure 41-6 follows
    Description of "Figure 41-6 Configuration for Event Subscription"

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

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

Example 41-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 41-3, the event is accepted for delivery only if the initial deposit is greater than 50000:

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

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

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.

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

41.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 41.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. From the File main menu, select Save All.

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

  1. Log in to the Oracle WebLogic Server Administration Console.

    http://host:port/console

  2. In the Domain Structure section, expand Services > Foreign JNDI Providers.

  3. Click Lock & Edit.

  4. Click New.

  5. In the Name field, enter a name (for example, SOA_JNDI), and click Next.

  6. Select the AdminServer checkbox, and click Finish.

  7. In the Name column, click the provider name you entered in Step 5.

  8. Enter the details shown in Table 41-2, and click Save.

    Table 41-2 Configuration Details

    Field Description

    Initial Context Factory

    Enter weblogic.jndi.WLInitialContextFactory.

    Provider URL

    Enter t3://hostname:soa_server_port.

    User

    Enter the Oracle WebLogic Server user name.

    Password and Confirm Password

    Enter the password for the Oracle WebLogic Server user name.

  9. Click Links > New.

  10. Enter the details shown in Table 41-3, and click OK.

    Table 41-3 Configuration Details

    Field Description

    Name

    Enter SOA_EDNDataSource.

    Local Name

    Enter jdbc/EDNDataSource.

    Remote Name

    Enter jdbc/EDNDataSource.

  11. Click New.

  12. Enter the details shown in Table 41-4, and click OK.

    Table 41-4 Configuration Details

    Field Description

    Name

    Enter SOA_EDNLocalTxDataSource.

    Local Name

    Enter jdbc/EDNLocalTxDataSource.

    Remote Name

    Enter jdbc/EDNLocalTxDataSource.

  13. Click OK.

  14. Click Activate Changes.

  15. Modify the FMW_Home/user_projects/domains/domain_name/bin/setDomainEnv.sh file for Linux (or setDomainEnv.bat file for Windows) as follows:

    WLS_JDBC_REMOTE_ENABLED="-Dweblogic.jdbc.remoteEnabled=true"

  16. Restart the server.

41.3.6 How to Configure JMS-based EDN Implementations

The following JNDI configuration changes are required when the EDN implementation is JMS-based (EDN-JMS). In these scenarios, a generic JMS queue is used as the back-end store. These changes enable the remote client (for example, the ADF application client) to look up the connection factory before publishing events.

To configure JMS-based EDN Implementations

  1. Log in to the Oracle WebLogic Server Administration Console.

    http://host:port/console

  2. In the Domain Structure section, expand Services > Data Sources.

    You must remove the EDN-DB JNDI sources to use EDN-JMS data sources.

  3. Select the following EDN-DB JNDI data sources, and click Remove.

    • jdbc/EDNDataSource

    • jdbc/EDNLocalTxDataSource

    If the event publisher is in an application (for example, ADF) running in a different cluster or even in a different domain from the SOA server for EDN, you must configure a foreign JNDI provider with the local JNDI names for the cluster mapping to JNDI names targeted to the SOA Infrastructure. Local and remote JNDI names are the same in the links.

  4. In the Domain Structure section, expand Services > Foreign JNDI Providers.

  5. Click New.

  6. In the Name field, enter a name for the foreign JNDI provider.

  7. Select targets for the new JNDI provider, and click Finish.

  8. In the Name field, click the new JNDI provider.

  9. Specify provider settings (the initial context factory, provider URL, and so on), and click Save.

  10. Click the Links tab.

  11. Click New to create a foreign JNDI link.

  12. Enter a name, then specify the local and remote JNDI name of jms/fabric/EDNConnectionFactory.

  13. Repeat Step 12, and specify a name and the local and remote JNDI name of jms/fabric/xaEDNConnectionFactory.Repeat Step 12, and specify a name and the local and remote JNDI name of jms/fabric/EDNQueue.

    Once complete, three links are created.

  14. Restart the targeted servers.

  15. Confirm the new JNDI provider links in the JNDI tree view.

If you do not make these configuration changes, errors similar to those shown in Example 41-4 occur.

Example 41-4 EDN-JMS Error Messages

<Aug 30, 2010 1:28:46 PM EDT> <Warning>
<oracle.adf.controller.faces.lifecycle.Utils> <BEA-000000> <ADF: Adding the
following JSF error message: [FMWGEN][SQLServer JDBC Driver][SQLServer]Could
not find stored procedure 'edn_internal_publish_event'.

oracle.fabric.common.FabricException: Error enqueueing event:
[FMWGEN][SQLServer JDBC Driver][SQLServer]Could not find stored procedure
'edn_internal_publish_event'.

               at
oracle.integration.platform.blocks.event.saq.SAQRemoteBusinessEventConnection.
enqueueEvent(SAQRemoteBusinessEventConnection.java:86)

41.3.7 What Happens When You Publish a Business Event

Two Oracle Mediator service components appear in Example 41-5. One service component (OrderPendingEvent) subscribes to the event and the other service component (PublishOrderPendingEvent) publishes the event.

Example 41-5 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>

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

41.4.1 How to Subscribe to a Business Event

To subscribe to a business event:

  1. From the Component Palette, drag a BPEL Process service component into the SOA Composite Editor.

  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 branch of a pick activity can also be set up to receive events from the EDN. For more information about the onMessage branch, see Section 15.2, "Creating a Pick Activity to Select Between Continuing a Process or Waiting."

  5. Double-click the Receive activity. The Receive dialog opens. Alternatively, you can also right-click the Receive activity and click Edit.

  6. In the Name field, enter a name.

  7. From the Interaction Type list, select Event. The layout of the Receive dialog changes.

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

    Figure 41-7 Subscribed Events Dialog

    Subscribed Events dialog
    Description of "Figure 41-7 Subscribed Events Dialog"

  9. Click the Add icon to select an event.

    The Event Chooser dialog appears, as shown in Figure 41-8.

    Figure 41-8 Event Chooser Dialog

    Event Chooser dialog
    Description of "Figure 41-8 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 an 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 action 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 41-9 shows a BPEL process service component that is configured for event subscription.

    Figure 41-9 BPEL Process Service component Configuration for Event Subscription

    Description of Figure 41-9 follows
    Description of "Figure 41-9 BPEL Process Service component Configuration for Event Subscription"

41.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 41.4.1, "How to Subscribe to a Business Event."

  2. Double-click the Invoke activity. The Invoke dialog opens. Alternatively, you can also right-click the Invoke activity and click Edit.

  3. In the Name field, enter a name.

  4. From Interaction Type list, select Event. The layout of the Invoke dialog changes.

  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 41-10 shows a BPEL process service component that is configured for an event subscription and publication. The blue lightning bolt in the circle on the left side indicates event subscription. The yellow lightning bolt in the circle on the right side indicates event publication. Clicking the blue arrow inside the title changes it to display the title of the published event.

    Figure 41-10 BPEL Process Service Component Configuration for Event Subscription and Publishing

    Description of Figure 41-10 follows
    Description of "Figure 41-10 BPEL Process Service Component Configuration for Event Subscription and Publishing"

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

The source code in Example 41-6 shows how the composite.xml source changes for the subscribed and published events of a BPEL process service component.

Example 41-6 Event Subscription and Publication

<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. 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 Example 41-7, the event is accepted for delivery only if the initial deposit is greater than 50000.

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

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 Example 41-8:

Example 41-8 The Schema for the Eventname Attribute

<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 41-9 shows how the eventName attribute is used in the BPEL source file:

Example 41-9 BPEL Source Code Using eventName Attribute

<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) element, then the standard attributes such as partnerLink, operation, or portType attributes 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 should enforce the presence of either the bpelx:eventName attribute or the partnerLink, operation, and portType attributes, but not both. Example 41-10 shows the modified schema definition of a BPEL receive activity.

Example 41-10 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.

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

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 Mediator service component or BPEL process service component named S1 that publishes an event and a second Mediator service component or BPEL process service component named S2 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 Mediator service component or BPEL process service component named s3 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.

Service component S2 writes the output to two files with the same content in the directory. As expected, service component S3 picks up the event and writes the output successfully to another directory. However, service component S2 (from revision 1) also picks up and processes the published event from revision 2 of the composite application. Therefore, it creates one more output file in the same directory.

41.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 Mediator service components and BPEL process service components.

To integrate Oracle ADF Business Component business events with SOA Components:

  1. Create a business component project.

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

    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.

  3. Create a SOA composite application and manually copy the EDL and XSD schema files to the root directory of the SOA project. For example:

    JDeveloper/mywork/SOA_application_name/SOA_project_name

  4. Place schema files at the proper relative location from the EDL file based on the import.

  5. Create a Mediator service component as described in Section 41.3.1, "How to Subscribe to a Business Event".

  6. In the Event Chooser window, select the EDL file of the event, as described in Section 41.3.1, "How to Subscribe to a Business Event."

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

  8. Double-click the BPEL process service component.

  9. Drag an Email activity into the BPEL process service component.

  10. Use the payload of the business event XSD to complete the Subject and Body fields.

  11. Return to the Oracle Mediator service component in the SOA Composite Editor.

  12. Design a second service component to publish the event, such as a BPEL process service component or a second Oracle Mediator service component.

    SOA composite application design is now complete.