Using Transformers
| Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version. |
Transformers convert message payloads to formats expected by their destinations. 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.
| The most powerful tool for transforming a message is the DataWeave Transformer, which can not only change the format of the message, but also rename, aggregate, split or rearrange the fields in it in any way you desire. |
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 or in a flow or where you want to apply it, whereas you configure a global transformer before any <model> or <flow> elements in your Mule configuration file and then reference it.
For example, the following code defines two global transformers, which are referenced from two different places:
<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"/>
...
<flow name="Error Manager">
<inbound-endpoint address="file://./test-data/in" transformer-refs="XMLToExceptionBean ExceptionBeanToErrorMessage">
<file:filename-wildcard-filter pattern="*.xml" />
</inbound-endpoint>
...
</flow>
...
<flow name="Business Error Manager">
<inbound-endpoint address="jms://exception.queue"/>
<transformer ref="XMLToExceptionBean"/>
<transformer ref="ExceptionBeanToErrorMessage"/>
...
</flow>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 or received from an endpoint. 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 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 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 enterprise service bus.
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’s always used, you should use a transformer, and if it is specific to a single business process, it should be part of the 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.
Available Transformers
Following are the transformers available with Mule. Some transformers are specific to a transport or module. For more information, see Transports Reference and Modules Reference. 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: |
ByteArrayToHexString < - > |
A pair of transformers that convert between byte arrays and hex strings. |
ByteArrayToMuleMessage < - > |
A pair of transformers that convert between byte arrays and Mule messages. |
ByteArrayToObject < - > |
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 < - > |
A pair of transformers that serialize and deserialize objects. |
CombineCollectionsTransformer |
Takes a payload which is a Collection of Collections and turns into a single List. For example, if the payload is a Collection which contains a Collection with elements A and B and another Collection with elements C and D, this turns them into a single Collection with elements A, B, C, and D. |
ExpressionTransformer |
Evaluates one or more expressions on the current message and return the results as an Array. For details, see Mule Expression Language MEL. |
MessagePropertiesTransformer |
A configurable message transformer that allows users to add, overwrite, and delete properties on the current message. |
ObjectArrayToString < - > |
A pair of transformers that convert between object arrays and strings. Use the configuration elements |
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 |
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 Reference.
| Transformer | Description |
|---|---|
Converts XML to a Java object and back again using XStream. |
|
Converts XML to a Java object and back again using the JAXB binding framework (ships with JDK6) |
|
Transforms XML payloads using XSLT. |
|
Transforms XML payloads using XQuery. |
|
Converts DOM objects to XML and back again. |
|
Converts XML from a message payload to a StAX XMLStreamReader. |
|
Queries and extracts object graphs using XPath expressions using JAXP. |
|
Queries and extracts object graphs using XPath expressions using JXPath. |
|
Allows you to output the XML with controlled formatting, including trimming white space and specifying the indent. |
JSON
The JSON transformers are in the org.mule.module.json.transformers package. They provide the ability to work with JSON documents and bind them automatically to Java objects. For information, see Native Support for JSON.
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 |
|---|---|
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 |
|---|---|
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 |
|---|---|
A pair of transformers that convert to and from Base 64 encoding. |
|
A pair of transformers that convert to and from XML entity encoding. |
The Email transport provides several transformers for converting from email to string, object to MIME, and more. For details, see Email Transport Reference.
File
The File transport provides transformers for converting from a file to a byte array (byte[]) or a string. For details, see File Transport Reference.
HTTP
The HTTP connector provides several transformers for converting an HTTP response to a Mule message, map or string, and for converting a message to an HTTP request or response. For details, see HTTP Connector.
JDBC
*Enterprise*
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 Reference.
JMS
The JMS Transport Reference and Mule WMQ Transport Reference (enterprise only) both provide transformers for converting between JMS messages and several different data types.
Strings and Byte Arrays
The Multicast Transport Reference and TCP Transport Reference 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 Reference.
Custom
Mule supports the ability to build Custom Transformer. Build custom transformers to meet specific data conversion needs in your application.
Common Attributes
Following are the attributes that are common to all transformers.
ignoreBadInput
If set to true, the transformer ignores any data that it does not know how to transform, but any transformers following it in the current chain is called. If set to false, the transformer also ignores any data that it does not know how to transform, but no further transformations takes place.