Mediation services overview

Mediation service applications intercept and modify messages that are passed between existing services (providers) and clients (requesters) that want to use those services. Mediation services are implemented using mediation modules that contain mediation flows.

Mediation modules can be deployed on the WebSphere® Enterprise Service Bus or the WebSphere Process Server.

In service-oriented architecture (SOA), services represent business functions that can be reused and combined in an ad hoc manner to create responsive business systems. These services have loosely coupled connections, rather than being connected directly to each other.

Introducing mediation flows between services enables you to process the messages that are being passed between these services. A message is a communication sent from one application or service to another application or service. Mediation flows provide the logic that processes the messages. For example, mediation flows can be used to find services with specific characteristics that a requester is seeking and to resolve interface differences between requesters and providers. For complex interactions, mediation primitives can be linked sequentially. Typical mediations include:
The concepts and terms described in this topic will help you understand how to build a mediation service application with WebSphere Integration Developer:

Stock Quote example: building a mediation service

To illustrate the concepts covered in this topic, we will use an example of a simple mediation service that provides stock quotes. A client application provides a query containing a stock symbol and customer ID to the mediation service, which processes the query. The customer's subscription level is determined, and depending on the level of subscription, the query is routed to the appropriate service provider. The quote that is returned from the service provider is converted into the customer's preferred currency before it is returned to the client application.

We are using a mediation service because we want to use different interfaces from two external service providers, and expose a single interface to the client application. We also need to build the service quickly, with the ability to change on demand, and without modeling a business process.

The following picture shows the complete mediation service:
Picture showing the required application

Mediation modules

Mediation service applications are assembled and deployed as one or more mediation modules. A mediation module can have the following parts:
  • A mediation flow component
  • Imports that identify service providers and their interfaces
  • Exports that expose the mediation module to service requesters
  • Java™ components that implement custom mediation primitives invoked by the mediation flow component

Stock Quote example

In the stock quote example, these are the parts in the mediation module, as seen in the Assembly editor.


Picture of Stock Quote example mediation module
  • StockQuoteService is the export that allows client requesters to invoke this mediation module as a service.
  • StockQuote_MediationFlowComponent is the mediation flow component that accepts a customer ID and symbol as input, processes the message, and returns the quote in the currency preferred by the customer.
  • DelayedService is the import that provides access to the external standard service.
  • RealtimeService is the import that provides access to the external premium service.

Interfaces and references

Services provide access to their business functions through interfaces, so that the service can be used or invoked. Mediation modules and business integration modules have interfaces in their exports, so that the module can be invoked. The interface defines the operations that can be called and the data that is passed, data such as input arguments, returned values, and exceptions. In mediation flow components, this data is passed in the form of messages.

In a mediation flow component, the interface that allows the service requester to access the mediation through an export is called a source interface.

A mediation flow component accesses a service provider (or import) through a reference which specifies the interface that is used by the import to invoke the service. In a mediation flow component, this reference is called a target reference.

Stock Quote example

These are the interfaces and references that are used in the Stock Quote example:


Picture of interfaces and references in the Stock Quote sample

  1. StockQuoteService is the export interface that allows the requester to invoke the mediation module. In the mediation flow, StockQuoteService is the source interface. It provides the getQuote operation that sends a business object, StockQuoteRequest, as input and returns a business object, StockQuoteResponse, as output.
  2. DelayedService is the import interface that provides access to the premium service provider.
  3. RealtimeService is the import interface that provides access to the standard service provider.
  4. DelayedServicePartner is the reference that specifies the interface of import DelayedService, which provides access to the standard service provider's interface.
  5. RealtimeServicePartner is the reference that specifies the interface of import RealtimeService, which provides access to the premium service provider's interface.

Mediation flow components

