This document describes the UltraESB public API for mediating messages, and the configuration of the various transports, WS-Security and AS2 options

Overview

The UltraESB public API has been separated into its own JAR file, and published as a Maven 2 artifact at the AdroitLogic Maven 2 repository:

http://downloads.adroitlogic.org/maven2

Additionally, Javadocs for the public API is published at : http://api.adroitlogic.com

Mediating Messages within a Sequence

The UltraESB mediation is based around two simple classes - Mediation, and Message. While the Mediation class exposes the built-in support for common actions, the Message class exposes the various aspects of a message, so that user could develop own utilities, extensions, methods of custom logic for mediating messages as required. The payload of a Message belongs to an Object implementing the MessageFormat interface - which exposes the raw message payload where required. The MessageFormat is determined by the transport accepting a message, and maybe converted during mediation. For example, an HTTP/S request is held as a RawFileMessage - but maybe converted to and from a DOMMessage etc. A JMS Text Message will default to a StringMessage, while a Map Message will default to a MapMessage etc. In future other MessageFormats may be introduced with additional transports.

Variables exposed to Java and JSR-223 Script fragments

Every sequence is passed three variables as follows:

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

Mediation utilities

The following common utility methods are exposed by the Mediation instance. In future, new methods may be made available in addition to these.

Refer to http://api.adroitlogic.org/org/adroitlogic/ultraesb/api/Mediation.html for the latest version

The Message object

The Message class exposes the following methods as its public API. In future, more methods maybe made available

Refer to http://api.adroitlogic.org/org/adroitlogic/ultraesb/api/Message.html for the latest version

Message Formats (i.e. Payload formats)

Refer to the full API documentation for the MessageFormats listed below

• RawFileMessage - The default message format used by the HTTP/S transport and File (file, sftp, ftp, ftps) transport
• StringMessage - JMS Text messages etc
• DOMMessage - Messages parsed into XML (for XPath evaluation or XSLT transformation)
• MapMessage - JMS Map messages etc
• ObjectMessage - JMS Object messages etc
• ByteArrayMessage - JMS Bytes messages etc
• DataHandlerMessage - Email messages etc

AS2 Manager

The use of the AS2 support requires the definition of the AS2Manager to the configuration. This configures the local AS2 identifier, email address and keystore information - through the KeystoreManager. The AS2 support will be further improved in the subsequent releases, with end-user feedback received. Currently the AS2Manager exposes the following methods

The core components in the use of AS2 is as per the following diagram. The AS2 support uses two proxy services "AS2Receiver" and "AS2Sender" through the HTTP/S transport, which interacts with the AS2Manager instance. An external partner thus may send a new AS2 message, or an asynchronous MDN to the AS2Receiver Proxy service URL, and it will pass it to the AS2Manager via the processIncomingAS2Message() method. After the AS2Manager processes a new AS2 message or MDN, it will issue the corresponding transport level closure or issuance of the synchronous MDN automatically, and then the control is returned to the AS2Receiver sequence with the current message set to the AS2 message payload received and its attachments if any. (See sample # 351)

To send a new AS2 message to a trading partner, one may typically use a Proxy service - such as a File transport proxy that will poll for messages to be sent to AS2 partners - and then invoke the AS2Manager.sendNewAS2Message() passing the Partner information and the message. It is perfectly possible for this process to be triggered by another Java bean/logic defined in the main Spring configuration, by calling directly to the AS2Manager. On a successful send with a MDN receipt, the notifyReceiptOfMDN() is called back, while on a transport level ack or error, the notifySendStatusFromTransport() is called back, and the message flagged as failed.

WS-Security Support

The WSSecurityManager configures the WS-Security support of the UltraESB. Configuration requires the specification of the identity/trust keystores and passwords, and the credentials against required certificates or aliases. There are two variations of the constructor to be used when the identity and trust stores are the same and different.

e.g. The definition of the WSSecurityManager to the configuration when the trust and identity keystores are the one and the same. The Map passed to the constructor specifies the alias and the password for the credentials to be used. Note that the passwords used in the configuration can be easily protected / encrypted using as per this article.

    <bean id="wssecMgr" class="org.adroitlogic.soapbox.WSSecurityManager">
        <constructor-arg value="samples/conf/keys/ws-sec-keystore.jks"/>
        <constructor-arg value="password"/>
        <constructor-arg>
            <map>
                <entry key="alice" value="password"/>
                <entry key="bob" value="password"/>
            </map>
        </constructor-arg>
    </bean>

Once the WSSecurityManager is configured, it could be used to verify security of incoming messages, and issue custom error messages - possibly hiding the original cause of the security failure as in the example given below. Refer to the sample configuration # 204 for more details.

        <u:inSequence>
                <u:java import="org.adroitlogic.soapbox.*;"><![CDATA[
                try {
                    WSSecurityManager wssecMgr = (WSSecurityManager) mediation.getSpringBean("wssecMgr");
                    wssecMgr.verifyUsernameTokenAuthentication(msg);
                    wssecMgr.verifyTimestampedEncryptedAndSignedMessage(msg, true);
                    System.out.println("Validated User : " + msg.getMessageProperty(MessageSecurityContext.USER_NAME));
                    System.out.println("Validated Roles : " + msg.getMessageProperty(MessageSecurityContext.USER_ROLES));
                } catch (Exception e) {
                    mediation.setPayloadToSOAP11Fault(msg, null, "Security validation failed", null);
                    mediation.sendResponse(msg, 500);
                }
                ]]></u:java>
        </u:inSequence>

The full sample # 204 configuration lists examples of how WS-Security is validated and used - including the use of Timestamps, Signatures and Encryption. Additionally, the same example shows how UsernameToken authentication maybe added to a message being sent via the UltraESB.

The WSSecurityManager exposes the following methods for mediation

Transports Configuration

The various transports allows many configuration options. These are well described in the links reachable from the following

HTTP/S Transport

• HttpNIOListener
• HttpNIOSender
• HttpsNIOListener
• HttpsNIOSender

JMS Transport

• JMSTransportListener
• JMSTransportSender

File Transport (i.e. file, sftp, ftp, ftps)

• FileTransportListener
• FileTransportSender

Email Transport (POP3, IMAP, SMTP)

• MailTransportListener
• MailTransportSender