Message Transformation is a core concept within SwitchYard, baked directly into the SwitchYard Exchange mechanism.  Before understanding how Message Transformation works in SwitchYard, one first needs to have an understanding of the SwitchYard Exchange and ExchangeContract constructs.

Transformers

Transformations are performed by Transformer implementations registered in the ServiceDomain.  They are selected based on the type information supplied in the ExchangeContract (specified on the Exchange).  If the ExchangeContract does not specify any message type information, no transformations are applied.

A Transformer transforms from one type to another type.  The types are specified using a QName (Qualified Name).

The interface is as follows:

public interface Transformer<F, T> { 

    T transform(F from);

    QName getFrom();

    QName getTo();
}

The following illustrations shows the lifecycle of a typical IN_OUT exchange sequence:

As outlined in Message Exchange & ExchangeContract, multiple message payload types may exist during the lifetime of an IN_OUT exchange:

1. IN: Actual input type at Invoker/Consumer (at A).
2. IN: Expected input type at the ServiceOperation (at B).
3. OUT: Actual output type at ServiceOperation (at C).
4. OUT: Expected output type at Invoker/Consumer (at D).

This means that a Transformer may need to be applied on both the IN and the OUT phase of the Exchange.

1. IN: Transform from actual type at A to expected type at B. (from A' to B')
2. OUT: Transform from actual type at C to expected type at D.  (from C' to D')

In order for either of these transformations to be applied, two things need to be in place:

1. The ExchangeContract type information needs to be populated on the Exchange instance.  See here.
2. Transformer instances that transform from and to the data types specified for the IN and OUT exchange phases, as outlined above.

If the ExchangeContract type information is populated on the Exchange (#1), but the appropriate Transformer instances are not registered (#2), an exception will occur and SwitchYard will log the expected to/from types, which will be the information you need to implement and register an appropriate Transformer.

Creating a Custom Transformer

The easiest way of creating a Custom Transformer is by extending the BaseTransformer class.  For example, to transform from a Java Reply object instance to a String containing a SOAP body payload:

public class JavaReplyToSOAP<F extends Reply, T extends String>  extends BaseTransformer<F, T> {

    public String transform(Reply from) {
        // Transform from a Reply object to a SOAP body payload

        return soap;
    }

    public QName getFrom() {
        return new QName("java:org.switchyard.component.soap.greeting.Reply");
    }

    public QName getTo() {
        return QName.valueOf("{urn:switchyard-component-soap:test-greeting:1.0}greetResponse");
    }
}

Registering/Configuring a Transformer

Transformer instances (to transform from one type to another) must be registered with the ServiceDomain instance associated with the target Service (Service Operation).  This is done by the SwitchYard application deployer based on the application's SwitchYard configuration.  Transformations are configured in the <transforms> section of the SwitchYard configuration.

Two transfromation types are currently supported:

1. Custom Java Transforms (see previous section).
2. Smooks Transforms (see following section).

The following is a switchyard.xml example containing a Custom Java transform configuration.

<switchyard xmlns="urn:switchyard-config:switchyard:1.0" xmlns:trfm="urn:switchyard-config:transform:1.0">

    <transforms>
        <trfm:transform.java from="msgA" to="msgB" class="org.examples.transform.AtoBTransform"/>
    </transforms>

    <!-- Rest of config... -->

</switchyard>

Smooks Transformations

Three types of Smooks transformations are supported by SwitchYard:

1. XML to Java:  Based on a standard Smooks Java Binding configuration.
2. Java to XML:  Based on a standard Smooks Java Binding configuration.
3. Smooks:  This is a "normal" Smooks transformation in which the developer must define which Smooks filtering Result is to be exported back to the SwitchYard Message as the transformation result.

Smooks transformations are, like all transformations, configured in the <transforms> section of the SwitchYard configuration (switchyard.xml):

<switchyard xmlns="urn:switchyard-config:switchyard:1.0" xmlns:trfm="urn:switchyard-config:transform:1.0">
    <transforms>
        <trfm:transform.smooks type="XML2JAVA" from="msgC" to="msgD" config="/trasnforms/xxx.xml" reportPath="/tmp/smooksreport.html" />
    </transforms>
</switchyard>