18 Getting Started with Oracle Mediator

This chapter provides an overview of Oracle Mediator and also describes how to create an Oracle Mediator service component.

This chapter includes the following sections:

18.1 Introduction to Oracle Mediator

Oracle Mediator is a service component of the Oracle SOA Suite that provides mediation capabilities such as selective routing, transformation, and validation capabilities, along with various message exchange patterns, such as synchronous, asynchronous, and event publishing or subscriptions.

Oracle Mediator provides a lightweight framework to mediate between various components within a composite application. Oracle Mediator converts data to facilitate communication between different interfaces exposed by different components that are wired to build a SOA composite application. For example, Oracle Mediator can accept data contained in a text file from an application or service, transform it into a format appropriate for updating a database that serves as a customer repository, and then route and deliver the data to that database.

Oracle Mediator facilitates integration between events and services, where service invocations and events can be mixed and matched. You can use an Oracle Mediator service component to consume a business event or receive a service invocation. An Oracle Mediator service component can evaluate routing rules, perform transformations, validate, and either invoke another service or raise another business event. You can use an Oracle Mediator service component to handle returned responses, callbacks, faults, and timeouts.

Oracle Mediator provides the following features:

  • Content-Based and Header-Based Routing

    Oracle Mediator provides support for setting rules based on message payload or message headers. You can select elements or attributes from the message payload or the message header and, based on the values in those elements or attributes, you can specify an action. For example, Oracle Mediator receives a file from an application or service containing data about new customers. Based on the country mentioned in the customer's address, you can route and deliver data to the database storing data for that particular country. Similarly, you can route a message based on the message header.

    For more information about header-based routing, see Section 19.2.2.11, "How to Access Headers for Filters and Assignments."

  • Synchronous and Asynchronous Interactions

    Oracle Mediator provides support for synchronous and asynchronous request and response interactions. In a synchronous interaction, the client requests a service and then waits for a response to the request. In an asynchronous interaction, the client invokes the service, but does not wait for the response. You can specify a timeout period for an asynchronous interaction and you can specify an action to perform after the timeout period, such as raise an event or start a process.

    For more information about synchronous and asynchronous interactions, see Section 19.2.2.4, "How to Configure Response Messages" and Chapter 23, "Understanding Message Exchange Patterns of an Oracle Mediator."

  • Sequential and Parallel Routing of Messages

    A routing rule can be either executed in parallel or sequentially. You can configure the execution type from the Routing Rules section of the Mediator Editor.

    For more information about sequential and parallel routing of messages, see Section 19.2.2.3, "How to Specify Sequential or Parallel Execution."

  • Transformations

    Oracle Mediator supports data transformation from one XML schema to another. This feature enables data interchange among applications using different schemas. For example, you can transform a comma-delimited file to a database table structure.

    For more information about transformations, see Section 19.2.2.8, "How to Create Transformations."

  • Validations

    Oracle Mediator provides support for validating the incoming message payload using a Schematron or an XSD file. You can specify Schematron files for each inbound message part and Oracle Mediator can execute Schematron file validations for those parts.

    For more information about validations, see Section 19.2.2.12, "How to Use Semantic Validation" and http://www.schematron.com/.

  • Java Callouts

    Oracle Mediator lets you add Java callouts to the routing rules. Java callouts are a way of using of Java code with regular expressions.

    For more information about Java callouts, see Section 19.2.2.13, "How to Use Java Callouts."

  • Event Handling

    An event is a message sent because an activity occurred in a business environment. Oracle Mediator supports subscribing to business events and raising business events. You can subscribe to a business event that is generated when a situation of interest occurs. For example, you can subscribe to an event that is generated when a new customer is created and then use this event to start a business process, such as sending a confirmation email. Similarly, you can generate business events when a situation of interest occurs. For example, after a new customer profile is created, you can generate a customer-created event.

    For more information about event handling, see Chapter 38, "Using Business Events and the Event Delivery Network."

  • Dynamic Routing

    Dynamic routing separates the control logic of a process from the execution of the process. The control logic determines the path taken by the process. You can create a dynamic routing rule from the Mediator Editor.

    For more information about dynamic routing, see Section 19.2.3, "How to Create Dynamic Routing Rules."

  • Error Handling

    Oracle Mediator supports both manual error handling and error handling based on a fault policy. A fault policy consists of conditions and actions, where the conditions specify the action to be carried out for a particular error condition.

    For more information about error handling, see Chapter 21, "Using Oracle Mediator Error Handling."

  • Echo

    Oracle Mediator supports echoing source messages back to the initial caller after any transformations, validations, assignments, or sequencing operations are performed.

    For more information about Oracle Mediator echo support, see "To echo a service:" of Section 19.2.2.1, "How to Specify Oracle Mediator Services or Events."

  • Multiple Part Messages

    Oracle Mediator an process messages consisting of multiple parts. Some Remote Procedure Call (RPC) web services contain multiple parts in the SOAP message.

    For more information about multiple part message support, see Chapter 20, "Working with Multiple Part Messages in Oracle Mediator."

18.2 Introduction to the Mediator Editor Environment

You can create an Oracle Mediator service component in a SOA composite application of Oracle JDeveloper and then configure it using the Mediator Editor. To display the Mediator Editor, double-click the Oracle Mediator service component in the SOA Composite Editor. For information about the SOA Composite Editor, see Chapter 2, "Developing SOA Composite Applications with Oracle SOA Suite."

Figure 18-1 shows the Mediator Editor along with the Application Navigator, Structure, and Messages windows.

Figure 18-1 Mediator Editor Window

Description of Figure 18-1 follows
Description of "Figure 18-1 Mediator Editor Window"

