Components and mediation modules

Mediation services 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 intercept and modify messages that are passed between services. 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:
Before you start to build a mediation module, you need to understand the terms and concepts in this topic.

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.

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 going through a top-down modeling of a business process.

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

Components

Components are services that provide an implementation. The WebSphere Integration Developer tools generate implementations that the assembly editor can use for components. In a mediation module, the implementation can include mediation flow and Java. However, a Java component cannot be wired directly to an export, it can only be called by a mediation flow component. The structure of a component is simple; it has the following parts:
  • An implementation.
  • One or more interfaces
  • Optionally, one or more partner references

The components generated by WebSphere Integration Developer tools and used by the assembly editor are Service Components Architecture (SCA) components. SCA defines a technology-independent format for describing component implementations, so that assembling components to build an application does not require knowledge of the language and technology of the implementation of the component.

Stock Quote example

In the stock quote example, a mediation flow component provides the required mediation logic:
  • StockQuote_MediationFlow is the mediation flow component that accepts a customer ID and stock symbol as input and retrieves the customer's subscription level and preferred currency from a database. Depending on the subscription level, it invokes a service provider to obtain the requested quote.

Assembly editor notes:

When you are using the assembly editor, the component appears as a rectangle on the canvas, as shown here:
component in the assembly editor

The component is created by the assembly editor under the following situations:
  • When you select a component from the palette and drop it onto the canvas
  • When you drag an interface onto the canvas
  • When you drag an implementation onto the canvas

Each component has a name and a display name. (The display name is used by various runtime functions.) By default, the two names are the same, although you can name them independently. The context menu for the assembly editor canvas has a toggle setting that allows you to display or hide the display names in the assembly diagram. Here is the component with the display name visible:
component with display name

See "Adding and wiring components" under related tasks for more information on how to create a component.

Implementation

The component's implementation specifies the execution logic. A mediation module can include implementation for two types of components:
  • Mediation Flow
  • Java
Note: There can be only one mediation flow component in a mediation module.

See the "Assembly editor" under related reference for more information on component implementation types.

Stock Quote example

In the example, the mediation flow component requires implementation that performs the processing; StockQuote_MediationFlow retrieves the customer's subscription level, performs processing, routes the request to the appropriate service provider, and returns the quote to the client application.

Assembly editor notes:

When working in the assembly editor, the component's implementation type is represented by an icon in the component. The following image shows the StockQuote_MediationFlow component which has a mediation flow implementation type:
Mediation flow component in the assembly editor

If the component's implementation does not exist, the component will have an exclamation mark in the lower left corner, as shown in the above StockQuote_MediationFlow component. You use the options available in the context menu to generate implementation for the component.

See "Working with implementations" under related tasks at the end of this topic for further instructions on how to change the component's implementation type and generate the implementation.

If the implementation already exists, then there is no exclamation mark, as shown in the following image of the StockQuote_MediationFlow component:
Mediation flow component with an existing implementation

You can drag one of the implementations (for example, a mediation flow) from the same module onto the canvas of the assembly editor and the component will be created for you. The component will show its implementation type with no exclamation mark to indicate that the implementation exists.

Also, you can set qualifiers on the component's implementation. The qualifiers provide “quality of service” support (such as transaction support or security) required from the hosting container. See the related links for more information on qualifiers.

Interface

A component exposes business-level interfaces to its application business logic so that the service can be used or invoked. The interface of a component defines the operations that can be called and the data that is passed, such as input arguments, returned values, and exceptions. An import and export also have interfaces so that the published service can be invoked.

All the components have WSDL type interfaces. Only Java components support Java type interfaces in addition to WSDL type interfaces. If a component, import, or export has more than one interface, all the interfaces must be the same type. See "WSDL and Java interfaces and references" and "Adding interfaces" under the related topics for more information.

A component can be called synchronously or asynchronously; this is independent of whether the implementation is synchronous or asynchronous. The interfaces on the component are defined in the synchronous form and asynchronous support is also generated for them. For an interface, you can specify a preferred interaction style as synchronous or asynchronous. The asynchronous type advertises to users of the interface that it contains at least one operation which may take a significant time to complete. As a consequence, the calling service should avoid keeping a transaction open while waiting for the operation to complete and send its response. The interaction style applies to all the operations in the interface.

You can also apply a role-based permission qualifier on an interface so that only authorized applications can invoke the service using that interface. If the operations require different levels of permission for their use, you will need to define separate interfaces to control their access. See the related links for more details on qualifiers.

Stock Quote example

