7. Message Transformation

7. Message Transformation
Prev	Part IV. Core Messaging	Next

7.1 Transformer

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

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

Object-to-String Transformer

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 and Map-to-Object Transformers

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.

Stream Transformer

The StreamTransformer transforms InputStream payloads to a byte[] or a String if a charset is provided.

<int:stream-transformer input-channel="directInput" output-channel="output"/> <!-- byte[] -->

<int:stream-transformer id="withCharset" charset="UTF-8"
    input-channel="charsetChannel" output-channel="output"/> <!-- String -->

@Bean
@Transformer(inputChannel = "stream", outputChannel = "data")
public StreamTransformer streamToBytes() {
    return new StreamTransformer(); // transforms to byte[]
}

@Bean
@Transformer(inputChannel = "stream", outputChannel = "data")
public StreamTransformer streamToString() {
    return new StreamTransformer("UTF-8"); // transforms to String
}

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 JsonObjectMapper by default based on implementation from classpath. You can provide your own custom JsonObjectMapper implementation with appropriate options or based on required library (e.g. GSON).

<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 wraphttps://github.com/RichardHightower/boon[Boon] and Jackson 2 are provided, with the version being detected on the classpath. These classes are BoonJsonObjectMapper and Jackson2JsonObjectMapper.

Note, BoonJsonObjectMapper is provided since version 4.1.

	Important
If there are requirements to use both Jackson libraries and/or Boon in the same application, keep in mind that before version 3.0, the JSON transformers used only Jackson 1.x. From 4.1 on, the framework will select Jackson 2 by default ahead of the Boon implementation if both are on the classpath. Jackson 1.x is no longer supported by the framework internally but, of course, you can still use it within your code. To avoid unexpected issues with JSON mapping features, when using annotations, there may be a need to apply annotations from both Jacksons and/or Boon on domain classes: @org.codehaus.jackson.annotate.JsonIgnoreProperties(ignoreUnknown=true) @com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown=true) @org.boon.json.annotations.JsonIgnoreProperties("foo") public class Foo { @org.codehaus.jackson.annotate.JsonProperty("fooBar") @com.fasterxml.jackson.annotation.JsonProperty("fooBar") @org.boon.json.annotations.JsonProperty("fooBar") public Object bar; }

Important

If there are requirements to use both Jackson libraries and/or Boon in the same application, keep in mind that before version 3.0, the JSON transformers used only Jackson 1.x. From 4.1 on, the framework will select Jackson 2 by default ahead of the Boon implementation if both are on the classpath. Jackson 1.x is no longer supported by the framework internally but, of course, you can still use it within your code. To avoid unexpected issues with JSON mapping features, when using annotations, there may be a need to apply annotations from both Jacksons and/or Boon on domain classes:

@org.codehaus.jackson.annotate.JsonIgnoreProperties(ignoreUnknown=true)
@com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown=true)
@org.boon.json.annotations.JsonIgnoreProperties("foo")
public class Foo {

