WebSphere WebSphere Enterprise Service Bus, Version 6.0.2 Operating Systems:

Overview of mediation primitives

Mediation primitives accept messages that they process as Service Message Objects (SMO).

Introduction

All mediation primitives have an input terminal that can be wired to accept a message.

Most mediation primitives have one or more output terminals that can be wired to propagate a message. However, the Stop and Fail mediation primitives have no output terminals. Output terminals are for two kinds of flows: fail flows and successful flows. Depending on the mediation primitive there is, at most, one fail terminal. The number of successful output terminals also depends on the mediation primitive. Some mediation primitives have no terminals for successful output, others have one or more.

If an exception occurs during the processing of the input message, then 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 IllegaArgumentException is thrown and the original message is not propagated.

If an output terminal of a mediation primitive is left unwired, then WebSphere Integration Developer generates a warning. At runtime, the unwired output terminal stops this path in the flow without generating an exception, and the message is consumed. If you want to stop a path through the flow without generating an exception, you can explicitly wire the output terminal to the Stop mediation primitive.

SMO

Mediation primitives process messages as Service Message Objects (SMO). SMO provides an abstraction layer for processing and manipulating messages exchanged between services.

All SMOs have the same basic structure. The structure consists of a root data object called a ServiceMessageObject, which contains other data objects representing header, body and context data.
  • The SMO headers contain information associated with the message. For example, Java Messaging Service (JMS) headers if a message has been conveyed using the JMS API.
  • The SMO body contains the message payload. The payload is the application data exchanged between service endpoints.
  • The SMO context can contain correlation context and transient context. Both correlation context and transient context allow data that is not part of the message payload to be passed between mediation primitives. However, correlation context can link a specific request message with its response, whereas transient context is restricted to a single message flow. Transient context cannot link requests and responses.

When creating mediation flows, the WebSphere Integration Developer tooling specifies the type of message body for each terminal (input, output or fail). The tooling optionally specifies the type of context information. The runtime product uses this information to convert messages into SMO objects of the specified type.

The SMO model is a pattern for using SDO (Service Data Object) DataObjects to represent messages. SMO provides an interface to access and modify message headers and message payloads. SMO can represent the logical content of many different types of message.

XPath

Many mediation primitives have a property called Root that contains an XPath 1.0 expression. The XPath expression represents the root of the current mediation. Typically, 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 then 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 runtime. The endpoint that the runtime 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 runtime to implement dynamic routing on a request, you must set the Use dynamic endpoint property in the callout node.

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

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.

Promoted properties have an alias name, which is the name displayed on the runtime administrative console. You can set the alias name and the alias value from WebSphere Integration Developer. Multiple promoted properties can be given the same alias name if they are of the same type. Promoted properties which use the same alias name will all use the value of that alias. For example, consider a mediation module that contains two primitives which both have a Validate input property. You could set the same alias name and then control message validation, for both, by setting the promoted property from the runtime administrative console.

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.

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 mediation runtime throws a MediationRuntimeException if there are problems setting up a mediation flow.


Concept topic

Terms of Use | Rate this page

Timestamp iconLast updated: 29 Oct 2006
http://publib.boulder.ibm.com/infocenter/dmndhelp/v6rxmx/index.jsp?topic=/com.ibm.wbit.help.medprim602.doc\concepts\cwesb_overviewmediationprimitives.html

(C) Copyright IBM Corporation 2005. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)