In the stock quote example, the mediation flow component, export and import must have interfaces so that they can be used by other components. Here is a description of these interfaces:
  • StockQuoteService interface allows to the client service to invoke the mediation flow..
  • DelayedServicePortType is the external service provider's interface.
  • RealtimeServicePortType is the other external service provider's interface.

Assembly editor notes:

In the assembly editor, the component's interfaces are represented by a single icon, interface icon, on the left side of the component. The following image shows the StockQuote_MediationFlow component which has one or more interfaces defined:
component in the assembly diagram

When you drag an implementation onto the assembly editor's canvas to create a new component, the interface of the implementation is automatically added to the component. You can create the component first and then add the interface to it. See "Adding and wiring components" for instructions on how to add interfaces to a node.

Partner reference

A partner reference is required when one component uses another component; it is defined on the component that wants to use another component. The partner reference (sometimes referred to as a reference) specifies the interface that is used in the invocation of the other component. The partner reference also contains wires that specify the target components that can be used. See "Adding and wiring components" under related tasks for more information on adding partner references to nodes.

Assembling the components for the application involves creating partner references, interfaces, and the wiring of components in the module assembly. The result is an assembly diagram that represents the modeled solution.

Stock Quote example

In the stock quote example, the StockQuote_MediationFlow component uses the services of two imports. It has two partner references:
  • One to the interface on the target import, DelayedService
  • One to the interface on the target import, RealtimeService

Assembly editor notes:

In the assembly editor, the component's partner references are represented by small blocks on the right side of the component. The block contains the number of wires that are allowed in the partner reference; the numbers are either 1..1 or 0..n to indicate one wire or 0 to n number of wires, respectively. The following image shows the StockQuote_MediationFlow component which has three partner references:
StockQuote_MediationFlow component in the assembly editor

If there are many partner references for your component, you can collapse them. As shown here, CustomerQuery component's two partner references have been collapsed:


Component with collapsed partner references

Select the partner reference on the node and right-click to invoke the Collapse References and Expand References actions to collapse and expand them, respectively.

Wire

A wire allows you to assemble components into an integrated application by identifying target services. The target of a wire must support the interface or interfaces that the source specifies.

There are two types of wires. The first type of wire comes from a partner reference (the source) that is defined for a component or stand-alone references and goes to a component or import (the target). In this case, the wire identifies the component or import (target) that is accessed when the source component uses that partner reference. By default, a partner reference only allows one wire leading from it unless the partner reference's multiplicity property is changed to 0...n.

The second type of wire comes from an export (the source) and goes to a component or import (the target). In this case, the wire identifies the (target) component that provides the service. An export can only have one wire leading out of it.

Stock Quote example

For our stock quote example, the StockQuote_MediationFlow component has two partner references and the wires point to the target imports that have the referenced interfaces. Here is part of the assembly diagram showing the three elements wired together:
Module assembly shown in the assembly editor

Assembly editor notes:

You can wire components together by hovering your mouse over the source component or partner reference to display the handle and then dragging the handle to connect to the target component. Here is a component with the handle displayed for wiring:


StockQuote_MediationFlow component with handle displayed

You can also use the editor's wire action to automatically wire components together. To learn about the wiring action, see "Adding and wiring components" and the tutorial listed at the end of this topic.

Mediation Module

Components are assembled in the mediation module, which is a basic unit of deployment in the WebSphere Process Server. The mediation module assembly contains a diagram (referred to as the assembly diagram) of the integrated business application, consisting of components and the wires that connect them. You use the assembly editor to visually compose the mediation service by using elements that you drag from the palette or from the tree in the Business Integration view.

Stock Quote example

For our stock quote example of creating a mediation service application to get a stock quote for a customer, we can create a mediation module whose wired components in the module assembly may look like the following diagram in the assembly editor:
Module assembly shown in the assembly editor

The implementations of components that are used in a module's assembly reside within the module. Components belonging to other modules can be used through imports, which are described later in this topic. Components in different modules can be wired together by publishing the services as exports that have their interfaces, and then dragging the exports into the required assembly diagram to create imports.

When wiring components, you can also specify quality of service qualifiers on the implementations, partner references, and interfaces of the component. For more information on qualifiers, see the related links at the end of this document.

Export

An export is a published interface from a component or import to offer its business service to the outside world, for example, as a Web service. Exports have interfaces that are the same as or a subset of the interfaces of the component or import that they are associated with so that the published service can be called. An export dragged from another module into an assembly diagram will automatically create an import. To share the interfaces between modules, put the interfaces into a library. Then, for both modules, add a dependency on the library to use its resources. See related tasks for more information on dependencies.

Stock Quote example

