Creating Custom Transformer Classes
A custom transformer is a user-defined transformer class that implements
org.mule.api.transformer.Transformer. Your class can extend
AbstractMessageTransformer, depending on your needs. This page describes how to create a custom transformer in more detail.
Access Transformer Annotation if you are looking for information about creating a transformer with the Transformer Annotation.
AbstractTransformer allows you to access and transform the source payload and to specify the encoding to use (if required). It defines methods for controlling the object types this transformer supports and validates the expected return type, leaving you to implement a single
If you need to transform the message header and attachments, you can use
AbstractMessageTransformer instead to change them directly on the message passed in. In this case, you return the transformed message payload by overriding the method
transform(MuleMessage message, String encoding). You can use
message.getProperty(Object key) to retrieve the properties or
message.setProperty(Object key, Object value) to set properties on the transformed message.
Registering Source and Return Types
You can specify which source types a transformer can accept and which type it will return. This allows Mule to validate the incoming message before invoking the transformer and to validate the output before sending the message on. If you create a discoverable transformer, you must set the source and return types.
For example, for the Order bean to HTML transformer, you would specify in the constructor that the transformer converts only message payloads of type Order:
Because the source type is specified, you don't need to do any type checking in your
transform() method. However, if you add more than one source type, you do need to check for each type in your
Notice that the above code sets the name of the transformer. Usually, you set the transformer name in the XML configuration when the transformer is declared. If no name is set, Mule generates a name based on the first source type and return class, such as "OrderToString" if the above example did not specify the name.
Using Transformer Lifecycle Methods
All objects in Mule have lifecycles associated with them. For transformers, there are two lifecycle methods that are most useful.
AbstractTransformer both implement the
org.mule.api.lifecycle.Initialisable interface. After all bean properties are set on the transformer (if any), the
doInitialise() method is called. This is useful for transformers to do any initialization or validation work. For example, if a transformer requires that an external file be loaded before the transformer can operate, you would load the file via the
If you want your transformer to clear up resources when the transformer is no longer needed, your transformer must implement
org.mule.api.lifecycle.Disposable and implement the
Creating Discoverable Transformers
Mule can perform automatic transformations. For example, when you call the
getPayload() method on a MuleMessage and pass in the required type as follows:
Mule looks at the current payload type and tries to find a transformer that can convert it to an
org.dom4j.Document object. Mule provides several standard transformers for switching between common types such as strings, byte, InputStream, and more. Also, transports usually have transformers for specific message types such as JMSMessage or HttpRequest. When creating a custom transformer, you can set its priority higher than the standard transformers so that it takes precedence.
To make a transformer discoverable, it must implementorg.mule.api.transformer.DiscoverableTransformer
. This interface introduces two methods,
setPriorityWeighting(int weighting). Weighting resolves conflicts when two or more transformers match the search criteria. The weighting is a number between 1 and 10, with 10 being the highest priority. As a rule, Mule transformers have a priority of 1 and should always have a lower priority than any custom transformers.
For example, to make the OrderToHtmlTransformer discoverable, you would define it as follows:
This transformer converts from an Order object to a String, which the standard ObjectToString transformer also does, but ObjectToHtml will be used because it has a higher priority weighting. You could test this as follows:
Registering the Transformer
After creating a transformer, you must register it so that Mule can discover it at runtime. You can register the transformer simply by configuring it using the
<custom-transformer> element in your Mule configuration file.
Alternatively, if you want your transformer to be loaded automatically by Mule when your module (JAR) is on the class path, you add a
registry-bootstrap.properties file to your JAR under the
/META-INF/services/org/mule/config directory. The contents of
registry-bootstrap.properties should look something like this:
When Mule starts, it will discover this bootstrap file before loading any configuration and will install any objects listed in the file into the local registry. For more information, see Bootstrapping the Registry.
To create an HTML message that includes the
transactionId from the message header, you would extend
AbstractMessageTransformer and write the
transform() method as follows:
The Hello World example defines a custom transformer called
StringToNameString, which wraps Java string in a custom class called
The transformer is then configured as follows:
Alternatively you can configure transformer directly in the endpoint, as follows: