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

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.

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.

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.

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.

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.

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.

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.

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:

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

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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.

Click OK on the Add Message Part dialog.

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

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

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.

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.

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.

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.

Click OK on the Add Message Part dialog.

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

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.

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.

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.

In the Interface Type field, select Asynchronous Interface.

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

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.

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.

Click OK on the Add Message Part dialog.

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

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.

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.

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.

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.7Modifying an Oracle Mediator Service Component

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

18.7.1How 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:

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 deleteMediator operation field lists all the operations that have been removed from the WSDL file. The Refresh will addMediator operation field lists all the new operations that have been added in the WSDL file. Figure 18-33 shows the Refresh WSDL dialog.