In the stock quote example, we can make the StockQuote_Meditionflow component's service available to other modules by an export. The following image shows the export, StockQuoteService, which uses the StockQuote_Meditionflow component's interface:


the CustomerQueryExport in the assembly diagram

Assembly editor notes:

The export is created by the assembly editor under the following situations:
  • When you select the export from the palette and drop it onto the canvas
  • When you select a component on the canvas and right-click to select Export
  • When you drag an interface onto the canvas

Exports that are shown under the module assembly in the Business Integration view can be used to create imports in other modules.

If an export in a module assembly does not have any binding, when deployed, SCA binding is assumed. For bindings information, see the Generating bindings for imports and exports topic under related tasks.

Stand-alone references

Applications that are not defined as SCA components (for example, JavaServer Pages) can still invoke SCA components; they do so through the use of the stand-alone references. Stand-alone references contains partner references that identify the components to call. On its own, a stand-alone reference does not have any implementation or interface.
Note: You can have, at most, one stand-alone references node in an assembly diagram.

Stock Quote example

In our Stock Quote example, we can add a stand-alone reference to provide access to the StockQuote_MediationFlow component. As a result, we can create JavaServer Pages to use the stand-alone reference to access StockQuote_MediationFlow. In the assembly editor, the node for the stand-alone reference has an arrow icon, stand-alone reference icon. The following image shows the addition of the stand-alone reference to access the StockQuote_MediationFlow component:


Stand-alone References in the assembly editor

Assembly editor notes:

The palette in the assembly editor has an icon to let you create the stand-alone references in the module assembly. You can add partner references to the stand-alone references and wire them to target components or target imports.

Imports

An import allows you to use functions that are not a part of the module that you are assembling. Imports can be from components in other modules or non-SCA components such as stateless session Enterprise JavaBeans (EJBs) and Web services. Available function (or business logic) implemented in remote systems (such as web services, EIS functions, EJBs, or remote SCA components) is modeled as an “imported service”. Imports have interfaces that are the same as, or a subset of, the interfaces of the remote service that they are associated with so that those remote services can be called. To share the interfaces between modules, put the interfaces into a library. Then, for both modules, add a dependency on the library to use its resources.

Under related concepts at the end of this topic, see "Modules and libraries dependencies" for more information on dependencies and "WSDL and Java interfaces and references" for more information on how to wire components with WSDL interfaces to EJB imports that have Java interfaces

Imports are used in an application in exactly the same way as local components. This provides a uniform assembly model for all functions, regardless of their locations or implementations.

A binding describes a protocol for calling a piece of code. The binding, then, determines how the import or export interact with clients outside the module where the import and export reside. The import binding does not have to be defined at development time; it can be done at deployment time. For bindings information, see the Generating bindings for imports and exports topic under related tasks.

Stock Quote example

The following image shows the Stock Quote mediation module as an import that is called by the CustomerQuery component.
Assembly module diagram

Assembly editor notes:

The import can be created by the assembly editor under the following situations:
  • When you select the import from the palette and drop it onto the canvas
  • When you drag an interface onto the canvas
  • When you drag an export from another module onto the canvas

For an import that is generated from an export, Web service, or EJB, the binding type of the import will be specified for you. If you are creating the import using the palette, you will have to specify a binding type for the external service technology in order to test it.

Architecture and programming details

The WebSphere Integration Developer tools generate components that implement the Service Component Architecture (SCA) programming model. The data objects generated and used by the components are Service Data Objects (SDO). Technical details are available from the following Web sites:

The component interfaces only support the automatic Java mapping of WSDL portTypes that follow the WS-I standard, that is, interfaces that have operations with single input and output part, and use document literal encoding.

Related concepts
Approaches to assembling a mediation module
Quality of service: Qualifiers for mediation services
Using Java in a mediation module
Using Java in a mediation module
Modules and libraries dependencies
Related tasks
Creating a mediation module
Opening a mediation module assembly
Setting assembly editor preferences
Adding and wiring components
Editing the properties of elements in the mediation module assembly
Adding Qualities of Service (QoS) qualifiers
Processing events in a sequence
Working with implementations
Generating bindings for imports and exports
Invoking a module from another module
Interoperability with services from other vendors
Fixing errors in the assembly diagram
Best practice: Do not make changes to J2EE staging projects
Business services: Opening a module assembly
Mediation services: Editing properties of elements in the module assembly
Adding dependencies to modules and libraries
Creating an implementation for a component
Related reference
Assembly editor for mediation modules

Related information

Tutorial: Wire components using the assembly editor
Tutorial: Create a mediation flow
Samples: Mediation Flow editor
Tutorial: Wire components using the assembly editor

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