6. Message Transformation

6. Message Transformation
Prev	Part III. Core Messaging	Next

6.1 Transformer

6.1.1 Introduction

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 31, XML Support - Dealing with XML Payloads.

6.1.2 Configuring Transformer

Configuring Transformer with XML

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.

<int: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:

<int: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 `<transformer>` configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.

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.

As of Spring Integration 2.0, a Message Transformer's transformation method can no longer return null. Returning null will result in an exception since a Message Transformer should always be expected to transform each source Message into a valid target Message. In other words, a Message Transformer should not be used as a Message Filter since there is a dedicated <filter> option for that. However, if you do need this type of behavior (where a component might return NULL and that should not be considered an error), a service-activator could be used. Its requires-reply value is FALSE by default, but that can be set to TRUE in order to have Exceptions thrown for NULL return values as with the transformer.

Transformers and Spring Expression Language (SpEL)

Just like Routers, Aggregators and other components, as of Spring Integration 2.0 Transformers can also benefit from SpEL support (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 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.

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

Note

The object-to-string-transformer is very simple; it invokes toString() on the inbound payload. There are two exceptions to this (since 3.0): if the payload is a char[], it invokes new String(payload); if the payload is a byte[], it invokes new String(payload, charset), where charset is "UTF-8" by default. The charset can be modified by supplying the charset attribute on the transformer.

For more sophistication (such as selection of the charset dynamically, at runtime), you can use a SpEL expression-based transformer instead; for example:

<int:transformer input-channel="in" output-channel="out"
		 expression="new java.lang.String(payload, headers['myCharset']" />

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. These will use standard Java serialization by default, but you can provide an implementation of Spring 3.0's Serializer or Deserializer strategies via the 'serializer' and 'deserializer' attributes, respectively.

<int:payload-serializing-transformer input-channel="objectsIn" output-channel="bytesOut"/>

<int:payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"/>

Object-to-Map Transformer

Spring Integration also provides Object-to-Map and Map-to-Object transformers which utilize the Spring Expression Language (SpEL) to serialize and de-serialize the object graphs. The object hierarchy is introspected to the most primitive types (String, int, etc.). The path to this type is described via SpEL, which becomes the key in the transformed Map. The primitive type becomes 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}

The 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 the 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
}

If you need to create a "structured" map, you can provide the 'flatten' attribute. The default value for this attribute is 'true' meaning the default behavior; if you provide a 'false' value, then the structure will be a map of maps.

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: {name=George, child={name=Jenna, nickNames=[Bimbo, ...]}}

To configure these transformers, Spring Integration provides namespace support Object-to-Map:

<int:object-to-map-transformer input-channel="directInput" output-channel="output"/>

<int:object-to-map-transformer input-channel="directInput" output-channel="output" flatten="false"/>

Map-to-Object

<int:map-to-object-transformer input-channel="input" 
                         output-channel="output" 
                          type="org.foo.Person"/>

<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 one. Also, if using the 'ref' attribute, you must point to a 'prototype' scoped bean, otherwise a BeanCreationException will be thrown.

JSON Transformers

Object to JSON and JSON to Object transformers are provided.

<int:object-to-json-transformer input-channel="objectMapperInput"/>

<int:json-to-object-transformer input-channel="objectMapperInput"
    type="foo.MyDomainObject"/>

These use a vanilla Jackson ObjectMapper by default. If you wish to customize the ObjectMapper (for example, to configure the 'ALLOW_COMMENTS' feature when parsing JSON), you can supply a reference to your custom ObjectMapper bean using the object-mapper attribute.

<int:json-to-object-transformer input-channel="objectMapperInput"
    type="foo.MyDomainObject" object-mapper="customObjectMapper"/>

Note

Beginning with version 3.0, the object-mapper attribute references an instance of a new strategy interface JsonObjectMapper. This abstraction allows multiple implementations of json mappers to be used. Implementations that wrap Jackson 1.x and Jackson 2 are provided, with the version being detected on the classpath. These classes are JacksonJsonObjectMapper and Jackson2JsonObjectMapper.

For backward compatibility, a simple Jackson 1.x ObjectMapper can be provided instead of a JsonObjectMapper. This will be removed in a future release.

	Important