Each section of the view shown in Figure 18-1 lets you perform specific design and deployment tasks. The sections in this view include the following:

  • Application Navigator

    The Application Navigator, shown in the upper left section of Figure 18-1, displays the Oracle Mediator file structure. These files appear under the SOA Content folder of the project where you created an Oracle Mediator.

    A SOA composite application consists of the following Oracle Mediator files:

    • composite.xml: This file describes the entire SOA composite application. For information about the composite.xml file, see Chapter 2, "Developing SOA Composite Applications with Oracle SOA Suite."

    • .componentType: This file describes the services and references for a service component.

    • .mplan: This file contains Oracle Mediator metadata.

    • .wsdl: The Web Services Description Language (WSDL) file specifies how other services call an Oracle Mediator. A WSDL file defines the input and output messages and operations of an Oracle Mediator.

  • Mediator Editor

    The Mediator Editor, shown in the middle of Figure 18-1, provides a visual view of the Oracle Mediator component. This view appears when you perform one of the following actions:

    • Double-click an Oracle Mediator icon in the SOA Composite Editor.

    • Double-click the.mplan file for the Oracle Mediator in the Application Navigator.

  • Source View

    The Source view displays the source code of an Oracle Mediator. Click Source at the bottom of the Mediator Editor shown in Figure 18-1 to view the source code. The code in Source view is immediately updated to reflect any changes to an Oracle Mediator.

    Example 18-1 shows sample Oracle Mediator source code:

    Example 18-1 Oracle Mediator Source Code

    <?xml version = '1.0' encoding = 'UTF-8'?>
    <!--Generated by Oracle SCA Modeler version 1.0 at [4/16/07 10:05 PM].-->
    <Mediator name="CustomerDataRouter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://xmlns.oracle.com/sca/1.0/mediator"/>
    
  • History Window

    The History window displays history information about the Oracle Mediator file, including a revision history and side-by-side comparisons of read-only and editable versions of a file. Click History at the bottom of the Design window shown in Figure 18-1 to open the History window. Figure 18-2 shows the History view for an Oracle Mediator file.

    Figure 18-2 History Window

    Description of Figure 18-2 follows
    Description of "Figure 18-2 History Window"

  • Property Inspector

    The Property Inspector, shown at the bottom of Figure 18-1, displays details about Oracle Mediator properties.

  • Structure Window

    The Structure Window, shown in the lower left section of Figure 18-1, displays a structural view of the data of an Oracle Mediator.

  • Log Window

    The Log Window displays messages about the validation and compilation status.

18.3 Creating an Oracle Mediator

You can create an Oracle Mediator in multiple ways, depending on where you are in your application development process.

18.3.1 How to Create an Oracle Mediator

You can create an Oracle Mediator in a SOA composite application of Oracle JDeveloper using one of the following methods:

  • When you create a composite application

  • From within an existing composite application

  • When you create a project

  • From within an existing project

When you create an Oracle Mediator using any of these methods, the Create Mediator dialog appears so you can name the Oracle Mediator component and select a template for the interface.

To create an Oracle Mediator when creating a composite application:

  1. Create and Name the SOA application and project using the Create SOA Application wizard.

  2. When you reach the Configure SOA Settings page, select Composite with Mediator in the Composite Template list, as shown in Figure 18-3.

    Figure 18-3 Composite with Oracle Mediator Selection in Create SOA Project Wizard

    Description of Figure 18-3 follows
    Description of "Figure 18-3 Composite with Oracle Mediator Selection in Create SOA Project Wizard"

  3. Click Finish.

    The Create Mediator dialog appears.

  4. Configure the Oracle Mediator interface, as described in Section 18.4, "Configuring the Oracle Mediator Interface Definition".

To create an Oracle Mediator within a composite application:

  1. Open the composite application to which you are adding an Oracle Mediator in the SOA Composite Editor.

  2. Drag and drop an Oracle Mediator from the Component Palette (shown in Figure 18-4) to the Components section of the editor.

    Tip:

    The Component Palette is to the right of the SOA Composite Editor.

    Figure 18-4 Component Palette with an Oracle Mediator Service Component

    Description of Figure 18-4 follows
    Description of "Figure 18-4 Component Palette with an Oracle Mediator Service Component"

    The Create Mediator dialog appears.

  3. Configure the Oracle Mediator interface, as described in Section 18.4, "Configuring the Oracle Mediator Interface Definition".

To create an Oracle Mediator when creating a new project:

  1. Using the New Gallery wizard, create and name a new SOA project in the SOA Tier category.

    Tip:

    The New Gallery wizard appears when you select New Project from the Application menu to the right of the application name in the Application Navigator. You can also right-click in the Application Navigator and select New.
  2. On the Configure SOA Settings page of the New Gallery dialog, select Composite With Mediator from the Composite Template list, shown in Figure 18-5.

    Figure 18-5 Create SOA Project Wizard with Composite With Mediator Template Shown

    Description of Figure 18-5 follows
    Description of "Figure 18-5 Create SOA Project Wizard with Composite With Mediator Template Shown"

  3. Click Finish.

    The Create Mediator dialog appears.

  4. Configure the Oracle Mediator interface, as described in Section 18.4, "Configuring the Oracle Mediator Interface Definition".

To create an Oracle Mediator within an existing project:

  1. In the Application Navigator, select the project to which you want to add an Oracle Mediator.

  2. Right-click in the navigator pane and select New.

  3. Under Categories, select Service Components, and then select Mediator from the Items list, as shown in Figure 18-6.

    Figure 18-6 New Gallery Dialog with Oracle Mediator Service Component

    Description of Figure 18-6 follows
    Description of "Figure 18-6 New Gallery Dialog with Oracle Mediator Service Component"

  4. Click OK.

    The Create Mediator dialog appears.

  5. Configure the Oracle Mediator interface, as described in Section 18.4, "Configuring the Oracle Mediator Interface Definition".

18.4 Configuring the Oracle Mediator Interface Definition

