Spring Integration 3.0 to 4.0 Migration Guide

Core classes/interfaces from Spring Integration have been moved to Spring Framework 4.0.

Users with direct references to the following classes, in order to migrate to Spring Integration 4.0 will need to change import statements to reflect these changes.

Users who do not reference framework classes from their own (POJO) code, and use the integration namespace to configure their components will need no changes.

The following classes have been moved

from org.springframework.integration to org.springframework.messaging:

• Message
• MessageChannel
• MessageHandler
• MessageHeaders
• PollableChannel
• SubscribableChannel
• MessagingException
• MessageHandlingException
• MessageDeliveryException

from org.springframework.integration.core to org.springframework.messaging:

• MessageHandler
• MessagePostProcessor

from org.springframework.integration.channel.interceptor to org.springframework.messaging.support:

• ChannelInterceptorAdapter

from org.springframework.integration.message to org.springframework.messaging.support:

• ErrorMessage
• GenericMessage

from org.springframework.integration.support.channel to org.springframework.messaging.core:

• ChannelResolver - now a Generic-typed DestinationResolver<MessageChannel>
• The resolveChannelName() method is also renamed to resolvedDestination()

In addition, MessageHeaders constants (for integration-specific headers, e.g CORRELATION_ID, SEQUENCE_SIZE) have been moved to IntegrationMessageHeaderAccessor. Message header accessors provide convenient typed accessor methods for these headers.

##Spring Integration Global Properties

Spring Integration starting with version 3.0 introduced global options, which can be changed using META-INF/integration.properties file or integrationGlobalProperties bean. Since version 4.0 those properties have been enriched with spring.integraton. prefix. Here is a list of all supported global options with their default values:

spring.integraton.channels.autoCreate=true
spring.integraton.channels.maxUnicastSubscribers=0x7fffffff
spring.integraton.channels.maxBroadcastSubscribers=0x7fffffff
spring.integraton.taskScheduler.poolSize=10
spring.integraton.messagingTemplate.throwExceptionOnLateReply=false

JSON transformers

The backward compatibility for object-mapper option of the <object-to-json-transformer/> and <json-to-object-transformer/> components has beed removed. Now they support only reference to the org.springframework.integration.support.json.JsonObjectMapper impementation.

Global Channel Interceptors

Previously, there were some issues with the timing of applying global channel interceptors to channels. In particular, with interceptors that referenced channels themselves (such as WireTap), the channel was never a candidate for interception themselves (by any interceptor); secondly, these channels could not be implicitly declared (as the input-channel on some consumer).

Interceptors are now applied immediately after all beans have been instantiated, solving both these problems.

One side effect of this is that interceptors that reference channels will likely intercept their own channel(s). While framework interceptors (such as WireTap) have runtime protection to avoid invoking the interceptor a second time, custom user interceptors may not.

With this release, a new interface VetoCapableIntercepter allows an interceptor to veto the interception on a particular channel. The wire tap uses this to prevent it's output channel being intercepted by itself.

Users should be aware of this behavior change and update their configuration and/or ChannelInterceptors accordingly.

JDBC Channel Message Store

Since <priority-queue> supports the message-store option the new PriorityCapableChannelMessageStore has been introduced. One of the implementations is JdbcChannelMessageStore. With that the new MESSAGE_PRIORITY column is added to the INT_CHANNEL_MESSAGE. In addition, to have more robust sequential message polling, one more MESSAGE_SEQUENCE column is added, too. The sequence value is provided by vendor specific indentity feature.

Check the SQL scripts for your RDBMS in the package org.springframework.integration.jdbc.store.channel of spring-integration-jdbc-4.0.RELEASE.jar. And be sure to use correct ChannelMessageStoreQueryProvider implementation for JdbcChannelMessageStore.

If Spring Integration doesn't provide SQL-scripts and ChannelMessageStoreQueryProvider implementation for some vendors, let us know via JIRA or contributions welcome!.

MongoDB Message Store

Since MongoDbMessageStore stores documents for messages with type information, e.g.

...
   "payload" : {
        "_class" : "org.springframework.integration.handler.DelayHandler$DelayedMessageWrapper",
        "requestDate" : NumberLong(1402604538225),
        "original" : {
            "_class" : "org.springframework.integration.message.GenericMessage",
            "payload" : {
...

there will be some 'type mismatch' error after upgrade to Spring Integratio 4.0 from the store based on previous version of the Framework. That's because GenericMessage has been moved to the package org.springframework.messaging.support.

The best way to overcome the issue to manually UPDATE all documents from messages collection to the new type:

db.messages.update(
	{},
	{ $set: { _messageType : "org.springframework.messaging.support.GenericMessage" } 
        },
	{
		multi: true
	}
)

db.messages.update(
	{'payload._class' : "org.springframework.integration.message.GenericMessage"},
	{ $set: { 'payload._class' : "org.springframework.messaging.support.GenericMessage"} },
	{
		multi: true
	}
)

db.messages.update(
        {'payload._class' : "org.springframework.integration.handler.DelayHandler$DelayedMessageWrapper"},
	{ $set: { 'payload.origin._class' : "org.springframework.messaging.support.GenericMessage"} },
	{
		multi: true
	}
)

Note: we can't add backward compatibility to read documents with old org.springframework.integration.message.GenericMessage type, because this class doesn't exist any more and we won't be able to convert BSON to MongoDbMessageStore$MessageWrapper object correctly.

##HTTP

Before Spring Integration 4.0 the MessageHeaders.CONTENT_TYPE constant had had a value content-type. It was appropriate header name to be mapped to the HTTP header Content-Type. But since migration to Spring Messaging MessageHeaders.CONTENT_TYPE constant has a value contentType. It prevented to map Message header to the HTTP request properly. To do the proper HTTP Content-Type header population you should manually re-map MessageHeaders.CONTENT_TYPE header to an additional content-type header using <header-enricher> to allow to propagate Message state to the HTTP request automatically:

<int:chain>
     <int:object-to-json-transformer/>
     <int:header-enricher>
         <int:header name="#{T(org.springframework.http.HttpHeaders).CONTENT_TYPE}" 
             expression="headers[T(org.springframework.messaging.MessageHeaders).CONTENT_TYPE]"/>
     </int:header-enricher>
     <int-http:outbound-gateway url="http://service"/>
</int:chain>