If there are requirements to use both Jackson libraries in the same application, keep in mind that before version 3.0, the JSON transformers used only Jackson 1.x and, from 3.0 on, the framework will select Jackson 2 by default, if both are on the classpath. So, to avoid unexpected issues with Jackson's mapping features, when using annotations, there may be a need to apply annotations from both Jacksons on domain classes: @org.codehaus.jackson.annotate.JsonIgnoreProperties(ignoreUnknown=true) @com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown=true) public class Foo { @org.codehaus.jackson.annotate.JsonProperty("fooBar") @com.fasterxml.jackson.annotation.JsonProperty("fooBar") public Object bar; }

Important

If there are requirements to use both Jackson libraries in the same application, keep in mind that before version 3.0, the JSON transformers used only Jackson 1.x and, from 3.0 on, the framework will select Jackson 2 by default, if both are on the classpath. So, to avoid unexpected issues with Jackson's mapping features, when using annotations, there may be a need to apply annotations from both Jacksons on domain classes:

@org.codehaus.jackson.annotate.JsonIgnoreProperties(ignoreUnknown=true)
@com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown=true)
public class Foo {

        @org.codehaus.jackson.annotate.JsonProperty("fooBar")
        @com.fasterxml.jackson.annotation.JsonProperty("fooBar")
        public Object bar;

}

You may wish to consider using a FactoryBean or simple factory method to create the JsonObjectMapper with the required characteristics.

public class ObjectMapperFactory {

    public static Jackson2JsonObjectMapper getMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.configure(JsonParser.Feature.ALLOW_COMMENTS, true);
        return new Jackson2JsonObjectMapper(mapper);
    }
}

<bean id="customObjectMapper" class="foo.ObjectMapperFactory"
            factory-method="getMapper"/>

Important

	Important
Beginning with version 2.2, the `object-to-json-transformer` sets the content-type header to `application/json`, by default, if the input message does not already have that header present. It you wish to set the content type header to some other value, or explicitly overwrite any existing header with some value (including `application/json`), use the `content-type` attribute. If you wish to suppress the setting of the header, set the `content-type` attribute to an empty string (`""`). This will result in a message with no `content-type` header, unless such a header was present on the input message.

Beginning with version 2.2, the object-to-json-transformer sets the content-type header to application/json, by default, if the input message does not already have that header present.

It you wish to set the content type header to some other value, or explicitly overwrite any existing header with some value (including application/json), use the content-type attribute. If you wish to suppress the setting of the header, set the content-type attribute to an empty string (""). This will result in a message with no content-type header, unless such a header was present on the input message.

Beginning with version 3.0, the ObjectToJsonTransformer adds headers, reflecting the source type, to the message. Similarly, the JsonToObjectTransformer can use those type headers when converting the JSON to an object. These headers are mapped in the AMQP adapters so that they are entirely compatible with the Spring-AMQP JsonMessageConverter.

This enables the following flows to work without any special configuration...

...->amqp-outbound-adapter---->

---->amqp-inbound-adapter->json-to-object-transformer->...

Where the outbound adapter is configured with a JsonMessageConverter and the inbound adapter uses the default SimpleMessageConverter.

...->object-to-json-transformer->amqp-outbound-adapter---->

---->amqp-inbound-adapter->...

Where the outbound adapter is configured with a SimpleMessageConverter and the inbound adapter uses the default JsonMessageConverter.

...->object-to-json-transformer->amqp-outbound-adapter---->

---->amqp-inbound-adapter->json-to-object-transformer->

Where both adapters are configured with a SimpleMessageConverter.

	Note
	When using the headers to determine the type, you should not provide a `class` attribute, because it takes precedence over the headers.

In addition to JSON Transformers, Spring Integration provides a built-in #jsonPath SpEL function for use in expressions. For more information see Appendix A, Spring Expression Language (SpEL).

#xpath SpEL Function

Since version 3.0, Spring Integration also provides a built-in #xpath SpEL function for use in expressions. For more information see Section 31.9, “#xpath SpEL Function”.

Configuring a Transformer with Annotations

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 F.5, “Annotation Support”

@Transformer
Order generateOrder(String productId, @Header("customerName") String customer) {
    return new Order(productId, customer);
}

Also see Section 7.7.5, “Advising Endpoints Using Annotations”.

6.1.3 Header Filter

Some times your transformation use case might be as simple as removing a few headers. For such a use case, Spring Integration provides a Header Filter which allows you to specify certain header names that should be removed from the output Message (e.g. for security reasons or a value that was only needed temporarily). Basically the Header Filter is the opposite of the Header Enricher. The latter is discussed in Section 6.2.2, “Header Enricher”

<int:header-filter input-channel="inputChannel"
		output-channel="outputChannel" header-names="lastName, state"/>

