Transformation - SwitchYard 1.0

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.

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 bean="MyTransformerBean"
                   from="{urn:switchyard-quickstart-demo:orders:1.0}submitOrder"
                   to="java:org.switchyard.quickstarts.demos.orders.Order"/>
</transforms>

Content Type Names

Since transformations occur between named types (i.e. from type A, to type B), it's important to understand how the type names are derived. The type of the message is determined based on the service contract, which can be WSDL or Java.

For WSDL interfaces, the message name is determined based on the fully-qualified element name of a WSDL message. Take the following WSDL definition:

<definitions xmlns:tns="urn:switchyard-quickstart:bean-service:1.0">  
  <message name="submitOrder">
    <part name="parameters" element="tns:submitOrder"/>
  </message>
  <portType name="OrderService">
    <operation name="submitOrder">
      <input message="tns:submitOrder"/>
    </operation>
  </portType>
</definitions>

This would yield the following message type name based on the message element name defined in the WSDL:

{urn:switchyard-quickstart:bean-service:1.0}submitOrder

When Java interfaces are used for the service contract, the message name consists of the full package name + the class name, prefixed with "java:".

package org.switchyard.example;
public interface OrderService {
    void submitOrder(Order order);
}

The message type name for the submitOrder method in this Java interface would be "java:org.switchyard.example.Order". Occasionally, it can be useful to override the default operation name generated for a Java interface. The @OperationTypes annotation provides this capability by allowing the user to specify the input, output, and/or fault type names used for a Java service interface. For example, if we wanted to accept XML input content without any need for transformation to a Java object model, the OrderService interface could be changed to look like this:

package org.switchyard.example;
public interface OrderService {
    @OperationTypes(in = "{urn:switchyard-quickstart:bean-service:1.0}submitOrder")
    void submitOrder(String orderXML);
}

Aside from short-circuiting the requirement for transformation, this annotation can be useful if you want to maintain tight control over the names used for message content.

Available Transformers

Switchyard supports several transformers that facilitate conversion from one data format to another. The list of available transformers is given below