Skip to end of metadata
Go to start of metadata

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.

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
  • 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

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
  • Caching - Refer to the Caching Guide for more details
  • Throttling - Refer to the Throttling Guide for more details
  • XACML - Refer to the XACML Guide for more details

 

 

 

 

  • No labels