        @org.codehaus.jackson.annotate.JsonProperty("fooBar")
        @com.fasterxml.jackson.annotation.JsonProperty("fooBar")
        @org.boon.json.annotations.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 35.9, “#xpath SpEL Function”.

Beginning with version 4.0, the ObjectToJsonTransformer supports the resultType property, to specify the node JSON representation. The result node tree representation depends on the implementation of the provided JsonObjectMapper. By default, the ObjectToJsonTransformer uses a Jackson2JsonObjectMapper and delegates the conversion of the object to the node tree to the ObjectMapper#valueToTree method. The node JSON representation provides efficiency for using the JsonPropertyAccessor, when the downstream message flow uses SpEL expressions with access to the properties of the JSON data. See Section A.4, “PropertyAccessors”. When using Boon, the NODE representation is a Map<String, Object>

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

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

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

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

7.1.4 Codec-Based Transformers

See Section 7.4, “Codec”.

7.2 Content Enricher

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

7.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"/>
    <routing-slip value="channel1; routingSlipRoutingStrategy; request.headers[myRoutingSlipChannel]"/>
    <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, routing-slip etc., 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.

Starting with version 4.1 the Header Enricher provides routing-slip sub-element. See the section called “Routing Slip” for more information.

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.

Configuring a Header Enricher with Java Configuration

The following are some examples of Java Configuration for header enrichers:

@Bean
@Transformer(inputChannel = "enrichHeadersChannel", outputChannel = "emailChannel")
public HeaderEnricher enrichHeaders() {
    Map<String, ? extends HeaderValueMessageProcessor<?>> headersToAdd =
            Collections.singletonMap("emailUrl",
                      new StaticHeaderValueMessageProcessor<>(this.imapUrl));
    HeaderEnricher enricher = new HeaderEnricher(headersToAdd);
    return enricher;
}

@Bean
@Transformer(inputChannel="enrichHeadersChannel", outputChannel="emailChannel")
public HeaderEnricher enrichHeaders() {
    Map<String, HeaderValueMessageProcessor<?>> headersToAdd = new HashMap<>();
    headersToAdd.put("emailUrl", new StaticHeaderValueMessageProcessor<String>(this.imapUrl));
    Expression expression = new SpelExpressionParser().parseExpression("payload.from[0].toString()");
    headersToAdd.put("from",
               new ExpressionEvaluatingHeaderValueMessageProcessor<>(expression, String.class));
    HeaderEnricher enricher = new HeaderEnricher(headersToAdd);
    return enricher;
}

The first adds a single literal header. The second adds two headers - a literal header and one based on a SpEL expression.

Configuring a Header Enricher with the Java DSL

The following is an example of Java DSL Configuration for a header enricher:

@Bean
public IntegrationFlow enrichHeadersInFlow() {
    return f -> f
                ...
                .enrichHeaders(h -> h.header("emailUrl", this.emailUrl)
                                     .headerExpression("from", "payload.from[0].toString()"))
                .handle(...);
}

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 default delay using a constructor argument (milliseconds).

Since version 4.1, you can set a property removeOnGet to true on the <bean/> definition, and the mapping entry will be removed immediately on first use. This might be useful in a high-volume environment and when the channel is only used once, rather than waiting for the reaper to remove it.

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)"
    overwrite="true" />
<int:error-channel
    expression="@integrationHeaderChannelRegistry.channelToChannelName(headers.errorChannel)"
    overwrite="true" />

Starting with version 4.1, you can now override the registry’s configured reaper delay, so the the channel mapping is retained for at least the specified time, regardless of the reaper delay:

<int:header-enricher input-channel="inputTtl" output-channel="next">
    <int:header-channels-to-string time-to-live-expression="120000" />
</int:header-enricher>

<int:header-enricher input-channel="inputCustomTtl" output-channel="next">
    <int:header-channels-to-string
        time-to-live-expression="headers['channelTTL'] ?: 120000" />
</int:header-enricher>

In the first case, the time to live for every header channel mapping will be 2 minutes; in the second case, the time to live is specified in the message header and uses an elvis operator to use 2 minutes if there is no header.

7.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=""                             
              error-channel=""                             
              send-timeout=""                              
              should-clone-payload="false">                
    <int:poller></int:poller>                              
    <int:property name="" expression="" null-result-expression="'Could not determine the name'"/>   
    <int:property name="" value="23" type="java.lang.Integer" null-result-expression="'0'"/>
    <int:header name="" expression="" null-result-expression=""/>   
    <int:header name="" value="" overwrite="" type="" null-result-expression=""/>
</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'`.
	Channel where a reply Message is expected. This is optional; typically the auto-generated temporary reply channel is sufficient. Optional.
	Channel to which an `ErrorMessage` will be sent if an `Exception` occurs downstream of the `request-channel`. This enables you to return an alternative object to use for enrichment. This is optional; if it is not set then `Exception` is thrown to the caller. 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). Starting with 4.0, when specifying a `value` attribute, you can also specify an optional `type` attribute. When the destination is a typed setter method, the framework will coerce the value appropriately (as long as a `PropertyEditor`) exists to handle the conversion. If however, the target payload is a `Map` the entry will be populated with the value without conversion. The `type` attribute allows you to, say, convert a String containing a number to an `Integer` value in the target payload. Starting with 4.1, you can also specify an optional `null-result-expression` attribute. When the `enricher` returns null, it will be evaluated and the output of the evaluation will be returned instead.
	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. Starting with 4.1, you can also specify an optional `null-result-expression` attribute. When the `enricher` returns null, it will be evaluated and the output of the evaluation will be returned instead.

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

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 although 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 loosely 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>