As you can see, configuration of a Header Filter is quite simple. It is a typical endpoint with input/output channels and a header-names attribute. That attribute accepts the names of the header(s) (delimited by commas if there are multiple) that need to be removed. So, in the above example the headers named 'lastName' and 'state' will not be present on the outbound Message.

6.2 Content Enricher

6.2.1 Introduction

At times you may have a requirement to enhance a request with more information than was provided by the target system. The Content Enricher pattern describes various scenarios as well as the component (Enricher), which allows you to address such requirements.

The Spring Integration Core module includes 2 enrichers:

Furthermore, several Adapter specific Header Enrichers are included as well:

Please go to the adapter specific sections of this reference manual to learn more about those adapters.

For more information regarding expressions support, please see Appendix A, Spring Expression Language (SpEL).

6.2.2 Header Enricher

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 a Transformer may be overkill. For that reason, Spring Integration provides support for the Header Enricher pattern. It is exposed via the <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>

The 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, replyChanneletc., instead of using generic <header> sub-elements where you would have to provide both header 'name' and 'value', you can use convenient sub-elements to set those values directly.

POJO Support

Often a header value cannot be defined statically and has to be determined dynamically based on some content in the Message. That is why Header Enricher allows you to also specify a bean reference using the ref and method attribute. The specified method 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";
    }

}

You can also configure your POJO as inner bean:

<int:header-enricher  input-channel="inputChannel" output-channel="outputChannel">
	<int:header name="some_header">
            <bean class="org.MyEnricher"/>
        </int:header>
</int:header-enricher>

as well as point to a Groovy script:

<int:header-enricher  input-channel="inputChannel" output-channel="outputChannel">
		<int:header name="some_header">
            <int-groovy:script location="org/SampleGroovyHeaderEnricher.groovy"/>
        </int:header>
</int:header-enricher>

SpEL Support

In Spring Integration 2.0 we have introduced the convenience of the Spring Expression Language (SpEL) to help configure many different components. The Header Enricher is one of them. Looking again at the POJO example above, you can see that the computation logic to determine the header value is actually pretty simple. A natural question would be: "is there a simpler way to accomplish this?". 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, by using SpEL for such simple cases, we no longer have to provide a separate class and configure it in the application context. All we need is the expression attribute configured with a valid SpEL expression. The 'payload' and 'headers' variables are bound to the SpEL Evaluation Context, giving you full access to the incoming Message.

Header Channel Registry

Starting with Spring Integration 3.0, a new sub-element <int:header-channels-to-string/> is available; it has no attributes. This converts existing replyChannel and errorChannel headers (when they are a MessageChannel) to a String and stores the channel(s) in a registry for later resolution when it is time to send a reply, or handle an error. This is useful for cases where the headers might be lost; for example when serializing a message into a message store or when transporting the message over JMS. If the header does not already exist, or it is not a MessageChannel, no changes are made.

Use of this functionality requires the presence of a HeaderChannelRegistry bean. By default, the framework creates a DefaultHeaderChannelRegistry with the default expiry (60 seconds). Channels are removed from the registry after this time. To change this, simply define a bean with id integrationHeaderChannelRegistry and configure the required delay using a constructor argument (milliseconds).

The HeaderChannelRegistry has a size() method to determine the current size of the registry. The runReaper() method cancels the current scheduled task and runs the reaper immediately; the task is then scheduled to run again based on the current delay. These methods can be invoked directly by getting a reference to the registry, or you can send a message with, for example, the following content to a control bus:

"@integrationHeaderChannelRegistry.runReaper()"

This sub-element is a convenience only, and is the equivalent of specifying:

<int:reply-channel
	expression="@integrationHeaderChannelRegistry.channelToChannelName(headers.replyChannel)"/>
<int:error-channel
	expression="@integrationHeaderChannelRegistry.channelToChannelName(headers.errorChannel)"/>

	Tip
	For more examples for configuring header enrichers, see Header Enricher Advanced Configuration.

6.2.3 Payload Enricher

In certain situations the Header Enricher, as discussed above, may not be sufficient and payloads themselves may have to be enriched with additional information. For example, order messages that enter the Spring Integration messaging system have to look up the order's customer based on the provided customer number and then enrich the original payload with that information.

Since Spring Integration 2.1, the Payload Enricher is provided. A Payload Enricher defines an endpoint that passes a Message to the exposed request channel and then expects a reply message. The reply message then becomes the root object for evaluation of expressions to enrich the target payload.

