Chapter 4. Transformation

4.1. Adding Transformation to Your Application
4.2. Java Transfomer
4.3. Smooks Transformer
4.4. JSON Transformer

Transformation represents a change to the format and/or representation of a message's content. The representation of a message is simply the Java contract (e.g. java.lang.String, org.example.MyFancyObject) used to access the underlying content. The format of a message refers to the actual structure of the data itself. Examples of data formats include XML, JSON, CSV, and EDI.

Take the following message content:

<MyBook>
  <Chapter1>
  <Chapter2>
</MyBook>

The format of this content is XML. One representation of XML in Java is as a String. Of course, the representation could also be a org.w3c.dom.Document, java.io.InputStream, etc.

String content = "<MyBook>...";

Transformation plays an important role in connecting service consumers and providers, since the format and representation of message content can be quite different between the two. For example, a SOAP gateway binding will likely use a different representation and format for messages than a service offered by a Java Bean. In order to route services from the SOAP gateway to the Bean providing the service, the format and representation of the SOAP message will need to change. Implementing the transformation logic directly in the consumer or provider pollutes the service logic and can lead to tight coupling. SwitchYard allows for the transformation logic to declared outside the service logic and injected into the mediation layer at runtime.

4.1. Adding Transformation to Your Application

Transformation of message content is specified in the descriptor of your SwitchYard application (switchyard.xml). The qualified name of the type being transformed from as well as the type being transformed to are defined along with the transformer implementation. This allows transformation to be a declarative aspect of a SwitchYard application, as the runtime will automatically register and execute transfomers in the course of a message exchange.

<transforms>
   <transform.java class="org.switchyard.quickstarts.demos.orders.Transformers"
                   from="{urn:switchyard-quickstart-demo:orders:1.0}submitOrder"
                   to="java:org.switchyard.quickstarts.demos.orders.Order"/>
</transforms>

4.2. Java Transfomer

There are two methods available for creating a Java-based transformer in SwitchYard:

Implement the org.switchyard.transform.Transfomer interface and add a <transform.java> definition to your switchyard.xml.
Annotate one or more methods on your Java class with @Transformer .

When using the @Transformer annotation, the SwitchYard maven plugin will automatically generate the <transform.java> definition(s) for you and add them to the switchyard.xml packaged in your application. The following Java class would produce the <transform.java> definition provided above:

public class MyTransformer {
    @Transformer(from = "{urn:switchyard-quickstart-demo:orders:1.0}submitOrder")
    public Order transform(Element from) {
       // handle transformation here
    }
}

The optional from and to elements of the @Transformer annotation can be used to specify the qualified type name used during transformer registration. If not supplied, the full class name of the method parameter will be used as the from type and the full class name of the return type will be used as the to type.

4.3. Smooks Transformer

There are three distinct transformation models available with Smooks in SwitchYard:

XML to Java : Based on a standard Smooks Java Binding configuration.
Java to XML : Based on a standard Smooks Java Binding configuration.
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 declared by including a <transform.smooks> definition in switchyard.xml.

<transform.smooks config="/smooks/OrderAck_XML.xml"
                  from="java:org.switchyard.quickstarts.transform.smooks.OrderAck"
                  to="{urn:switchyard-quickstart:transform-smooks:1.0}submitOrderResponse"
                  type="JAVA2XML"/>

The config attribute points to a Smooks resource containing the mapping definition. The type attribute can be one of SMOOKS , XML2JAVA , or JAVA2XML .

4.4. JSON Transformer

The JSON transformer provides a basically mapping facility between POJOs and JSON using the popular Jackson processor. Specification of the transformer requires one Java type and one named type. The following example converts a JSON serialization of an order to the Order object.

<trfm:transform.json
            from="{urn:switchyard-quickstart:transform-json:1.0}order"
            to="java:org.switchyard.quickstarts.transform.json.Order"/>