Mediation primitives accept messages that they process as Service Message Objects (SMO).
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.
Mediation primitives process messages as Service Message Objects (SMO). SMO provides an abstraction layer for processing and manipulating messages exchanged between services.
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.
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.
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.
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.
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.