Interaction Pattern	Messaging Support	Configuration	EDN Notes
Request/Reply	Separate JMS queues are used for Request and Response messages. JMS Message Headers are used to correlate requests with responses.	Request and response queues must be configured with appropriate connection factories and message store.	EDN does not support request/reply. It is not possible to target the receiver of an event. Event subscribers are not visible to event producers and so cannot be directly targeted. Similarly, event producers are not visible to event subscribers and so it is not possible to send direct replies just to the originator of the event.
One way guaranteed delivery	Single JMS queue with a single subscriber	Queue must be configured with appropriate connection factory and message store	EDN does not support guaranteed one way delivery of events. An event producer has no way of knowing how many subscribers will receive the message or if any subscribers will receive the message.
One-to-many message delivery	Single JMS topic with zero or more subscribers	Topic must be configured with appropriate connection factory and message store.	EDN supports exactly this message interaction pattern without the need to configure any JMS artifacts. EDN uses JMS but this is hidden from the developer.

A sample use case

Consider an auction process. The basic auction process accepts new items for auction from a seller service, accepts bids from a bidder service, and identifies the winning bid in an auction service. All these operations require co-ordination between the services involved.

There may be concerns about the proprietary of some bids, but the time taken to validate the bid and ensure that it is legitimate may be viewed as too lengthy and instead it may be desired to have a background process to validate bids, so we do not slow down the normal bid taking process.

This is an extension to the business functionality that does not require a conversation between the bid process and the validation service. In fact, a conversation may slow down the auction process and increase the time taken to accept and confirm bids and winners. This is an excellent use case for the EDN because of the following features:

No conversation is required between the event consumer (bid legitimacy process) and the event producer (auction process).
The event consumer can be added to the system without any changes to the event producer. As long as the auction process is publishing bid events, adding the bid validator will not impact the auction process.
Additional producers may be added to the system without impacting existing producers and/or consumers. For example, different auction systems may raise the same event.
Additional consumers may also be added independently of either existing producers and/or consumers. For example, an automated bidding service may make use of this event later without impacting the existing services.

Event Delivery Network essentials

The EDN is a very simple but very powerful concept, and we will now explain the basic principles associated with it.

Events

An event is the message that will be published and consumed on the Event Delivery Network. Events consist of three parts:

A namespace that identifies the general area that the event is associated with and helps to avoid clashes between event names
A name that identifies the type of event within a namespace
A data type that defines the data associated with the event

Namespaces of events behave in the same way as namespaces in XML and identify the solution area of the events and avoid clashes between events with the same name that belong to different solution areas. For example, a namespace would differentiate an event called NewOrder in a military command and control system from an event called NewOrder in a logistics system.

Events are defined using an XML-based language called the Event Description Language (EDL).

We can model business events from within JDeveloper by clicking on the event icon Events on the top-left-hand corner of the composite editor as shown in the following screenshot.

This brings up the Create Event Definition File dialog to allow us to create a new EDL file to contain our event definitions.

After defining the EDL File Name, the Directory it resides in, and the Namespace of the EDL file, we can add events to it by clicking on the green plus symbol Events . This takes us to the Add an Event dialog, where we can choose the XML Element that represents the data content of the event and give the event a Name.

Event elements and data types should always be defined in an XML schema file, which is separate from other SOA XML artifacts such as message schemas. This is because the events may be used across many areas, and they should not have dependencies on other SOA artifacts.

After completing the definition of our EDL file, it is displayed in JDeveloper, where we can continue to add or remove events.

The EDL file itself is a very simple format, shown as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<definitions xmlns=http://schemas.oracle.com/events/edltargetNamespace="AuctionEventDefinitions">
    <schema-import namespace="auction.events"location="xsd/AuctionEvents.xsd"/>
        <event-definition name="NewAuctionEvent">
        <content xmlns:ns0=" auction.events"element="ns0:NewAuction"/>
        </event-definition>
        <event-definition name="NewBidEvent">
          <content xmlns:ns0=" auction.events" element="ns0:NewBid"/>
        </event-definition>
</definitions>

The targetNamespace attribute of the <definitions> element defines the namespace for the events. XML-type definitions are imported using <schema-import>, and <event-definition> is used to define events and their associated element.

Event publishers

Events are created by event publishers. An event publisher may be a Mediator or BPEL component in an SCA Assembly or it may be a custom Java application. The event publisher raises the event by creating an XML element and passing it to the Event Delivery Network. Once passed to the EDN, the publisher is unaware of how many subscribers consume the event or even if the event is consumed by any subscriber. This provides a degree of isolation between the publisher and subscribers. The EDN is responsible for keeping track of who is subscribing and ensuring that they receive the new event.

Publishing an event using the Mediator component

When using a Mediator to publish an event, we usually want to publish the event in parallel with other processing that the Mediator is doing. Typically, we want the Mediator to take the request from some service call and publish the event.

In the following example, we have a Mediator NewAuctionMediator that routes to a dummy service implemented by a Mediator ServiceMediator that uses Echo functionality to provide a synchronous response to its caller. We will raise a NewAuction event as part of the inbound processing in the Mediator. Note that although the Mediator will route a reply to the specific caller of the composite, the event will be routed to all subscribers of that event type.

Publishing an event using the Mediator component

We can raise an event based on the input request in the following fashion.

We open the routing Mediator component, in this case, NewAuctionMediator, and add a new sequential static routing rule. When the Target Type dialog comes up, select the Event button to generate an event.

In the Event Chooser dialog, we can choose the Event Definition File that contains our event. We can either browse for an existing EDL file using the magnifying glass icon or we can create a new EDL file by using the thunderbolt icon. Once an EDL file has been chosen, we can then select the specific event that we wish to produce.

If we choose an existing EDL file that is not in our project, JDeveloper will assume that we want to copy the EDL file and its associated XML schemas into the project. On the Localize Files dialog, we have the choice of keeping existing directory relationships between files or flattening any existing directory structure.

Once the event is selected, we then just need to add a transformation to transform the input of the request to the event format.

Publishing an event using BPEL

We can also publish events using BPEL. Using the previous example, we may decide that rather than just publishing a NewAuction event that contains the input data used to create the auction, we also wish to include the auction identifier generated by the response to the new auction request. This is best achieved using the BPEL event publisher.

Using the previous example, we insert a BPEL process between the service requestor, in this case, NewAuctionMediator, and the service provider, in this case ServiceProvider. We use the Base on a WSDL template to create the process and select the WSDL of the target service as our WSDL, in this case the WSDL for ServiceMediator. We then rewire the composite so that the target service is now invoked by our new BPEL process, and the original client of the service is now a client of the BPEL process, as shown in the following diagram:

We then edit the BPEL process to invoke the original target service. Because we have used the target service WSDL for the WSDL of the BPEL process, we can use the input and output variables of the process as parameters to invoke the target service. With this done, we are ready to publish the event as part of our BPEL process.

We publish an event from within BPEL by using an invoke and setting the Interaction Type to be Event rather than the more usual Partner Link.

This allows us to select an event and a variable to hold the data for that event. The event itself is chosen from the Event Chooser dialog, which was introduced in the previous section. We then need to add an assign statement to initialize the variable used to populate the event. The fact that this invoke is actually raising an event is identified by the lightning symbol on the Invoke.

Note that when we raise an event, there is no indication provided as to how to route or deliver the event. In the next section, we will look at how events are consumed.

Publishing an event using Java

We can also publish and consume events using Java. In this section, we will look at how Java code can be used to publish an event.

To publish an event, we need to go through the following steps:

Create the event
Connect to the Event Delivery Network
Publish the event on the connection

Creating the event

We create the event in Java by using the oracle.integration.platform.blocks.event.BusinessEventBuilder class. An instance of this class is created by a static factory method called newInstance. We need to provide a qualified name (QName that includes the namespace and the entity name) and a body for the event through setter methods on the builder class. Once these have been set, we can call createEvent to generate an instance of a BusinessEvent.

BusinessEventBuilder builder = BusinessEventBuilder.newInstance();
QName name = new QName("http://schemas.oracle.com/events/edl/AuctionEventDefinitions","NewAuctionEvent");
builder.setEventName(name);
XMLElement content = …
builder.setBody(content);
BusinessEvent event = builder.createEvent();