When you create a new Oracle Mediator, you can specify an interface template that generates a basic set of default files in the Oracle Mediator project. These files provide a framework from which you can design and configure the Oracle Mediator. You can create an Oracle Mediator with the following interface options:

  • Oracle Mediator with no interface definition

  • Oracle Mediator with the interface defined by a WSDL file

  • Oracle Mediator with a one-way interface

  • Oracle Mediator with a synchronous interface

  • Oracle Mediator with an asynchronous interface

  • Oracle Mediator that subscribes to events

18.4.1 Creating an Oracle Mediator Without an Interface Definition

You can create an empty Oracle Mediator with no interface definition. This process does not create a WSDL file, and it provides you with the flexibility to create the SOA components in the order you want. After you create an Oracle Mediator without an interface definition, you must create a service or an event that starts the Oracle Mediator.

18.4.1.1 How to Create an Oracle Mediator Without an Interface Definition

The Define Interface Later template in the Create Mediator dialog creates an Oracle Mediator with no interface definition.

To create an Oracle Mediator without an interface definition:

  1. Create an Oracle Mediator using one of the methods described in Section 18.3, "Creating an Oracle Mediator".

    The Create Mediator dialog appears.

  2. In the Name field, enter a name for the Oracle Mediator service component.

  3. From the Template list, select Define Interface Later and click OK.

    Figure 18-7 Define Interface Later Template Selection on the Create Mediator Dialog

    Description of Figure 18-7 follows
    Description of "Figure 18-7 Define Interface Later Template Selection on the Create Mediator Dialog"

18.4.1.2 What Happens When You Create an Oracle Mediator Without an Interface Definition

The Oracle Mediator files are generated under the specified application and project in the Application Navigator, and the new Oracle Mediator appears in the Mediator Editor in Design view.

The Oracle Mediator has no associated WSDL file, port types, or operations. You must define these as described in the following sections. Figure 18-8 shows how an Oracle Mediator created with no interface definition appears in the Mediator Editor.

Figure 18-8 Oracle Mediator with no Interface Definition in the Mediator Editor

Description of Figure 18-8 follows
Description of "Figure 18-8 Oracle Mediator with no Interface Definition in the Mediator Editor"

18.4.1.3 How to Define an Interface for an Oracle Mediator

After you create an Oracle Mediator without an interface definition, you must define the interface by subscribing to events or by defining services.

To subscribe to events:

To subscribe to events, the events must be defined in an Event Definition (EDL) file.

  1. Open the Oracle Mediator you want to edit in the Mediator Editor.

  2. In the Routing Rules section, click Add Event Subscription.

    The Subscribed Events dialog appears.

  3. Click Add.

    The Event Chooser dialog appears.

  4. To the right of the Event Definition File field, click Search and then browse to and select an EDL file.

    The Event field is populated with the events defined in the EDL file.

  5. Select one or more events and click OK.

  6. In the Consistency list, select a level of delivery consistency for the event.

  7. In the Run as publisher field, either leave the default value of yes or select no.

  8. Double-click the Filter field to open the Expression Builder and define an expression for filtering the event.

  9. Click OK.

    For more information about the Consistency, Run as publisher, and Filter fields of an event, see Section 18.4.6, "Creating an Oracle Mediator for an Event Subscription."

To define services:

You can define service for an Oracle Mediator with no interface definition in the following two ways:

  • Connect the Oracle Mediator to a service through a wire in the SOA Composite Editor.

  • Use the Define Service option in the Mediator Editor.

To define services for an Oracle Mediator through a wire:

  • In the SOA Composite Editor, drag a wire from an Oracle Mediator to a service.

    For more information about wires and how to wire a service component to a service, see Section 2.5.1, "How to Wire a Service and a Service Component."

    Note:

    You can also connect an Oracle Mediator with a defined interface and defined reference to a service through a wire. However, to connect Oracle Mediator to a service, the interface of the Oracle Mediator and of the service must match.

    The service for an Oracle Mediator is automatically defined using the WSDL file from the wire source. For example, if you connect the ReadFile service shown in Figure 18-9 to the CustomerDataRouter Oracle Mediator, the CustomerDataRouter Oracle Mediator automatically inherits the service definition of the ReadFile service.

    Figure 18-9 Connecting Oracle Mediator to a Service

    Description of Figure 18-9 follows
    Description of "Figure 18-9 Connecting Oracle Mediator to a Service"

To define services for an Oracle Mediator in the Mediator Editor:

  1. Display the Oracle Mediator you want to edit in the Mediator Editor.

  2. To the right of the WSDL URL field, click Define Service.

    The Define Service dialog appears, as shown in Figure 18-10.

    Figure 18-10 Define Service Dialog

    Description of Figure 18-10 follows
    Description of "Figure 18-10 Define Service Dialog"

  3. Do one of the following:

    • To use an existing WSDL file, click Find existing WSDLs to the right of the WSDL URL field.

    • To create a WSDL file, click Generate WSDL from schema(s) to the right of the WSDL URL field.

    For information about how to generate a WSDL file, see Section 18.5, "Generating a WSDL File."

  4. From the Port Type list, select a port.

  5. From the Callback Port Type list, select a port for the response message in an asynchronous interaction.

  6. Click OK.

18.4.2 Creating an Oracle Mediator Based on a WSDL File

When you create an Oracle Mediator, you can base the interface definition on a WSDL file, which describes the interfaces of an Oracle Mediator, such as port types, operations, services, and schemas.

18.4.2.1 How to Create an Oracle Mediator Based on a WSDL File

The Interface Definition from WSDL template on the Create Mediator dialog box creates an Oracle Mediator based on a WSDL file that has already been created or that can be generated from a schema.

