Message Transformers play a very important role in enabling the loose-coupling of Message Producers and Message Consumers. Rather than requiring every Message-producing component to know what type is expected by the next consumer, Transformers can be added between those components. Generic transformers, such as one that converts a String to an XML Document, are also highly reusable.
For some systems, it may be best to provide a Canonical Data Model, but Spring Integration's general philosophy is not to require any particular format. Rather, for maximum flexibility, Spring Integration aims to provide the simplest possible model for extension. As with the other endpoint types, the use of declarative configuration in XML and/or Annotations enables simple POJOs to be adapted for the role of Message Transformers. These configuration options will be described below.
Note | |
---|---|
For the same reason of maximizing flexibility, Spring does not require XML-based Message payloads. Nevertheless, the framework does provide some convenient Transformers for dealing with XML-based payloads if that is indeed the right choice for your application. For more information on those transformers, see Chapter 23, XML Support - Dealing with XML Payloads. |
The <transformer> element is used to create a Message-transforming endpoint. In addition to "input-channel" and "output-channel" attributes, it requires a "ref". The "ref" may either point to an Object that contains the @Transformer annotation on a single method (see below) or it may be combined with an explicit method name value provided via the "method" attribute.
<transformer id="testTransformer" ref="testTransformerBean" input-channel="inChannel" method="transform" output-channel="outChannel"/> <beans:bean id="testTransformerBean" class="org.foo.TestTransformer" />
Using a "ref" attribute is generally recommended if the custom transformer handler implementation can be reused in
other <transformer>
definitions. However if the custom transformer handler implementation should
be scoped to a single definition of the <transformer>
, you can define an inner bean definition:
<transformer id="testTransformer" input-channel="inChannel" method="transform" output-channel="outChannel"> <beans:bean class="org.foo.TestTransformer"/> </transformer>
Note | |
---|---|
Using both the "ref" attribute and an inner handler definition in the same |
The method that is used for transformation may expect either the Message
type or
the payload type of inbound Messages. It may also accept Message header values either individually or as a full
map by using the @Header and @Headers parameter annotations respectively. The return value of the method can be
any type. If the return value is itself a Message
, that will be passed along to
the transformer's output channel. If the return type is a Map, and the original Message payload was
not a Map, the entries in that Map will be added to the Message headers of the original
Message (the keys must be Strings). If the return value is null, then no reply Message will
be sent (effectively the same behavior as a Message Filter returning false). Otherwise, the return value will be
sent as the payload of an outbound reply Message.
Transformers and Spring Expression Language (SpEL)
Just like Routers, Aggregators and other components, since Spring Integration 2.0 Transformers can also benefit from SpEL http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html whenever transformation logic is relatively simple.
<int:transformer input-channel="inChannel" output-channel="outChannel" expression="payload.toUpperCase() + '- [' + T(java.lang.System).currentTimeMillis() + ']'"/>
In the above configuration we are achieving a simple transformation of the payload with a simple SpEL expression and without writing a custom transformer. Our payload (assuming String) will be upper-cased and concatenated with the current timestamp with some simple formatting.
Common Transformers
There are a also a few Transformer implementations available out of the box. Because, it is fairly common
to use the toString()
representation of an Object, Spring Integration provides an
ObjectToStringTransformer
whose output is a Message with a String payload. That String
is the result of invoking the toString operation on the inbound Message's payload.
<object-to-string-transformer input-channel="in" output-channel="out"/>
A potential example for this would be sending some arbitrary object to the 'outbound-channel-adapter' in the
file namespace. Whereas that Channel Adapter only supports String, byte-array, or
java.io.File
payloads by default, adding this transformer immediately before the
adapter will handle the necessary conversion. Of course, that works fine as long as the result of the
toString()
call is what you want to be written to the File. Otherwise, you can
just provide a custom POJO-based Transformer via the generic 'transformer' element shown previously.
Tip | |
---|---|
When debugging, this transformer is not typically necessary since the 'logging-channel-adapter' is capable of logging the Message payload. Refer to the section called “Wire Tap” for more detail. |
If you need to serialize an Object to a byte array or deserialize a byte array back into an Object, Spring Integration provides symmetrical serialization transformers.
<payload-serializing-transformer input-channel="objectsIn" output-channel="bytesOut"/> <payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"/>
Object-to-Map Transformer
As added convenience, Spring Integration also provides Object-to-Map and Map-to-Object transformers which utilize Spring Expression Language (SpEL) to serialize and de-serialize the object graphs. Object hierarchy is introspected to the most primitive types (e.g., String, int etc.). The path to this type is described via SpEL, which becomes the keykey in the transformed Map with primitive type being the value.
For example:
public class Parent{ private Child child; private String name; // setters and getters are omitted } public class Child{ private String name; private List<String> nickNames; // setters and getters are omitted }
... will be transformed to a Map which looks like this:
{person.name=George, person.child.name=Jenna, person.child.nickNames[0]=Bimbo . . . etc}
SpEL-based Map allows you to describe the object structure without sharing the actual types allowing you to restore/rebuild the object graph into a differently typed Object graph as long as you maintain the structure.
For example: The above structure could be easily restored back to the following Object graph via Map-to-Object transformer:
public class Father{ private Kid child; private String name; // setters and getters are omitted } public class Kid{ private String name; private List<String> nickNames; // setters and getters are omitted }
To configure these transformers, Spring Integration provides namespace support Object-to-Map:
<object-to-map-transformer input-channel="directInput" output-channel="output"/>
Map-to-Object
<int:map-to-object-transformer input-channel="input" output-channel="output" type="org.foo.Person"/>
or
<int:map-to-object-transformer input-channel="inputA" output-channel="outputA" ref="person"/> <bean id="person" class="org.foo.Person" scope="prototype"/>
Note | |
---|---|
NOTE: 'ref' and 'type' attributes are mutually exclusive. You can only use either one. Also, if using 'ref' attribute you must point to a 'prototype' scoped bean, otherwise BeanCreationException will be thrown. |
The @Transformer
annotation can also be added to methods that expect either the
Message
type or the message payload type. The return value will be handled in the
exact same way as described above in the section describing the <transformer> element.
@Transformer Order generateOrder(String productId) { return new Order(productId); }
Transformer methods may also accept the @Header and @Headers annotations that is documented in Section B.5, “Annotation Support”
@Transformer Order generateOrder(String productId, @Header("customerName") String customer) { return new Order(productId, customer); }
<int:header-filter input-channel="inputChannel" output-channel="outputChannel" header-names="lastName, state"/>As you can see, configuration of Header Filter is quite simple. It is a typical endpoint with input/output channels and
header-names
attribute which allows you to specify the names of the headers (delimited by coma if multiple)
that need to be removed. So, in the above example headers with the name 'lastName' and 'state' will be removed.
Some time you may have a requirement to enhance a request with more information then it was provided by the target system. Content Enricher pattern describes various scenarios as well as the component (Enricher), which allows you to address such requirements.
If you only need to add headers to a Message, and they are not dynamically determined by the Message content,
then referencing a custom implementation of the Transformer may be an overkill. For that reason,
Spring Integration provides the Header Enricher which is exposed via <header-enricher>
element.
<int:header-enricher input-channel="in" output-channel="out"> <int:header name="foo" value="123"/> <int:header name="bar" ref="someBean"/> </int:header-enricher>
Header Enricher also provides helpful sub-elements to set well known header names.
<int:header-enricher input-channel="in" output-channel="out"> <int:error-channel ref="applicationErrorChannel"/> <int:reply-channel ref="quoteReplyChannel"/> <int:correlation-id value="123"/> <int:priority value="HIGHEST"/> <int:header name="bar" ref="someBean"/> </int:header-enricher>
In the above configuration you can clearly see that for well known headers such as errorChannel
,
correlationId
, priority
, replyChannel
etc., instead of using generic <header>
sub-element where you would have to provide both header 'name' and 'value', you can use convenient sub-elements
allowing you to set those values directly.
SpEL Support
In Spring Integration 2.0 we are introducing convenience of Spring Expression Language (SpEL) to help configure many different components. Header Enricher is one of them. A lot of times, header value cannot be defined statically and has to be computed dynamically. That is why Header Enricher allows you to also specify bean 'ref' and 'method' that will calculate the header value. Let's look at the following configuration:
<int:header-enricher input-channel="in" output-channel="out"> <int:header name="foo" method="computeValue" ref="myBean"/> </int:header-enricher> <bean id="myBean" class="foo.bar.MyBean"/>
public class MyBean{ public String computeValue(String payload){ return payload.toUpperCase() + "_US"; } }
As you can see that the computation logic to determine the header value is actually pretty simple and the natural question would be is there a simpler way to accomplish this? And that is where SpEL shows its true power.
<int:header-enricher input-channel="in" output-channel="out"> <int:header name="foo" expression="payload.toUpperCase() + '_US'"/> </int:header-enricher>
As you can see, with SpEL for simple cases like above we no longer have to provide a separate class and configure it in the application context. All we need is to use expression attribute and provide a valid SpEL expression. You can also see that 'payload' and 'headers' are bound as variables to the SpEL Evaluation Context giving you full access to the incoming Message.
Adapter specific Header Enrichers
As you go through the manual you will see that as an added convenience Spring Integration provides adapter specific Header Enrichers (e.g., MAIL, XMPP, etc.)
In the earlier sections we've covered several Content Enricher type components that helps you deal with situations where a message is missing a piece of data. We also discussed Content Filtering which lets you remove uninteresting data items from a message. However there are times when we want to remove some data temporarily. For example; In a distributed system we may receive a Message with a very large payload. Some intermittent message processing steps may not need access to this payload and some may only need to access parts of the payload so carrying the large Message through each processing step may cause performance degradation and makes debugging harder.
Claim Check pattern describes mechanism that allows you to store data in a well known place while only maintaining a pointer (Claim Check) to where that data is and pass such pointer around as a payload of a new Message allowing any component within the message flow to get the actual data as soon as it needs it. This approach is very similar to the Certified Mail process where you'll get Claim Check in your mailbox and would have to go to the Post Office to claim your actual package or mail.
Spring Integration provides two types of Claim Check transformers - Incoming Claim Check Transformer and Outgoing Claim Check Transformer as well as convenient namespace-based mechanism to configure them.
Incoming Claim Check Transformer - will transform incoming Message by storing it in the Message Store
identified by message-store
attribute.
<int:claim-check-in id="checkin" input-channel="checkinChannel" message-store="testMessageStore" output-channel="checkoutChannel"/>
In the above configuration the Message that is received on the input-channel
will be persisted to the
Message Store identified with message-store
attribute and indexed with generated ID. That ID is the Claim Check for that Message.
This Claim Check will also become the payload of the new (transformed) Message that will be sent to the output-channel
.
Now, lets assume that at some point you do need access to the actual Message. You can of course access the Message Store manually and get the contents of the Message or you can use the same approach as before except now you will be transforming the Claim Check to the actual Message by using Outgoing Claim Check Transformer.
Incoming Claim Check Transformer allows you to transform a Message from the Message with just a Claim Check to the Message with the original content.
<claim-check-out id="checkout" input-channel="checkoutChannel" message-store="testMessageStore"/>
In the above configuration the Message that is received on the input-channel
has a Claim Check as a payload
and Outgoing Claim Check Transformer will transform it into an original Message by simply querying the
Message store for a Message identified by a Claim Check provided and sending the new Message to the output-channel
.
Although we rarely care about the protocol of the claim checks as long as they work, but it is still worth knowing that current implementation of the actual Claim Check (the pointer) in Spring Integration is UUID to ensure uniqueness.
A word on Message Store
org.springframework.integration.store.MessageStore
is a strategy interface for storing and retrieving messages.
Spring Integration provides two convenient implementations of it. SimpleMessageStore
- In memory Map-based
implementation (default, good for testing) and JdbcMessageStore
- Implementation of MessageStore
that uses relational database via JDBC.