Access Keys:
Skip to content (Access Key - 0)
Cancel    
Cancel   
 

Using Transformers

Jul 31, 2005 15:16

Robin Pille

Jun 06, 2013 17:06

Mulesoft Current Mule Documentation

Using Transformers

Mulesoft Documentation Page

Contents

Using Transformers

Transformers convert message payloads to formats expected by their destinations. Mule ESB 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:

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:

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:

You could also configure this as follows:

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 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 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 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 <->
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.

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 will turn 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 <->
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 Reference.

Transformer

Description

XmlToObject <-> ObjectToXml

Converts XML to a Java object and back again using XStream.

JAXB XmlToObject <-> JAXB ObjectToXml

Converts XML to a Java object and back again using the JAXB binding framework (ships with JDK6)

XSLT

Transforms XML payloads using XSLT.

XQuery

Transforms XML payloads using XQuery.

DomToXml <-> XmlToDom

Converts DOM objects to XML and back again.

XmlToXMLStreamReader

Converts XML from a message payload to a StAX XMLStreamReader.

XPath Extractor

Queries and extracts object graphs using XPath expressions using JAXP.

JXPath Extractor

Queries and extracts object graphs using XPath expressions using JXPath.

XmlPrettyPrinter

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

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 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 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 Reference. Additionally, the Servlet transport provides transformers that convert from HTTP requests to parameter maps, input streams, and byte arrays. For details, see Servlet Transport Reference.

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.

returnClass

This specifies the name of the Java class that the transformer returns.

ignoreBadInput

If set to true, the transformer will ignore any data that it does not know how to transform, but any transformers following it in the current chain will be called. If set to false, the transformer will also ignore any data that it does not know how to transform, but no further transformations will take place.

mimeType

This mime type will be set on all messages that this transformer produces.

encoding

This encoding will be set on all messages that this transformer produces.