To create an Oracle Mediator based on a WSDL file:

  1. Create an Oracle Mediator as described in Section 18.3, "Creating an Oracle Mediator".

    The Create Mediator dialog appears.

  2. In the Name field, enter a name for the Oracle Mediator service component.

  3. From the Template list, select Interface Definition from WSDL, as shown in Figure 18-11.

    Figure 18-11 Interface Definition from WSDL Template Selection on the Create Mediator Dialog

    Description of Figure 18-11 follows
    Description of "Figure 18-11 Interface Definition from WSDL Template Selection on the Create Mediator Dialog"

  4. If you do not want to create an exposed service with SOAP bindings that is automatically connected to your Oracle Mediator, deselect the Create Composite Service with SOAP Bindings option.

  5. In the WSDL URL field, do one of the following:

    • To use an existing WSDL file, enter the name of the file or click Find existing WSDL files to browse for the file.

    • To create a new WSDL file, click Generate WSDL from schema(s).

    For more information about these options, see Section 18.5, "Generating a WSDL File."

  6. From the Port Type list, select a port.

    This parses the WSDL file that you specify in the WSDL URL field to display the list of port types.

  7. From the Callback Port Type list, select a callback port.

    A callback port is the one to which the response message is sent in an asynchronous communication.

  8. Click OK.

18.4.2.2 What Happens When You Create an Oracle Mediator from a WSDL File

The Oracle Mediator files are generated under the specified application and project in the Application Navigator, and the new Oracle Mediator appears in the Mediator Editor in Design view. If the WSDL file you specify is located in a different directory from the project files, the file and its associated schema files are copied to the Oracle Mediator project.

The appearance and source code of the Oracle Mediator varies depending on the name of the WSDL file and the port types and operations defined by the WSDL file. Figure 18-12 shows a sample Oracle Mediator created from a WSDL file.

Figure 18-12 Oracle Mediator from WSDL in the Mediator Editor

Description of Figure 18-12 follows
Description of "Figure 18-12 Oracle Mediator from WSDL in the Mediator Editor"

18.4.3 Creating an Oracle Mediator With a One-Way Interface Definition

In a one-way interaction, the client sends a message to a service and the service does not need to reply.

18.4.3.1 How to Create an Oracle Mediator with a One-Way Interface Definition

The One-Way Interface template in the Create Mediator dialog creates an Oracle Mediator for a one-way interaction.

To create an Oracle Mediator with a one-way interface definition:

  1. Create an Oracle Mediator as described in Section 18.3, "Creating an Oracle Mediator".

    The Create Mediator dialog appears.

  2. In the Name field, enter a name for the Oracle Mediator service component.

  3. From the Template list, select One-Way Interface, as shown in Figure 18-13.

    Figure 18-13 One-Way Interface Template Selection on the Create Mediator Dialog

    Description of Figure 18-13 follows
    Description of "Figure 18-13 One-Way Interface Template Selection on the Create Mediator Dialog"

  4. If you do not want to create an exposed service with SOAP bindings that is automatically connected to your Oracle Mediator service component, deselect the Create Composite Service with SOAP Bindings option.

  5. To the right of the Input field, click Search to select a schema element for the input message.

    By default, the singleString schema element is selected for the input message.

    Note:

    You can use any XSD schema to specify the format of the input document that Oracle Mediator processes. Here is a sample schema:
    <xsd:schema attributeFormDefault="qualified"
                elementFormDefault="qualified"
                targetNamespace="http://samples.otn.com/helloworld"
                xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                xmlns="http://samples.otn.com/helloworld">
             <include namespace="http://samples.otn.com/helloworld"
                schemaLocation="helloworld.xsd" />
             <xsd:element name="name1" type="xsd:string" />
             <xsd:element name="result1" type="xsd:string"/>
    </xsd:schema>
    
  6. Click OK.

18.4.3.2 What Happens When You Create an Oracle Mediator with a One-Way Interface Definition

The Oracle Mediator files that define a one-way interaction are generated under the specified application and project in the Application Navigator, and the new Oracle Mediator appears in the Mediator Editor in Design view. A WSDL file is also generated with the same name as the Oracle Mediator.

Figure 18-14 shows how an Oracle Mediator created with a one-way interface appears in the Mediator Editor. The arrow to the left of the execute operation in Figure 18-16 represents a one-way operation.

Figure 18-14 One-Way Interface Oracle Mediator in the Mediator Editor

Description of Figure 18-14 follows
Description of "Figure 18-14 One-Way Interface Oracle Mediator in the Mediator Editor"

18.4.4 Creating an Oracle Mediator with a Synchronous Interface Definition

Oracle Mediator supports synchronous request-response interactions. In a synchronous interaction, a client sends a request to a service and receives an immediate response. The client does not proceed further until the response arrives.

18.4.4.1 How to Create an Oracle Mediator with a Synchronous Interface Definition

The Synchronous Interface template in the Create Mediator dialog creates an Oracle Mediator for a synchronous interaction.

To create an Oracle Mediator with a synchronous interface definition:

  1. Create an Oracle Mediator as described in Section 18.3, "Creating an Oracle Mediator".

    The Create Mediator dialog appears.

  2. In the Name field, enter a name for the Oracle Mediator.

  3. From the Template list, select Synchronous Interface, as shown in Figure 18-15.

    Figure 18-15 Synchronous Interface Template Selection on the Create Mediator Dialog

    Description of Figure 18-15 follows
    Description of "Figure 18-15 Synchronous Interface Template Selection on the Create Mediator Dialog"

  4. If you do not want to create an exposed service with SOAP bindings that is automatically connected to your Oracle Mediator, deselect the Create Composite Service with SOAP Bindings option.

  5. To the right of the Input field, click Search to select a schema element for the input message.

    By default, the singleString schema element is selected for the input message.

  6. Click Search to the right of the Output field to select a schema element for the output message.

    By default, the singleString schema element is selected for the output message.

  7. Click OK.

18.4.4.2 What Happens When You Create an Oracle Mediator with a Synchronous Interface Definition

The Oracle Mediator files that define a synchronous interaction are generated under the specified application and project in the Application Navigator, and the new Oracle Mediator appears in the Mediator Editor in Design view. A WSDL file is also generated with the same name as the Oracle Mediator.

In a synchronous interaction, only one port is defined because the response is sent to the same port as the request. Figure 18-16 shows how an Oracle Mediator created with a synchronous interface appears in the Mediator Editor. The arrows to the left of the execute operation in Figure 18-16 represent a synchronous operation.

Figure 18-16 Synchronous Oracle Mediator Component in the Mediator Editor

Description of Figure 18-16 follows
Description of "Figure 18-16 Synchronous Oracle Mediator Component in the Mediator Editor"

18.4.5 Creating an Oracle Mediator with an Asynchronous Interface Definition

Oracle Mediator supports asynchronous request-response interactions. In an asynchronous interaction, a client sends a request to a service, but does not block and wait for a reply.

18.4.5.1 How to Create an Oracle Mediator with an Asynchronous Interface Definition

The Asynchronous Interface template in the Create Mediator dialog creates an Oracle Mediator for asynchronous interaction.

To create an Oracle Mediator with an asynchronous interface definition:

  1. Create an Oracle Mediator as described in Section 18.3, "Creating an Oracle Mediator".

    The Create Mediator dialog appears.

  2. In the Name field, enter a name for the Oracle Mediator.

  3. From the Template list, select Asynchronous Interface, as shown in Figure 18-17.

    Figure 18-17 Asynchronous Interface Template Selection on the Create Mediator Dialog

    Description of Figure 18-17 follows
    Description of "Figure 18-17 Asynchronous Interface Template Selection on the Create Mediator Dialog"

  4. If you do not want to create an exposed service with SOAP bindings that is automatically connected to your Oracle Mediator service component, deselect the Create Composite Service with SOAP Bindings option.

  5. To the right of the Input field, click Search to select a schema element for the input message.

    By default, the singleString schema element is selected for the input message.

  6. To the right of the Output field, click Search to select a schema element for the output message.

    By default, the singleString schema element is selected for the output message.

  7. Click OK.

18.4.5.2 What Happens When You Create an Oracle Mediator with an Asynchronous Interface Definition

The Oracle Mediator files that define an asynchronous interaction are generated under the specified application and project in the Application Navigator, and the new Oracle Mediator appears in the Mediator Editor in Design view. A WSDL file is also generated with the same name as the Oracle Mediator.

Figure 18-18 shows how an Oracle Mediator created with an asynchronous interface appears in the Mediator Editor. The Port Type field displays the port on which the request message is sent. The Callback Port Type field displays the port to which the response is sent. The arrows to the left of the execute operation in Figure 18-18 represent an asynchronous operation.

Figure 18-18 Asynchronous Oracle Mediator in the Mediator Editor

Description of Figure 18-18 follows
Description of "Figure 18-18 Asynchronous Oracle Mediator in the Mediator Editor"

18.4.6 Creating an Oracle Mediator for an Event Subscription

You can create an Oracle Mediator for subscribing to a business event that is generated when a situation of interest occurs. A business event consists of message data sent as the result of an occurrence in a business environment. For information about business events, see Chapter 38, "Using Business Events and the Event Delivery Network."

18.4.6.1 How to Create an Oracle Mediator for an Event Subscription

The Subscribe to Events template in the Create Mediator dialog creates an Oracle Mediator that subscribes to events. To subscribe to events, the events must be defined in an Event Definition (EDL) file.

To create an Oracle Mediator for an event subscription:

  1. Create an Oracle Mediator as described in Section 18.3, "Creating an Oracle Mediator".

    The Create Mediator dialog appears.

  2. In the Name field, enter a name for the Oracle Mediator service component.

  3. From the Template list, select Subscribe to Events, as shown in Figure 18-19.

    Figure 18-19 Subscribe to Events Template Selection in Create Mediator Dialog

    Description of Figure 18-19 follows
    Description of "Figure 18-19 Subscribe to Events Template Selection in Create Mediator Dialog"

  4. Click Add.

    The Event Chooser dialog appears.

  5. To the right of the Event Definition field, click Search.

    The SOA Resource Browser dialog appears.

  6. Select an event definition file (.edl) and click OK.

    The Event field is populated with the events described in the.edl file that you selected. For more information about creating.edl files, see Chapter 38, "Using Business Events and the Event Delivery Network."

  7. Select one or more events in the Event field, as shown in Figure 18-20, and click OK.

    Figure 18-20 Event Chooser Dialog

    Description of Figure 18-20 follows
    Description of "Figure 18-20 Event Chooser Dialog"

  8. Select a level of delivery consistency for the event.

    • one and only one: A global (JTA) transaction is used for event delivery. If the event call fails, the transaction is rolled back and the call is retried a configurable number of times.

    • guaranteed: A local transaction is used to guarantee delivery. There are no retries upon failure.

    • immediate: Events are delivered on the same thread and on the same transaction as the caller.

  9. In the Run as publisher field, select whether to run the event subscription under the security of the event publisher.

    By default, event subscription run under the security of the event publisher.

  10. To filter the event, perform any of the following:

    • Double-click the Filter column of the selected event.

    • Select the event and then click the filter icon (first icon).

    The Expression Builder dialog appears.

  11. In the Expression field, enter an XPath expression and click OK.

    Figure 18-21 shows a sample Expression Builder dialog.

    Figure 18-21 Business Event Filter

    Description of Figure 18-21 follows
    Description of "Figure 18-21 Business Event Filter"

    The expression you created appears in the Filter column of the Create Mediator dialog.

  12. Click OK.

18.4.6.2 What Happens When You Create an Oracle Mediator for an Event Subscription