A mediation flow component in the Assembly editor has the following parts:
  • One or more interfaces that describe how to invoke this mediation flow. These interfaces have to match those of the exports that will be wired to this mediation flow.
  • Zero or more named references that specify the interfaces of partners that this flow wants to invoke. The actual partners are not known by the flow, only their interfaces. These references are wired to actual partners, that are imports or Java components, with matching interfaces.
  • Mediation flows, which define the implementation of the component.

Stock Quote example

In the stock quote example, StockQuote_MediationFlowComponent is the mediation flow component that accepts a customer ID and symbol as input, processes the message, and returns the quote in the currency preferred by the customer. These are the parts of the mediation flow component


Picture of Stock Quote example mediation flow component
  1. StockQuoteService is the interface that allows access to the client application's operations.
  2. DelayedServicePartner is the reference that specifies the interface of import DelayedService, which provides access to the standard service provider's interface.
  3. RealtimeServicePartner is the reference that specifies the interface of import RealtimeService, which provides access to the premium service provider's interface.

Mediation flows

A mediation flow consists of a sequence of processing steps that are executed when an input message is received. A mediation flow is created in the Mediation Flow editor by including a number of mediation primitives that define processing steps. Connections represent the flow of the message between the mediation primitives.

The definition of a mediation flow begins with a source operation:
  • Flows process messages from source operations and responses from target operations. In the top section of the Mediation Flow editor, a source operation can be visually connected to one or more target operations. This indicates that the source operation will send a message to the target operations, which send a response to the caller of the source operation. These flows include a request flow and a response flow.
  • Source operations do not need to be connected to target operations if they don't intend to receive a response. In this case, only a request flow is created, and the message is returned directly to the source operation after processing.
In the Mediation Flow editor, flows are represented from left to right. The flow of the outgoing message from the source to the targets is a request flow, and the flow of the returning message from the targets to the source is a response flow. When multiple targets return a response, the returning messages are processed into a single message, which is then returned to the source.
  • A request flow begins with a single input node for the source operation, followed by one or more mediation primitives in sequence and a callout node for each target operation, all wired together. If a message is to be returned to the source directly after processing, it can be wired to an input response node in the request flow. If fault messages are defined in the source operation, an input fault node is also created.
  • A response flow begins with a callout response node for each target operation, followed by one or more mediation primitives in sequence and a single input response node representing the source operation, all wired together. If fault messages are defined in the source operation, an input fault node is also created. If fault messages are defined in the target operation, a callout fault node is also created. Errors that are returned by the operation but are not defined as fault messages are propagated to the fail terminal of the callout response node. Response flows for request-only operations consist of a callout response node that has a fail terminal to handle faults, and no output terminal.

Stock Quote example

In the Stock Quote example, the mediation flow is defined by the following operation connections:

Picture of connection between source and target operations
  • The getQuote operation of the source interface is connected to the getQuote operations of DelayedServicePartner and RealtimeServicePartner.

See the topics "Mediation Flow editor" and "Building mediation flows" under related links for more information.

.

Mediation primitives

Mediation flows consist of a sequence of mediation primitives, which define processing steps. A mediation primitive receives a message, processes it and propagates the processed message to the next primitive or node in the flow. For example, a Database Lookup primitive retrieves a value from a database and sets it in the message. A ready-made set of mediation primitives is available from the Mediation Flow editor palette. If you need mediation capabilities that are not provided by this set of primitives, you can create custom mediation primitives to call your own Java implementation or an imported service. Mediation primitives have terminals which receive and propagate messages. For example, these are the terminals of a Message Logger:Message logger in the mediation flow editor canvas

  • The input terminal on the left receives the message
  • The output terminal on the top right propagates the message on successful processing to the next primitive or node in the flow
  • The fail terminal on the bottom right propagates the message and failure information when an execution failure occurs in the primitive.
For more information, see these topics:
  • "Mediation Flow editor" under related concepts
  • "Building mediation flows" under related tasks.

Service message objects

As defined earlier, a message is a communication sent from one application or service to another application or service. Messages in mediation flows are represented as service message objects (SMOs) .