The Payload Enricher provides full XML namespace support via the enricher element. In order to send request messages, the payload enricher has a request-channel attribute that allows you to dispatch messages to a request channel.

Basically by defining the request channel, the Payload Enricher acts as a Gateway, waiting for the message that were sent to the request channel to return, and the Enricher then augments the message's payload with the data provided by the reply message.

When sending messages to the request channel you also have the option to only send a subset of the original payload using the request-payload-expression attribute.

The enriching of payloads is configured through SpEL expressions, providing users with a maximum degree of flexibility. Therefore, users are not only able to enrich payloads with direct values from the reply channel's Message, but they can use SpEL expressions to extract a subset from that Message, only, or to apply addtional inline transformations, allowing them to further manipulate the data.

If you only need to enrich payloads with static values, you don't have to provide the request-channel attribute.

	Note
	Enrichers are a variant of Transformers and in many cases you could use a Payload Enricher or a generic Transformer implementation to add additional data to your messages payloads. Thus, familiarize yourself with all transformation-capable components that are provided by Spring Integration and carefully select the implementation that semantically fits your business case best.

Configuration

Below, please find an overview of all available configuration options that are available for the payload enricher:

<int:enricher request-channel=""                          
              auto-startup="true"                         
              id=""                                       
              order=""                                    
              output-channel=""                           
              request-payload-expression=""               
              reply-channel=""                            
              send-timeout=""                             
              should-clone-payload="false">               
    <int:poller></int:poller>                             
    <int:property name="" expression=""/>  
    <int:property name="" value=""/>
	<int:header name="" expression=""/>  
    <int:header name="" value="" overwrite="" type=""/>
</int:enricher>

	Channel to which a Message will be sent to get the data to use for enrichment. Optional.
	Lifecycle attribute signaling if this component should be started during Application Context startup. Defaults to true. Optional.
	Id of the underlying bean definition, which is either an `EventDrivenConsumer` or a `PollingConsumer`. Optional.
	Specifies the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel is using a "failover" dispatching strategy. It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue. Optional.
	Identifies the Message channel where a Message will be sent after it is being processed by this endpoint. Optional.
	By default the original message's payload will be used as payload that will be send to the `request-channel`. By specifying a SpEL expression as value for the `request-payload-expression` attribute, a subset of the original payload, a header value or any other resolvable SpEL expression can be used as the basis for the payload, that will be sent to the request-channel. For the Expression evaluation the full message is available as the 'root object'. For instance the following SpEL expressions (among others) are possible: payload.foo headers.foobar new java.util.Date() 'foo' + 'bar' If more sophisticated logic is required (e.g. changing the message headers etc.) please use additional downstream transformers. Optional.
	Channel where a reply Message is expected. This is optional; typically the auto-generated temporary reply channel is sufficient. Optional.
	Maximum amount of time in milliseconds to wait when sending a message to the channel, if such channel may block. For example, a Queue Channel can block until space is available, if its maximum capacity has been reached. Internally the send timeout is set on the `MessagingTemplate` and ultimately applied when invoking the send operation on the `MessageChannel`. By default the send timeout is set to '-1', which may cause the send operation on the `MessageChannel`, depending on the implementation, to block indefinitely. Optional.
	Boolean value indicating whether any payload that implements `Cloneable` should be cloned prior to sending the Message to the request chanenl for acquiring the enriching data. The cloned version would be used as the target payload for the ultimate reply. Default is `false`. Optional.
	Allows you to configure a Message Poller if this endpoint is a Polling Consumer. Optional.
	Each `property` sub-element provides the name of a property (via the mandatory `name` attribute). That property should be settable on the target payload instance. Exactly one of the `value` or `expression` attributes must be provided as well. The former for a literal value to set, and the latter for a SpEL expression to be evaluated. The root object of the evaluation context is the Message that was returned from the flow initiated by this enricher, the input Message if there is no request channel, or the application context (using the '@<beanName>.<beanProperty>' SpEL syntax).
	Each `header` sub-element provides the name of a Message header (via the mandatory `name` attribute). Exactly one of the `value` or `expression` attributes must be provided as well. The former for a literal value to set, and the latter for a SpEL expression to be evaluated. The root object of the evaluation context is the Message that was returned from the flow initiated by this enricher, the input Message if there is no request channel, or the application context (using the '@<beanName>.<beanProperty>' SpEL syntax). Note, similar to the `<header-enricher>`, the `<enricher>`'s `header` element has `type` and `overwrite` attributes. However, a difference is that, with the `<enricher>`, the `overwrite` attribute is `true` by default, to be consistent with `<enricher>`'s `<property>` sub-element.

Examples

Below, please find several examples of using a Payload Enricher in various situations.

In the following example, a User object is passed as the payload of the Message. The User has several properties but only the username is set initially. The Enricher's request-channel attribute below is configured to pass the User on to the findUserServiceChannel.

Through the implicitly set reply-channel a User object is returned and using the property sub-element, properties from the reply are extracted and used to enrich the original payload.

<int:enricher id="findUserEnricher"
              input-channel="findUserEnricherChannel"
              request-channel="findUserServiceChannel">
    <int:property name="email"    expression="payload.email"/>
    <int:property name="password" expression="payload.password"/>
</int:enricher>

	Note
	The code samples shown here, are part of the Spring Integration Samples project. Please feel free to check it out at: https://github.com/SpringSource/spring-integration-samples

How do I pass only a subset of data to the request channel?

Using a request-payload-expression attribute a single property of the payload can be passed on to the request channel instead of the full message. In the example below on the username property is passed on to the request channel. Keep in mind, that alwhough only the username is passed on, the resulting message send to the request channel will contain the full set of MessageHeaders.

<int:enricher id="findUserByUsernameEnricher"
              input-channel="findUserByUsernameEnricherChannel"
              request-channel="findUserByUsernameServiceChannel"
              request-payload-expression="payload.username">
    <int:property name="email"    expression="payload.email"/>
    <int:property name="password" expression="payload.password"/>
</int:enricher>

How can I enrich payloads that consist of Collection data?

In the following example, instead of a User object, a Map is passed in. The Map contains the username under the map key username. Only the username is passed on to the request channel. The reply contains a full User object, which is ultimately added to the Map under the user key.

<int:enricher id="findUserWithMapEnricher"
              input-channel="findUserWithMapEnricherChannel"
              request-channel="findUserByUsernameServiceChannel"
              request-payload-expression="payload.username">
    <int:property name="user"    expression="payload"/>
</int:enricher>

How can I enrich payloads with static information without using a request channel?

Here is an example that does not use a request channel at all, but solely enriches the message's payload with static values. But please be aware that the word 'static' is used loosly here. You can still use SpEL expressions for setting those values.

<int:enricher id="userEnricher"
              input-channel="input">
    <int:property name="user.updateDate" expression="new java.util.Date()"/>
    <int:property name="user.firstName" value="foo"/>
    <int:property name="user.lastName"  value="bar"/>
    <int:property name="user.age"       value="42"/>
</int:enricher>

6.3 Claim Check

6.3.1 Introduction

In the earlier sections we've covered several Content Enricher type components that help you deal with situations where a message is missing a piece of data. We also discussed Content Filtering which lets you remove data items from a message. However there are times when we want to hide 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 certain headers, so carrying the large Message payload through each processing step may cause performance degradation, may produce a security risk, and may make debugging more difficult.

The Claim Check pattern describes a mechanism that allows you to store data in a well known place while only maintaining a pointer (Claim Check) to where that data is located. You can pass that pointer around as a payload of a new Message thereby 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 a Claim Check in your mailbox and would have to go to the Post Office to claim your actual package. Of course it's also the same idea as baggage-claim on a flight or in a hotel.

Spring Integration provides two types of Claim Check transformers:

Incoming Claim Check Transformer
Outgoing Claim Check Transformer

Convenient namespace-based mechanisms are available to configure them.

6.3.2 Incoming Claim Check Transformer

An Incoming Claim Check Transformer will transform an incoming Message by storing it in the Message Store identified by its message-store attribute.

<int:claim-check-in id="checkin"
        input-channel="checkinChannel"
        message-store="testMessageStore"
        output-channel="output"/>

In the above configuration the Message that is received on the input-channel will be persisted to the Message Store identified with the message-store attribute and indexed with generated ID. That ID is the Claim Check for that Message. The 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 an Outgoing Claim Check Transformer.

Here is an overview of all available parameters of an Incoming Claim Check Transformer:

<int:claim-check-in auto-startup="true" 
                    id=""                          
                    input-channel=""               
                    message-store="messageStore"   
                    order=""                       
                    output-channel=""              
                    send-timeout="">               
    <int:poller></int:poller>                      
