WebSphere

Mediation primitives

Mediation primitives let you change the format, content or target of service requests.

Introduction

Mediation primitives are the building blocks of mediation flows. You create mediation flows in mediation flow components, and mediation flow components can exist in either business modules or mediation modules.

Mediation flows operate on messages that are in-flight between service requesters (service consumers) and service providers, and each mediation primitive lets you do different things with a message. For example, you can route a message or change its content. Mediation primitives process messages as service message objects (SMOs) because SMOs allow different types of messages to be processed in a more abstract way.

All mediation primitives have an input terminal (called in) that can be wired to accept a message. Most mediation primitives have one fail terminal (called fail) and one or more output terminals. However, the Stop and Fail mediation primitives have no fail terminal and no output terminals.

If an exception occurs during the processing of the input message, the fail terminal propagates the original message, together with any exception information. If an exception occurs before mediating the input message, when setting the properties of a mediation primitive, an IllegalArgumentException is thrown and the original message is not propagated.

If an output terminal of a mediation primitive is left unwired, WebSphere® Integration Developer generates a warning. At run time, the unwired output terminal stops this path in the flow without generating an exception, and the message is consumed.

Mediation flows

Mediation flows can contain request flows and response flows.

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.

Promoted properties

Mediation primitives have properties, and some of these properties can be made visible to the runtime administrator by promoting them. Certain properties lend themselves to being administratively configured. Other properties are not suitable for administrative configuration, typically because modifying them affects the mediation flow in such a way that you need to redeploy the mediation module. WebSphere Integration Developer lists the properties that you can choose to promote under the promoted properties of a mediation primitive.
Note: The callout node also has properties that can be promoted.

Promoted properties are given an alias name, and you can set the alias name so that it is meaningful in the context of a particular mediation. The alias name is the property name that is displayed on the runtime administrative console; multiple promoted properties can be given the same alias name if they are of the same type. You can set the value of a promoted property, from WebSphere Integration Developer and from the runtime administrative console.

Property groups

A promoted property belongs to a group. By default, the group name is the mediation flow component name, but you can override the default group name. At integration time, you can use property groups to create collections of properties. There is a relationship between property groups and mediation policy namespaces.

At run time, properties are displayed and administered in their groups.

Dynamic properties

Any property that you promote is also a dynamic property. If your mediation flow contains a Policy Resolution mediation primitive, then you can override a dynamic property (in another mediation primitive) using a mediation policy file. Although you can override promoted properties dynamically you must always specify a valid default value in either the mediation primitive or the callout node.
Note: A property group name is used to construct a mediation policy namespace; a property alias name must map to an assertion name in the mediation policy file.

Any mediation primitive that promotes a property is allowing the property value to be dynamically set, and the mediation primitive is said to be dynamically configurable.

Mediation policies

If you want to use mediation policies to control your mediation flows, you must include the Policy Resolution mediation primitive in your mediation flow component. After exporting the EAR file containing your Policy Resolution primitive, you must import it into WebSphere Service Registry and Repository (WSRR). This adds your module to the registry. You must then attach a suitable mediation policy to your module.

At run time, the Policy Resolution mediation primitive queries your registry, and uses any suitable mediation policy information to override promoted properties that come later in the flow.

XPath

Many mediation primitives have a property called Root that contains an XPath 1.0 expression. You can use this XPath expression to specify a subset of the message for the mediation primitive to operate on. Depending on the mediation primitive, you can specify: /, /body, /headers, or your own XPath expression. / refers to the complete SMO, /body refers to the body section of the SMO, /headers refers to the headers of the SMO. If you specify your own XPath expression, the part of the SMO you specify is processed.

WebSphere Integration Developer displays the structure of a message and allows you to select locations within the message. In this way you can navigate the structure of a message and create XPath expressions.

WebSphere Integration Developer does not allow Root to be null.

Dynamic routing

You can route messages to an endpoint that is decided at run time. The endpoint that the run time uses is located in the SMO header at /headers/SMOHeader/Target/address. You can set this part of the SMO manually, using various mediation primitives, but the Endpoint Lookup mediation primitive can set this location automatically.

In order for the run time to implement dynamic routing on a request, you must set the Use dynamic endpoint if set in the message header property in the callout node or Service Invoke mediation primitive.

You can specify a default endpoint that the run time uses if it cannot find a dynamic endpoint. You specify a default endpoint by wiring an import to a reference.

Dynamic endpoint support does not require you to wire a reference to an import. However, if you want to provide default configuration settings for the dynamic endpoint, you can use a wired import. After a reference is wired to an import, the configuration settings of the import apply to all dynamic endpoints using that reference.

For example, if you want to influence whether a service is called synchronously or asynchronously, (from the callout or Service Invoke primitive), you can specify the preferred interaction style on the interface, used by the import; and wire the reference to this import. Similarly, you can configure the security settings for a Web service dynamic endpoint, by using a wired import with Web service binding.

Attachments

You can send and receive SOAP messages that have attachments of various types. You might want to send SOAP messages with attachments and let the attachments pass through the mediation flow unchanged, or you might want to create new attachments, perhaps from information in the message.

Exceptions

A mediation primitive throws a MediationConfigurationException if it detects either a configuration problem or a transient external resource failure. For example, if a database cannot be found. In addition, a mediation primitive throws a MediationConfigurationException if a dynamic property has a problem with the override value supplied in the relevant policy. For example, if a dynamic property is an integer and the string value defined in the policy cannot be successfully converted into an integer, the mediation primitive throws a MediationConfigurationException.

A mediation primitive throws a MediationBusinessException if there is a business error. For example, if a key that should be in a message, is not found.

The run time throws a MediationRuntimeException if there are problems setting up a mediation flow.


concept Concept topic

Terms of use | Feedback


Timestamp icon Last updated: 20 June 2010 00:39:51 BST (DRAFT)


http://publib.boulder.ibm.com/infocenter/dmndhelp/v6r2mx/topic//com.ibm.wbit.help.medprim620.doc/concepts/cwesb_overviewmediationprimitives.html
Copyright IBM Corporation 2005, 2010. All Rights Reserved.
This information center is powered by Eclipse technology (http://www.eclipse.org).
iDoc on