The event name is a combination of the event schema, acting as an XML namespace, and the event name. The content is the XML element containing the event content.

Once we have a BusinessEvent, we need a connection to the Event Delivery Network in order to publish the event.

Creating the event connection

The event connection can be created using either a JMS queue connection to the Event Delivery Network or an Oracle AQ connection. The latter requires the use of a data source and is the approach we will show. We obtain an oracle.fabric.blocks.event.BusinessEventConnection from a BusinessEventConnectionFactory. We will use the AQ version of this connection factory, which is provided by the oracle.integration.platform.blocks.event.saq. SAQRemoteBusinessEventConnectionFactory class.

DataSource ds = …
  BusinessEventConnectionFactory factory = new
    SAQRemoteBusinessEventConnectionFactory(ds, ds, null);
  BusinessEventConnection conn =
    factory.createBusinessEventConnection();

We use the connection factory to create a connection to Event Delivery Network. The data source we provide must be configured to connect to the SOA infrastructure schema in the database, which by default is called <PREFIX>_SOAInfra.

Publishing the event

Now that we have an EDN connection, we can publish our event on it by calling publishEvent:

conn.publishEvent(event, EVENT_PRIORITY);

This publishes our event on our previously created connection. The event priority is usually set to 3, but it is not used in this release.

Event subscribers

Events are consumed by event subscribers. In a similar fashion to event publishers, event subscribers may be BPEL processes or Mediators. When subscribing to an event, the subscriber can filter the events. Subscribers subscribe to a specific event within an event namespace. They can limit the instances of an event that they receive by applying a filter. Only events for which the filter evaluates to true are delivered to the event subscriber. Event filters are XPath expressions.

Consuming an event using Mediator

To consume an event, we can add an event subscriber to a Mediator. We do this by clicking on the green plus sign next to the Event Subscriptions label under Routing Rules.

This brings us to the Subscribed Events dialog where, by clicking on the green plus sign, we add a new event subscription using the Event Chooser dialog introduced in the section on publishing an event.

Having chosen an event, we can determine how the event is to be delivered using the Consistency option. Transactions are discussed later in Chapter 15, Advanced SOA Suite Architecture. The consistency options are:

Exactly once by selecting the one and only one option. This makes the event delivery transaction part of the Mediator transaction. If the Mediator transaction completes successfully, then the event will also be marked as read, otherwise it will be rolled back and thus appear not to have been delivered. Transaction boundaries are explained in more detail in Chapter 15, Advanced SOA Suite Architecture
At least once by selecting guaranteed. This keeps the Mediator transaction separate from the delivery transaction. The event will be delivered to the subscriber, but any errors in the Mediator may cause that event to be lost to that subscriber.
immediate makes the delivery transaction part of the event publishing transaction. This option should be avoided as it couples the subscriber and the publisher.
Tip
Avoid using the immediate delivery option as it tightly couples the publisher to a subscriber that it should be unaware of. The Java API for this is marked as deprecated, and it is likely that this option will disappear in the future.

The Run as publisher option allows the Mediator to run in the same security context as the event publisher. This allows the subscriber component to perform any actions that the publisher could perform.

The Filter option brings up the Expression Builder dialog when clicked on. This allows us to construct an XPath expression to limit the delivered event to only those for which the XPath expression resolves to true.

A component in a composite that has subscribed to an event has a lightning bolt Consuming an event using Mediator on its service side to identify it within a composite.

Consuming an event using BPEL

To subscribe to an event using BPEL, we can create a BPEL process using the Subscribe to Events template. This allows us to add the events to which we wish to subscribe to in a similar fashion to having the Mediator subscribe to events by using the Event Chooser dialog and adding quality of service options and filters.

This creates a BPEL process with a single receive activity that identifies itself as subscribing to an event by the lightening icon Consuming an event using BPEL on the receive.

Events may also be subscribed to by adding a BPEL Receive activity to the process and choosing an Interaction Type of Event.

Events

An event is the message that will be published and consumed on the Event Delivery Network. Events consist of three parts:

A namespace that identifies the general area that the event is associated with and helps to avoid clashes between event names
A name that identifies the type of event within a namespace
A data type that defines the data associated with the event