</int:claim-check-in>

	Lifecycle attribute signaling if this component should be started during Application Context startup. Defaults to true. Attribute is not available inside a `Chain` element. Optional.
	Id identifying the underlying bean definition (`MessageTransformingHandler`). Attribute is not available inside a `Chain` element. Optional.
	The receiving Message channel of this endpoint. Attribute is not available inside a `Chain` element. Optional.
	Reference to the MessageStore to be used by this Claim Check transformer. If not specified, the default reference will be to a bean named messageStore. Optional.
	Specifies the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel is using a failover dispatching strategy. It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue. Attribute is not available inside a `Chain` element. Optional.
	Identifies the Message channel where Message will be sent after its being processed by this endpoint. Attribute is not available inside a `Chain` element. Optional.
	Specify the maximum amount of time in milliseconds to wait when sending a reply Message to the output channel. By default the send will block for one second. Attribute is not available inside a `Chain` element. Optional.
	Defines a poller. Element is not available inside a `Chain` element. Optional.

6.3.3 Outgoing Claim Check Transformer

An Outgoing Claim Check Transformer allows you to transform a Message with a Claim Check payload into a Message with the original content as its payload.

<int:claim-check-out id="checkout"
        input-channel="checkoutChannel"
        message-store="testMessageStore"
        output-channel="output"/>

In the above configuration, the Message that is received on the input-channel should have a Claim Check as its payload and the Outgoing Claim Check Transformer will transform it into a Message with the original payload by simply querying the Message store for a Message identified by the provided Claim Check. It then sends the newly checked-out Message to the output-channel.

Here is an overview of all available parameters of an Outgoing Claim Check Transformer:

<int:claim-check-out auto-startup="true" 
                     id=""                          
                     input-channel=""               
                     message-store="messageStore"   
                     order=""                       
                     output-channel=""              
                     remove-message="false"         
                     send-timeout="">               
    <int:poller></int:poller>                       
</int:claim-check-out>

	Lifecycle attribute signaling if this component should be started during Application Context startup. Defaults to true. Attribute is not available inside a `Chain` element. Optional.
	Id identifying the underlying bean definition (`MessageTransformingHandler`). Attribute is not available inside a `Chain` element. Optional.
	The receiving Message channel of this endpoint. Attribute is not available inside a `Chain` element. Optional.
	Reference to the MessageStore to be used by this Claim Check transformer. If not specified, the default reference will be to a bean named messageStore. Optional.
	Specifies the order for invocation when this endpoint is connected as a subscriber to a channel. This is particularly relevant when that channel is using a failover dispatching strategy. It has no effect when this endpoint itself is a Polling Consumer for a channel with a queue. Attribute is not available inside a `Chain` element. Optional.
	Identifies the Message channel where Message will be sent after its being processed by this endpoint. Attribute is not available inside a `Chain` element. Optional.
	If set to `true` the Message will be removed from the MessageStore by this transformer. Useful when Message can be "claimed" only once. Defaults to `false`. Optional.
	Specify the maximum amount of time in milliseconds to wait when sending a reply Message to the output channel. By default the send will block for one second. Attribute is not available inside a `Chain` element. Optional.
	Defines a poller. Element is not available inside a `Chain` element. Optional.

Claim Once

There are scenarios when a particular message must be claimed only once. As an analogy, consider the airplane luggage check-in/out process. Checking-in your luggage on departure and and then claiming it on arrival is a classic example of such a scenario. Once the luggage has been claimed, it can not be claimed again without first checking it back in. To accommodate such cases, we introduced a remove-message boolean attribute on the claim-check-out transformer. This attribute is set to false by default. However, if set to true, the claimed Message will be removed from the MessageStore, so that it can no longer be claimed again.

This is also something to consider in terms of storage space, especially in the case of the in-memory Map-based SimpleMessageStore, where failing to remove the Messages could ultimately lead to an OutOfMemoryException. Therefore, if you don't expect multiple claims to be made, it's recommended that you set the remove-message attribute's value to true.

<int:claim-check-out id="checkout"
        input-channel="checkoutChannel"
        message-store="testMessageStore"
        output-channel="output"
        remove-message="true"/>

6.3.4 A word on Message Store

Although we rarely care about the details of the claim checks as long as they work, it is still worth knowing that the current implementation of the actual Claim Check (the pointer) in Spring Integration is a UUID to ensure uniqueness.

org.springframework.integration.store.MessageStore is a strategy interface for storing and retrieving messages. Spring Integration provides two convenient implementations of it. SimpleMessageStore: an in-memory, Map-based implementation (the default, good for testing) and JdbcMessageStore: an implementation that uses a relational database via JDBC.