Mule Transformers

Using Transformers

[ Configuring Transformers ] [ Inbound, Outbound, and Response Configurations ] [ Chaining Transformers ] [ Transformation Best Practices ] [ Available Transformers ]

Transformers convert message payloads as they are transported between services. Mule provides many standard transformers, which you configure using predefined elements and attributes in your Mule XML configuration file. You can also configure custom transformers using the <custom-transformer> element, in which you specify the fully qualified class name of the custom transformer class. For more information on creating and configuring a custom transformer, see Creating Custom Transformers .

Standard transformers are easier to use than custom transformers. You don't need to know the Java name of the transformer, and all properties are explicitly declared in a Mule configuration schema. Following is an example of declaring the standard Append String transformer, which appends string text to the original message payload:

<append-string-transformer name="myAppender"
 message=" ... that's good to know!"
/>

If the original message payload was the string "foo", the transformer above would convert the string to "foo ... that's good to know!".

The Available Transformers section of this page describes all the standard transformers provided with Mule. Additionally, many transports and modules have their own transformers, such as the ObjectToJMSMessage transformer for the JMS transport.

Configuring Transformers

You can configure a transformer locally or globally . You configure a local transformer right on the endpoint where you want to apply it, whereas you configure a global transformer before the <model> element in your Mule configuration properties so you can then refer to the transformer in multiple places.

For example, the following code defines two global transformers, which are referenced from two different services:

<xm:xml-to-object-transformer name="XMLToExceptionBean"
 returnClass="org.mule.example.errorhandler.ExceptionBean"
/>
 
<custom-transformer name="ExceptionBeanToErrorMessage"
 class="org.mule.example.errorhandler.ExceptionBeanToErrorMessage"
 
returnClass="org.mule.example.errorhandler.ErrorMessage"
/> 

...
<model name="errorhandler-test"
>

  <service name="Error Manager"
>

    <inbound>

      <inbound-endpoint address="file://./test-data/in"
 transformer-refs="XMLToExceptionBean ExceptionBeanToErrorMessage"
>

        <file:filename-wildcard-filter pattern="*.xml"
 />
 
      </inbound-endpoint>

    </inbound>

    ...
  </service>

...
  <service name="Business Error Manager"
>

    <inbound>

      <inbound-endpoint address="jms://exception.queue"
 transformer-refs="XMLToExceptionBean ExceptionBeanToErrorMessage"
 />
 
    </inbound>

  ...
  </service>

</model>

This example uses the transformer-refs attribute on the endpoint to specify the transformers to use. This is a fast way of specifying global transformers, but if you want to enter a local transformer or a mix of local and global transformers, you must use the <transformer> element instead. For example, if only one of the transformers were defined globally, you would refer to the global transformer and configure the local transformer as follows:

  <service name="Error Manager"
>

    <inbound>

      <inbound-endpoint address="file://./test-data/in"
>
 
        <transformer ref="XMLToExceptionBean/>

        <custom-transformer name="ExceptionBeanToErrorMessage"
 class="org.mule.example.errorhandler.ExceptionBeanToErrorMessage"
 
returnClass="org.mule.example.errorhandler.ErrorMessage"
 />
        <file:filename-wildcard-filter pattern="*.xml"
 />
 
      </inbound-endpoint>

    </inbound>

    ...
  </service>

Inbound, Outbound, and Response Configurations

The above examples illustrate configuring inbound transformers, which are applied to the message after it is received on the inbound endpoint and before it is passed to the service's component. You specify inbound transformers under the <inbound-endpoint> element.

You can also specify an outbound transformer in exactly the same way but on <outbound> element routers, in which case the message is transformed after it has been processed by the service's component but before it has been sent to the outbound endpoint specified by that router. For example:

<outbound>

  <filtering-router transformer-refs="ErrorMessageToException"
>

    <file:outbound-endpoint path="test-data/exceptions"
 outputPattern="Exception-[UUID].xml"
 transformer-refs=
"ErrorMessageToExceptionBean ExceptionBeanToXML"
 /> 
  </filtering-router>

...
</outbound>
 

Lastly, you can specify a response transformer, which converts response message payloads on their way from the service back to the caller. To configure a response transformer, you use the responseTransformers-refs attribute on the router, or you can use the <response-transformer> element. For example:

<inbound>

     <vm:inbound-endpoint path="my.inbound.endpoint"
 responseTransformer-refs="myAppender"
/>

</inbound>

<some-component/>

In this example, the response message from "some-component" is transformed using the "myAppender" transformer before being returned to the caller. For more information on response messages and the messaging styles supported by Mule, see Mule Messaging Styles .

Chaining Transformers

You can chain transformers together so that the output from one transformer becomes the input for the next. To chain transformers, you create a space-separated list of transformers in the transformer-refs or responseTransformer-refs attributes or by creating multiple <transformer> elements as shown above.

For example, this chain ultimately converts from a ByteArray to InputStream:

transformer-refs="ByteArrayToString StringToObject ObjectToInputStream"

You could also configure this as follows:

<transformer ref="ByteArrayToString"
/>

<transformer ref="StringToObject"
/>

<transformer ref="ObjectToInputStream"
/>

Note that if you specify transformer chains, any default transformers or discoverable transformers are not applied. If you want to use those transformers, you must specify them explicitly with the other chained transformers.

Transformation Best Practices

Mule has an efficient transformation mechanism. Transformers are applied to inbound or outbound endpoints, and the data is transformed just before it is sent from a service or just before it is received by another service. Transformers can be concatenated, so it is simple to perform multiple transformations on data in transit.