7.3 Claim Check

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

7.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. Defaults to `-1` - blocking indefinitely. Attribute is not available inside a `Chain` element. Optional.
	Defines a poller. Element is not available inside a `Chain` element. Optional.

7.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. Defaults to `-1` - blocking indefinitely. 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"/>

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

7.4 Codec

7.4.1 Introduction

Spring Integration version 4.2 introduces the Codec abstraction. Codecs are used to encode/decode objects to/from byte[]. They are an alternative to Java Serialization. One advantage is, typically, objects do not have to implement Serializable. One implementation, using Kryo for serialization, is provided but you can provide your own implementation for use in any of these components:

EncodingPayloadTransformer
DecodingTransformer
CodecMessageConverter

See their JavaDocs for more information.

7.4.2 EncodingPayloadTransformer

This transformer encodes the payload to a byte[] using the codec. It does not affect message headers.

7.4.3 DecodingTransformer

This transformer decodes a byte[] using the codec; it needs to be configured with the Class to which the object should be decoded (or an expression that resolves to a Class). If the resulting object is a Message<?>, inbound headers will not be retained.

7.4.4 CodecMessageConverter

Certain endpoints (e.g. TCP, Redis) have no concept of message headers; they support the use of a MessageConverter and the CodecMessageConverter can be used to convert a message to/from a byte[] for transmission.

7.4.5 Kryo

Currently, this is the only implementation of Codec. There are two Codec s - PojoCodec which can be used in the transformers and MessageCodec which can be used in the CodecMessageConverter.

Several custom serializers are provided by the framework:

FileSerializer
MessageHeadersSerializer
MutableMessageHeadersSerializer

The first can be used with the PojoCodec, by initializing it with the FileKryoRegistrar. The second and third are used with the MessageCodec, which is initialized with the MessageKryoRegistrar.

Customizing Kryo

By default, Kryo delegates unknown Java types to its FieldSerializer. Kryo also registers default serializers for each primitive type along with String, Collection and Map serializers. FieldSerializer uses reflection to navigate the object graph. A more efficient approach is to implement a custom serializer that is aware of the object’s structure and can directly serialize selected primitive fields:

public class AddressSerializer extends Serializer<Address> {

    @Override
    public void write(Kryo kryo, Output output, Address address) {
        output.writeString(address.getStreet());
        output.writeString(address.getCity());
        output.writeString(address.getCountry());
    }

    @Override
    public Address read(Kryo kryo, Input input, Class<Address> type) {
        return new Address(input.readString(), input.readString(), input.readString());
    }
}

The Serializer interface exposes Kryo, Input, and Output which provide complete control over which fields are included and other internal settings as described in the documentation.

Note

When registering your custom serializer, you need a registration ID. The registration IDs are arbitrary but in our case must be explicitly defined because each Kryo instance across the distributed application must use the same IDs. Kryo recommends small positive integers, and reserves a few ids (value < 10). Spring Integration currently defaults to using 40, 41 and 42 (for the file and message header serializers mentioned above); we recommend you start at, say 60, to allow for expansion in the framework. These framework defaults can be overridden by configuring the registrars mentioned above.

Using a Custom Kryo Serializer

If custom serialization is indicated, please consult the Kryo documentation since you will be using the native API. For an example, see the MessageCodec.

Implementing KryoSerializable

If you have write access to the domain object source code it may implement KryoSerializable as described here. In this case the class provides the serialization methods itself and no further configuration is required. This has the advantage of being much simpler to use with XD, however benchmarks have shown this is not quite as efficient as registering a custom serializer explicitly:

public class Address implements KryoSerializable {
    ...

    @Override
    public void write(Kryo kryo, Output output) {
        output.writeString(this.street);
        output.writeString(this.city);
        output.writeString(this.country);
    }

    @Override
    public void read(Kryo kryo, Input input) {
        this.street = input.readString();
        this.city = input.readString();
        this.country = input.readString();
    }
}

Note that this technique can also be used to wrap a serialization library other than Kryo.

Using DefaultSerializer Annotation

Kryo also provides an annotation as described here.

@DefaultSerializer(SomeClassSerializer.class)
public class SomeClass {
       // ...
}

If you have write access to the domain object this may be a simpler alternative to specify a custom serializer. Note this does not register the class with an ID, so your mileage may vary.