The Oracle Mediator files that define an event subscription interaction are generated under the specified application and project in the Application Navigator, and the new Oracle Mediator appears in the Mediator Editor in Design view. A WSDL file is also generated with the same name as the Oracle Mediator.

When you view the Oracle Mediator component in the SOA Composite Editor, the icon on the left side of the Oracle Mediator indicates that this Oracle Mediator is configured for an event subscription, as shown in Figure 18-22.

Figure 18-22 Oracle Mediator Component Created with the Subscribe to Events Template

Description of Figure 18-22 follows
Description of "Figure 18-22 Oracle Mediator Component Created with the Subscribe to Events Template"

When you double-click the Oracle Mediator, the Mediator Editor appears, as shown in Figure 18-23.

Figure 18-23 Event Subscription Oracle Mediator in the Mediator Editor

Description of Figure 18-23 follows
Description of "Figure 18-23 Event Subscription Oracle Mediator in the Mediator Editor"

18.4.7 What You May Need to Know About the Mediator Editor

This section provides information you should know about creating an Oracle Mediator service component.

18.4.7.1 Resequencing

The resequencing feature of the Oracle Mediator reorders sets of messages that might arrive to the Oracle Mediator in the wrong sequence. You can define resequencing for all operations in an Oracle Mediator or for a specific operation. The resequencer provides three resequencing strategies that reorder incoming messages based on the type of sequencing information they contain.

For more information about resequencing in Oracle Mediator, see Chapter 18, "Getting Started with Oracle Mediator."

18.4.7.2 Routing Rules

Routing rules are mediation logic or execution logic that you define to achieve the requisite mediation. Below is an overview of the routing rule features; for more information about defining routing rules, see Section 19.2, "Defining Routing Rules."

You can specify the following to create a routing rule:

  • Operation or Event

    A routing rule can be triggered either by a service operation or an event subscription. The service operation can be synchronous, asynchronous, or one-way.

  • Java Callouts

    Java callouts perform external Java logic at various points in the execution of the Oracle Mediator.

  • Static Routing Rule

    A static routing rule is not expected to change depending on the invocation context. In this case, the routing can be an echo, a routing to another service, or a publishing of an event.

    Static routing rules include the following information:

    • Request Handler

      This defines how Oracle Mediator handles incoming requests.

    • Reply Handler

      This defines how the synchronous response from the called service is handled by Oracle Mediator.

    • Fault Handler

      This defines how the named or declared faults from the called service are handled by Oracle Mediator.

    • Callback Handler

      This defines how the asynchronous response and callback from the called service are handled by Oracle Mediator.

    • Timeout Handler in Callback

      This defines how long Oracle Mediator waits for the asynchronous response and callback before performing timeout handling for the particular asynchronous request.

    • Event Publishing and Service Invocation

      This calls other services or publishes an event depending on the configuration of the handlers.

    • Sequential or Parallel Execution

      Each routing rule execution can be configured to be either sequential (that is, running in the same thread) or parallel (that is, running in different threads).

      Note:

      For synchronous service invocations, the routing rule should always be sequential.
    • Filter Expression

      This defines a filter to be applied to the message before a rule is executed. Filters use XPath standards and enable selective execution of Oracle Mediator routing rules.

    • Semantic Validation

      This uses the Schematron validation standard to define semantic validation of incoming requests. Semantic validation also verifies that the data is correct.

    • Transformation

      This transforms incoming data to a format that is compliant with the called services or published events. Transformation is based on XSL transformation standards.

    • Assign

      This manipulates headers and properties for a message to meet the requirements of the called service.

  • Dynamic Routing Rule

    A dynamic routing rule lets you externalize the routing logic to an Oracle Rules Dictionary, which in turn enables dynamic modification of the routing logic in a routing rule. This feature depends on a decision service and Oracle Rules to obtain the routing logic at runtime.

Note:

Oracle recommends using a Unicode database with AL32UTF8 as the database character set for full globalization support in Oracle Mediator.

18.5 Generating a WSDL File

You can generate the WSDL file for a message using an XML schema definition (XSD) file or using a sample file. When working with Oracle Mediator, you can generate a WSDL file at either of the following times:

  • When you are creating an Oracle Mediator and you select the Interface Definition from WSDL template in the Create Mediator dialog, selecting Generate WSDL from Schema(s) next to the WSDL URL field opens the Create WSDL dialog.

  • When you have an Oracle Mediator with no interface defined and you click Define Service next to the WSDL URL field in the Mediator Editor, selecting Generate WSDL from Schema(s) next to the WSDL URL field opens the Create WSDL dialog.

The Create WSDL dialog populates standard fields, such as the file name, directory, and namespace; and the dialog changes depending on the interface type you select. You can specify the same or different schema files for the message inputs.

18.5.1 How to Generate a WSDL File

The way you configure a WSDL file depends on the type of interface being defined by the WSDL file. You can define a one-way interface, a synchronous interface, or an asynchronous interface.

To generate a WSDL file for a one-way interface from an XSD file:

Perform these steps after the Create WSDL dialog appears when you are creating an Oracle Mediator component or when you are defining a service for an Oracle Mediator component.

  1. On the Create WSDL dialog, accept the default values or enter the following information for the WSDL file:

    • File Name: A unique name for the WSDL file.

    • Directory: The directory where you want to store the WSDL file. By default, it is stored in the same location as the Oracle Mediator file. This must be the current project directory or one of its subdirectories. If the specified directory does not exist, Oracle JDeveloper creates it.

    • Namespace: A namespace address for the WSDL file; for example, http://oracle.com/esb/namespaces/Mediator.

      The namespace that you specify is defined as the tns namespace in the WSDL file.

    • Port Type: The name of the port type in the WSDL file that contains the operation to use.

    • Operation: The name of the action to perform; for example, executeQuery.

      Note:

      Spaces and special characters are not allowed in an operation name or port type. Only alphabetic and numeric characters are supported, and the first character cannot be a number.
  2. In the Interface Type field, select One-Way Interface.

    The Input field appears, as shown in Figure 18-24.

    Figure 18-24 Create WSDL Dialog for a One-Way Interface

    Description of Figure 18-24 follows
    Description of "Figure 18-24 Create WSDL Dialog for a One-Way Interface"

  3. To the upper right of the Input field, click Add a new message part.

    The Add Message Part dialog appears, as shown in Figure 18-25.

    Figure 18-25 Add Message Part Dialog

    Description of Figure 18-25 follows
    Description of "Figure 18-25 Add Message Part Dialog"

  4. In the Part Name field, enter a name for the message part.

  5. To the right of the URL field, click the browse for schema file icon to browse for the URL.

    The Type Chooser dialog appears and contains a list of the schema files (XSD files), as shown in Figure 18-26.

    Figure 18-26 Type Chooser Dialog

    Description of Figure 18-26 follows
    Description of "Figure 18-26 Type Chooser Dialog"

  6. Expand the Type Explorer tree to locate and select the schema element to use.

    If the schema you want to use is not located in the project in which you are working, you can import a schema XSD file or WSDL file into the project using the Import Schema File or Import WSDL icon in the upper right corner of the dialog.

    Note:

    If you want to use a schema XSD file that resides on your local file system, ensure that the XSD file and any XSD files that it imports all reside in the Oracle JDeveloper project directory. This ensures that the schema is deployed with the project and is made available at runtime.

    After you specify a file, Oracle JDeveloper parses it to determine the defined schema elements and displays them in a list from which you select.

  7. Select the root element of the XSD file and click OK.

    The Add Message Part dialog reappears with the URL and Schema Element fields populated from the Type Chooser dialog. If you selected an XSD simple type, these fields are replaced by a Simple Type field.

  8. Click OK on the Add Message Part dialog.

    The input information appears in the Input field of the Create WSDL dialog.

  9. If needed, repeat the above steps to define additional message parts.

  10. Click OK.

    Note:

    Partner link types are generally used in BPEL, so you do not need to select Generate partnerlinkType extension for Oracle Mediator.

To generate a WSDL file for a synchronous interface from an XSD file:

Perform these steps after the Create WSDL dialog appears when you are creating an Oracle Mediator component or when you are defining a service for an Oracle Mediator component.

  1. On the Create WSDL dialog, enter the following information for the WSDL file:

    • File Name: A unique name for the WSDL file.

    • Directory: The directory where you want to store the WSDL file. By default, it is stored in the same location as the Oracle Mediator file.

    • Namespace: A namespace address for the WSDL file; for example, http://oracle.com/esb/namespaces/Mediator.

      The namespace that you specify is defined as the tns namespace in the WSDL file.

    • Port Type: The name of the port type in the WSDL file that contains the operation to use.

    • Operation: The name of the action to perform; for example, executeQuery.

      Note:

      Spaces and special characters are not allowed in an operation name or port type. Only alphabetic and numeric characters are supported, and the first character cannot be a number.
  2. In the Interface Type field, select Synchronous Interface.

    The Input, Output, and Fault fields appear, as shown in Figure 18-27.

    Figure 18-27 Create WSDL Dialog for a Synchronous Interface

    Description of Figure 18-27 follows
    Description of "Figure 18-27 Create WSDL Dialog for a Synchronous Interface"

  3. To the upper right of the Input field, click Add a new message part.

    The Add Message Part dialog appears, as shown in Figure 18-28.

    Figure 18-28 Add Message Part Dialog

    Description of Figure 18-28 follows
    Description of "Figure 18-28 Add Message Part Dialog"

  4. In the Part Name field, enter a name for the message part.

  5. To the right of the URL field, click the browse for schema file icon to browse for the URL.

    The Type Chooser dialog appears and contains a list of the schema files (XSD files), as shown in Figure 18-29.

    Figure 18-29 Type Chooser Dialog

    Description of Figure 18-29 follows
    Description of "Figure 18-29 Type Chooser Dialog"

  6. Expand the Type Explorer tree to locate and select the schema element to use.

    If the schema you want to use is not located in the project in which you are working, you can import a schema XSD file or WSDL file into the project using the Import Schema File or Import WSDL icon in the upper right corner of the dialog.

    Note:

    If you want to use a schema XSD file that resides on your local file system, ensure that the XSD file and any XSD files that it imports all reside in the Oracle JDeveloper project directory. This ensures that the schema is deployed with the project and is made available at runtime.

    After you specify a file, Oracle JDeveloper parses it to determine the defined schema elements and displays them in a list from which you can make a selection.

  7. Select the root element of the XSD file and click OK.

    The Add Message Part dialog reappears with the URL and Schema Element fields populated from the Type Chooser dialog. If you selected an XSD simple type, these fields are replaced by a Simple Type element.

  8. Click OK on the Add Message Part dialog.

    The input information appears in the Input field of the Create WSDL dialog.

  9. Repeat the above steps to define message parts for the Output and Fault fields.

    The output represents the response message and is required in synchronous transactions. Faults are optional.

  10. Click OK.

    Note:

    Partner link types are generally used in BPEL, so you do not need to select Generate partnerlinkType extension for Oracle Mediator.

To generate a WSDL file for an asynchronous interface from an XSD file:

Perform these steps after the Create WSDL dialog appears when you are creating an Oracle Mediator component or when you are defining a service for an Oracle Mediator component.

  1. On the Create WSDL dialog, enter the following information for the WSDL file:

    • File Name: A unique name for the WSDL file.

    • Directory: The directory where you want to store the WSDL file. By default, it is stored in the same location as the Oracle Mediator file.

    • Namespace: A namespace address for the WSDL file; for example, http://oracle.com/esb/namespaces/Mediator.

      The namespace that you specify is defined as the tns namespace in the WSDL file.

    • Port Type: The name of the port type in the WSDL file that contains the operation to use.

    • Operation: The name of the action to perform; for example, executeQuery.

      Note:

      Spaces and special characters are not allowed in an operation name or port type. Only alphabetic and numeric characters are supported, and the first character cannot be a number.
  2. In the Interface Type field, select Asynchronous Interface.

    The Input field and Callback section appear, as shown in Figure 18-30.

    Figure 18-30 Create WSDL Dialog for an Asynchronous Interface

    Description of Figure 18-30 follows
    Description of "Figure 18-30 Create WSDL Dialog for an Asynchronous Interface"

  3. To the upper right of the first Input field, click Add a new message part.

    The Add Message Part dialog appears, as shown in Figure 18-31.

    Figure 18-31 Add Message Part Dialog

    Description of Figure 18-31 follows
    Description of "Figure 18-31 Add Message Part Dialog"

  4. In the Part Name field, enter a name for the message part.

  5. To the right of the URL field, click the browse for schema file icon to browse for the URL.

    The Type Chooser dialog appears and contains a list of the schema files (XSD files), as shown in Figure 18-32.

    Figure 18-32 Type Chooser Dialog

    Description of Figure 18-32 follows
    Description of "Figure 18-32 Type Chooser Dialog"

  6. Expand the Type Explorer tree to locate and select the schema element to use.

    If the schema you want to use is not located in the project in which you are working, you can import a schema XSD file or WSDL file into the project using the Import Schema File or Import WSDL icon in the upper right corner of the dialog.

    Note:

    If you want to use a schema XSD file that resides on your local file system, ensure that the XSD file and any XSD files that it imports all reside in the Oracle JDeveloper project directory. This ensures that the schema is deployed with the project and is made available at runtime.

    After you specify a file, Oracle JDeveloper parses it to determine the defined schema elements and displays them in a list from which you can make a selection.

  7. Select the root element of the XSD file and click OK.

    The Add Message Part dialog reappears with the URL and Schema Element fields populated from the Type Chooser dialog. If you selected an XSD simple type, these fields are replaced by a Simple Type element.

  8. Click OK on the Add Message Part dialog.

    The input information appears in the Input field of the Create WSDL dialog.

  9. Repeat the above steps to define the input message parts for the Callback section.

    Note:

    The callback input represents the response message and is required in asynchronous transactions.
  10. In the Callback section, specify the following information for the response message:

    • Port Type: The name of the port type in the WSDL file that contains the operation to use.

    • Operation: The name of the action to perform; for example, executeResponse.

      Note:

      Spaces and special characters are not allowed in an operation name or port type. Only alphabetic and numeric characters are supported, and the first character cannot be a number. Both of these fields are required.
  11. Click OK.

    Note:

    Partner link types are generally used in BPEL, so you do not need to select Generate partnerlinkType extension for Oracle Mediator.

To generate the WSDL file based on a sample file:

You can generate a WSDL file from a file in a native format such as a comma-separated value (CSV) file, a fixed-length file, a document type definition (DTD) file, or a COBOL copybook file. Use the Native Format Builder wizard to generate a WSDL file based on a sample file. The Native Format Builder wizard appears when you click Define Schema for Native Format in the Request, Response, Fault, and Callback tabs of the Create WSDL dialog. A WSDL file is generated after you complete the wizard.

For information about the Native Format Builder wizard, see the Oracle Fusion Middleware User's Guide for Technology Adapters.

18.6 Specifying Operation or Event Subscription Properties

After creating an Oracle Mediator, you can use the Mediator Editor to select the Validate Syntax (XSD) checkbox for an operation or event subscription. You can select this option to validate the schemas of the inbound messages. By default, this checkbox is not selected.

18.7 Modifying an Oracle Mediator Service Component

You can modify the operations or event subscriptions of an Oracle Mediator using the Mediator Editor.

18.7.1 How To Modify Operations of an Oracle Mediator

You can modify an Oracle Mediator WSDL file by adding or deleting operations. After modifying the WSDL file, use the Refresh WSDL dialog to synchronize the changes.

To modify the operations of an Oracle Mediator:

  1. In the Mediator Editor, click the Refresh operations From WSDL icon to the right of the WSDL URL field.

    The Refresh WSDL dialog appears. If you have made any modifications to the WSDL file, the Refresh WSDL dialog lists all the operations to delete or add. The Refresh will delete Mediator operation field lists all the operations that have been removed from the WSDL file. The Refresh will add Mediator operation field lists all the new operations that have been added in the WSDL file. Figure 18-33 shows the Refresh WSDL dialog.

    Figure 18-33 Refresh WSDL Dialog

    Description of Figure 18-33 follows
    Description of "Figure 18-33 Refresh WSDL Dialog"

  2. To specify a different WSDL file, click Find existing WSDLs to the right of the WSDL URL field to use an existing WSDL file or Generate WSDL From schema(s) to create a new WSDL file.

    The Refresh WSDL dialog is updated based on the operations defined in the specified WSDL file.

  3. Click OK.

  4. From the File menu, select Save All.

18.7.2 How To Modify Event Subscriptions of an Oracle Mediator

You can subscribe to new events, modify existing event subscriptions, and unsubscribe from subscribed events using the Manage Event Subscriptions option in the Mediator Editor.

To modify event subscriptions of an Oracle Mediator:

  1. In the Mediator Editor, click the Manage Event Subscriptions icon to the right of Event Subscriptions.

    The Subscribed Events dialog appears, as shown in Figure 18-34.

    Figure 18-34 The Subscribed Events Dialog

    Description of Figure 18-34 follows
    Description of "Figure 18-34 The Subscribed Events Dialog"

  2. You can perform any of the following functions:

  3. Click OK.

  4. From the File menu, select Save All.