There is no one standard approach for how and where transformations should occur. Some maintain that because transformation should always be applied on inbound/outbound data, transformations should be available as part of the enterprise service bus instead of inside the service components. This approach matches the concepts of Aspect Oriented Programming (AOP). Others conclude that it is far more efficient to encode the transformation logic into the service components themselves. In the second case, however, there is no distinction between code that is related to a business process and code that is generic enough to be reused, which contradicts the philosophy of an ESB.

While there is no industry best practice, MuleSoft recommends that developers examine their transformation logic to see if it will always be used (AOP) or if it is specific to a business process. In general, if it will always be used, you should use a transformer, and if it is specific to a single business process, it should be part of the service component.

Note the following cases where you should not configure a transformer:

• Default transformers: some transports have default transformers that are called by default, but only if you don't configure explicit transformations.
• Discoverable transformers: some transformers can be discovered and used automatically based on the type of message. You do not configure these transformers explicitly. These include custom transformers that have been defined as discoverable. For more information, see Creating Custom Transformers .

References: http://msdn2.microsoft.com/en-us/library/aa480061.aspx http://blogs.ittoolbox.com/eai/applications/archives/transformation-in-a-soa-12186

Available Transformers

Following are the transformers available with Mule. Some transformers are specific to a transport or module. For more information, see Available Transports and Using Mule Modules . For a complete reference to the elements and attributes for the standard Mule transformers, see Transformers Configuration Reference .

Basic

The basic transformers are in the org.mule.transformer.simple package. They do not require any special configuration. For details on these transformers, see Transformers Configuration Reference .

Transformer Description

BeanBuilderTransformer	(As of Mule 2.2) Constructs simple bean objects by defining the object and then setting a number of expressions used to populate the bean properties. For example: <bean-builder-transformer name="testTransformer3" beanClass="org.mule.test.fruit.Orange" > <bean-property name="brand" evaluator="mule" expression="message.payload" optional="true" /> <bean-property name="segments" evaluator="mule" expression="message.header(SEGMENTS)" /> </bean-builder-transformer>
ByteArrayToHexString <-> HexStringToByteArray	A pair of transformers that convert between byte arrays and hex strings.
ByteArrayToMuleMessage <-> MuleMessageToByteArray	A pair of transformers that convert between byte arrays and Mule messages.
ByteArrayToObject <-> ObjectToByteArray	A pair of transformers that convert between byte arrays and objects. If the byte array is not serialized, ByteArrayToObject returns a String created from the bytes as the returnType on the transformer.
ByteArrayToSerializable <-> SerializableToByteArray	A pair of transformers that serialize and deserialize objects.
ExpressionTransformer	Evaluates one or more expressions on the current message and return the results as an Array. For details, see Using Expressions .
MessagePropertiesTransformer	A configurable message transformer that allows users to add, overwrite, and delete properties on the current message.
ObjectArrayToString <-> StringToObjectArray	A pair of transformers that convert between object arrays and strings. Use the configuration elements <byte-array-to-string-transformer> and <string-to-byte-array-transformer> .
ObjectToInputStream	Converts serializable objects to an input stream but treats java.lang.String differently by converting to bytes using the String.getBytes() method.
ObjectToOutputHandler	Converts a byte array into a String.
ObjectToString	Returns human-readable output for various kinds of objects. Useful for debugging.
StringAppendTransformer	Appends a string to an existing string.
StringToObjectArray	Converts a string to an object array. Use the configuration element <string-to-byte-array-transformer> .

XML

The XML transformers are in the org.mule.module.xml.transformer package. They provide the ability to transform between different XML formats, use XSLT, and convert to POJOs from XML. For information, see XML Module .

Scripting

The Scripting transformer transforms objects using scripting, such as JavaScript or Groovy scripts. This transformer is in the org.mule.module.scripting.transformer package.

Encryption

The encryption transformers are in the org.mule.transformer.encryption package.

Transformer Description

Encryption <-> Decryption	A pair of transformers that use a configured EncryptionStrategy implementation to encrypt and decrypt data.

Compression

The compression transformers are in the org.mule.transformer.compression package. They do not require any special configuration.

Transformer Description

GZipCompressTransformer <-> GZipUncompressTransformer	A pair of transformers that compress and uncompress data.

Encoding

The encoding transformers are in the org.mule.transformer.codec package. They do not require any special configuration.

Transformer Description

Base64Encoder <-> Base64Decoder	A pair of transformers that convert to and from Base 64 encoding.
XMLEntityEncoder <-> XMLEntityDecoder	A pair of transformers that convert to and from XML entity encoding.

Email

The Email transport provides several transformers for converting from email to string, object to MIME, and more. For details, see Email Transport .

File

The File transport provides transformers for converting from a file to a byte array (byte[]) or a string. For details, see File Transport .

HTTP

The HTTP transport provides several transformers for converting an HTTP response to a Mule message or string, and for converting a message to an HTTP request or response. For details, see HTTP Transport . Additionally, the Servlet transport provides transformers that convert from HTTP requests to parameter maps, input streams, and byte arrays. For details, see Servlet Transport .

JDBC

The Mule Enterprise version of the JDBC transport provides transformers for moving CSV and XML data from files to databases and back. For details, see JDBC Transport .

JMS

The JMS Transport and Mule WMQ Transport (enterprise only) both provide transformers for converting between JMS messages and several different data types.

Strings and Byte Arrays

The Multicast Transport and TCP Transport both provide transformers that convert between byte arrays and strings.

XMPP

The XMPP transport provides transformers for converting between XMPP packets and strings. For details, see XMPP Transport .

 

http://www.mulesoft.org/display/MULE2USER/Using+Transformers