Service message objects are enhanced business objects that include the application data and header information related to the transport protocol used to invoke a service such as SOAP or JMS. A service message object is composed of a body that contains the application data (also known as the payload or operation message) in a business object, and headers containing additional context information. You can use XPath 1.0 expressions to access elements in a message. The following picture represents a service message object:


Picture of service message object
  1. context: is the message context where information that is unrelated to the payload is stored. The context has these elements.

    correlation
    makes the property persist throughout the duration of the request and response flows, and is used for passing values from the request flow to the response flow.
    transient
    makes the property available for the duration of the current flow (either the request flow or the response flow), and is used to pass values between mediation primitives in the same flow.
    failInfo
    contains exception information about execution failure in a mediation primitive; it contains the message exception chain, and identifies the primitive where the failure occurred. This information is propagated to the fail terminal.
    primitiveContext
    contains context information for primitives.
    • EndpointLookupContext contains the result of a WebSphere Service Registry and Repository query.
      • endpointReference contains the information needed to access the service endpoint.
      • registryAnnotations contains information for the user-defined properties.

  2. Headers contain header information associated with the message. These are the elements in the headers section:

    SMOHeader
    contains information that defines the message; such as the unique message id, message version and message type. An SMO header is always present in a service message object.
    • Target contains the dynamic endpoint used by the runtime if the Use dynamic endpoint property is set and there is a valid endpoint in the field.
      • address the address of the target.
    JMSHeader
    contains JMS headers, when a JMS import or export binding is used.
    SOAPHeader
    contains SOAP header information when a web services import or export binding is used.
    SOAPFaultInfo
    contains information about SOAP faults; fault code, fault string etc.
    Properties[]
    properties put in the message header by the application
    MQHeader
    contains WebSphere MQ header information, when an MQ binding is used.

  3. Body contains the application data in a business object. Application data is also known as the payload, or operation message type.
In WebSphere Integration Developer, service message objects are used only within mediation flows. Other components consume and transmit business objects, which are transformed into service message objects when they enter a mediation flow component. On leaving the mediation flow component, the service message object is transformed back into business objects.
  • See "Building XPath expressions" in the topic "Building mediation flows" under related tasks for an example of the relationship between a business object in an interface and an XPath 1.0 condition.
  • See topics "SMO Body" and "SMO Structure" under related references below.

XPath

Most mediation primitives have properties that are specified using an XPath 1.0 expression; for example the root property takes an XPath 1.0 expression which specifies the part of the message that is available to the primitive for processing. You can also use an XPath 1.0 expression to identify one or more fields in a message, and use these fields to filter or select by specifying a value.

See "Building XPath expressions" in the topic "Building mediation flows" under related tasks for an example of the relationship between a business object in an interface and an XPath 1.0 condition.

Message transformation

Typically, interfaces and operations of disparate services are not identical, and the service message object from the source needs to be transformed into a format that can be accepted by the target. An XSL transformation mediation primitive is required when the source and target message types are different.

To transform the message in the Mediation Flow editor, define the scope of the message to be transformed with an XPath 1.0 expression. Then, map the source and target service message objects, using the XML Mapping editor.

For more information see:
  • "Creating mappings for the XSL Transformation primitive" in under related tasks for more information.
  • Rational® Application Developer topic Mapping between XML files
Related concepts
Mediation Flow editor
Related tasks
Creating a mediation flow
Opening the Mediation Flow editor
Building mediation flows
Emitting common base events
Creating mappings for the XSL Transformation primitive
Selecting endpoints dynamically
Implementing custom mediation logic
Storing and using properties in the message context
Changing the value of mediation flow properties at runtime
Testing and debugging mediation modules
Related reference
Error handling in the mediation flow
Considerations when refactoring mediation flow artifacts
SMO Body
SMO Structure

Related information

Tutorial: Create a mediation flow
Samples: Mediation Flow editor
Contributing your own mediation primitive plug-in

Feedback
(C) Copyright IBM Corporation 2005, 2006. All Rights Reserved.