Mediation Reference

API Overview

The UltraESB users are shielded from being bound to any internals of the ESB through a clearly separated user level API. This API is available as a separate JAR file as well, and could be linked via Maven2 to any custom projects that define any mediation code or such reusable artifacts related to mediation.

API JavaDoc’s are available at http://api.adroitlogic.org
The binary API JAR files are available at the AdroitLogic Maven2 Repository at http://repository.adroitlogic.org/maven2 and this could be linked via Maven2

Mediating Messages within a Sequence

The mediation API is based mainly around two interfaces - Mediation, and Message. While the Mediation interface exposes the built-in support for common actions, the Message interface exposes the various aspects of a message (e.g. transport headers, message properties etc) so that a user could develop his own mediation logic, extensions, or custom libraries for mediating messages as required. In addition, an instance to a SLF4J Logger is passed into a sequence, which could be used by the mediation code for logging.

The payload of a Message is an Object implementing the MessageFormat interface - and would be created based on the native message format of the message that the transport level sees. During mediation, the message format maybe changed - by explicit user action, or implicitly. For example, an HTTP/S request is held as a RawFileMessage - but maybe converted to and from a DOMMessage implicitly for XPath evaluation or XSLT transformation etc. A JMS Text Message will default to a StringMessage, while a Map Message will default to a MapMessage etc. Users could define custom message formats - but this would generally be very rare as the default message formats support many transports and protocols.

Variables available to Java and JSR 223 Scripting language Sequences

Every sequence is passed three variables as follows:

msg - Represents the current message, and is defined by the Message interface
mediation - Allows easy access to a rich and powerful set of mediation utility methods and is defined by the Mediation interface
logger - a logger category that maybe used for logging from within user code during mediation

The Mediation Interface

The Mediation interface defines the following sub-interfaces for organized access to mediation utilities and features

SOAPSupport - Mediation utilities for SOAP message processing (Schema validation, transformation, XPath evaluation, FastInfoset, Header and Fault manipulation)
HTTPSupport - HTTP level mediation support (e.g. cookies, authentication etc)
XMLSupport - XML mediation support (e.g. to/from DOM/JSON conversion, FastInfoset, DOM manipulation, Schema validation, transformation, XPath evaluation etc)
JSONSupport - JSON mediation support (e.g. JSON Data services, SOAP or XML to/from JSON etc)
ProtocolBufferSupport - mediation utilities for interacting with Protocol Buffers based messages
XACMLSupport - XACML fine grained authorization support
DateSupport - Data manipulation utilities
CachingSupport - Support for caching of responses
ThrottleSupport - Support for Throttling
AuditSupport - Support for Auditing
MappingSupport - Mapping support for the conversion of message payloads with transformation
AS2Manager - AS2 based messaging support
WSSecurityManager - WS-Security processing support

In addition, the Mediation interface directly exposes some useful methods such as:

sendToEndpoint() - send the message to a specifically selected endpoint (e.g. for routing between different endpoints during mediation)
getConnection() and getDataSource - obtain a JDBC connection or Datasource (e.g. for use with Spring JDBC templates within mediation)
getDefaultPlatformTM() - obtain platform Transaction Manager - e.g. for resource local or JTA XA transaction support
getSpringBean() - directly access any visible Spring bean (Note: dynamically re-loadable configuration fragments can access beans defined only within their scope or from the root scope)
sendResponse(), invokeSequence() and dropMessage() - send a response to the client, invoke another sequence, or stop handling by default inDestination or outDestination
readPayloadAsString() - return a String representation of the payload LIMITED TO 8KB (larger messages WILL be trimmed)
savePayloadToFile() - save the payload to a file easily
setPayloadFromByteArray(), setPayloadFromFile(), setPayloadFromString() - self explanatory
sendAndReceiveResponse() - send the message to the given endpoint to and populate the response data to the response message

The Message Interface

The Message interface holds the payload of the message, attachments, transport headers, properties and its run-time state (such as transactions bound to, tasks to execute on message completion or failure, content type, UUID, correlated properties set on the message, exceptions and errors encountered etc). The payload of the message is held in an object implementing the MessageFormat interface

RawFileMessage - the most efficient form of a message, where the raw bytes are held in a RAM disk based file system or on Memory mapped files (default for HTTP/S messages etc)
StringMessage - payload held as a String and hence will not be optimal for large messages (default for JMS text messages etc)
ByteArrayMessage - payload held in a byte array in memory (default for JMS bytes messages etc)
DOMMessage - DOM object based message for XML payloads
DataHandlerMessage - payload held as a DataHandler
MapMessage - payload is held on a Java Map (e.g. JMS map messages)
ObjectMessage - payload is a Java Object (e.g. JMS Object messages)
ProtocolBufferMessage - payload is a Google Protocol Buffers based message
StreamMessage - payload is a Stream (e.g. JMS stream message)
HAPIMessage - payload is a HL7 message stored as a HAPI message
GenericMessage - an abstract base class for message formats

The Message interface exposes some key methods for mediation as follows:

Attachment and Exceptions manipulation
Message properties and co-relation to asynchronous responses
Transport header manipulation
JTA XA and Resource Local Transaction manipulation - including begin/commit/rollback/suspend/resume etc
Message cloning
Payload manipulation including detachment of an actual payload from a message
Temporary files assignment and manipulation for message processing

Please see the Javadocs for the Message interface for complete details

Other Mediation Utilities and Features

AS2 Message Processing - Refer to the AS2 Guide for more details
WS-Security - Refer to the WS-Security Gateway guide for more details
XACML - Refer to the XACML Guide for more details