Spring Integration 1.0 to 2.0 Migration Guide

Dependencies

Spring Integration 2.0 builds upon Spring 3.0, so you will need to upgrade the underlying Spring Framework dependencies first. In fact, we require 3.0.5 as a minimum version.

We have also upgraded our base dependency on Spring Security (for those who are using the spring-integration-security module) to version 3.0.5.

Packaging Structure Changes

If you have direct dependencies on the core Spring Integration API (things like Message, MessageChannel, MessageBuilder, and so on), then you will need to update imports. Several of those classes and interfaces have been moved to new packages. For example, the 'Message' class has moved from 'org.springframework.integration.core' to 'org.springframework.integration', and the MessageBuilder is now in the 'org.springframework.integration.support' package. These changes were made to enforce consistency and to avoid cyclical package-level dependencies as the framework evolved from 1.0 to 2.0. For the most part, other than the package migration, the actual "public API" exposed by those classes and interfaces (constructors, methods, constants, etc.) should not have changed in any way that affects you directly (a few exceptions are listed immediately below). Therefore, the impact of these package structure changes should be manageable by simply updating imports through your IDE.

As well as this package change, MessageChannelTemplate was renamed to MessagingTemplate.

XML Transformers

Removed 'XmlPayload' from the names of 'XmlPayloadUnmarshallingTransformer' and 'XmlPayloadMarshallingTransformer' since the former can now return a Message instance and the latter now accepts a boolean to specify whether only the payload should be passed to the marshaller or the entire Message.

Removed Classes

The StringMessage class has been removed. We discovered that we were only using it within tests ourselves. We then decided there was no reason to have a specific type when either of the following are sufficient: new GenericMessage<String>("foo") or MessageBuilder.withPayload("foo").build();

The SimpleMessagingGateway class has been removed. The support that it provided is still available by extending MessagingGatewaySupport.

HeaderMappingMessageConverter was removed to provide greater flexibility when converting Jms Message to SI Message.
You can still provide MessageConverter to JmsTemplate directly as before, but you can also set 'header-mapper' attribute on the adapter injecting implementation of the org.springframework.integration.mapping.HeaderMapper strategy (default DefaultJmsHeaderMapper)
The Jms Message will be converted using Message Converter present in JmsTemplate and Jms Headers wil be converted using provided HeaderMapper. If the result of Jms Message conversion is SI Message than the headers converted via HeaderMapper will be merged with the headers already present in the Message. If the result of Jms Message conversion is NOT SI Message, than it becomes a payload of the new Message that is being constructed with headers buit via HeaderMapper

Router hierarchy was simplified resulting in removal of AbstractSingleChannelRouter. Now each Router is a subclass of AbstractMessageRouter

Removed and/or Renamed Methods

The MessageChannel no longer provides a getName() method directly. Instead, the base class for all of the core channel implementations (AbstractMessageChannel) now implements a NamedComponent interface, and that provides a getComponentName() method. This change was part of a general enhancement to add Message History tracking capabilities for channels as well as endpoints.

The QueueChannel's getMessageCount() method was renamed to getQueueSize(). We felt that the previous name was ambiguous now that we have added several new methods for monitoring channels (with statistics about the number of messages sent, number of failures, etc). The getQueueSize() method should return exactly the same results, but it is hopefully clearer to end users exactly what is being returned (the number of Messages currently in the Queue).

Deprecations

The 'spring-integration-httpinvoker' module is now deprecated, and we plan to remove it entirely for the 2.1 release. Now that the 'spring-integration-http' module builds upon Spring 3.0's underlying HTTP API, including such functionality as the HttpMessageConverter strategies, we believe that everything one could accomplish with the HttpInvoker-based adapter should now be achievable with the HTTP inbound gateways and/or channel-adapters.

Functional changes

Transformer

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 attribute is set to FALSE by default, but could be set to TRUE in order to have Exceptions thrown for null return values as with the transformer.
Also, unlike Spring Integration 1.0 the return value of the transformation method will be used as a payload of the new Message regardless of what was the type or the payload of the original Message. In other words Transformer should not be used as the way to enrich message headers. Header Enricher (e.g., <header-enricher>) should be used instead.

Configuration Changes

Pollers and Triggers

When configuring Pollers via XML, the various trigger sub-elements (e.g. ) have been deprecated and will be removed entirely in the 2.1 release. Now, those same values can be configured directly on attributes of the <poller> element itself. For example, you can provide 'fixed-delay' or 'cron' attributes, and you can even provide a reference to your own implementation of Spring 3.0's Trigger implementation with the 'trigger' attribute. In 2.0.0.RELEASE, there was no 'time-unit' attribute (as was available on the <interval-trigger> sub-element in 1.0). However, we have added support for a 'time-unit' attribute on the top-level <poller> element itself in 2.0.1. Keep in mind, that you can only use that attribute along with 'fixed-delay' or 'fixed-rate' (not with 'cron' or 'trigger').

Thread Pool Task Executors

Spring Integration 1.0 provided a <thread-pool-task-executor> element as a convenience, rather than requiring a <bean> element for defining simple ThreadPoolTaskExecutor instances. Now that Spring 3.0 provides a 'task' namespace with its own simple <executor> element and Spring Integration 2.0 depends on Spring 3.0, we have dropped the <thread-pool-task-executor>. Simply replace any occurrences with <task:executor> instead.

Inbound Channel Adapter for Files

The 'filename-pattern' attribute on the <inbound-channel-adapter> element within the 'file' namespace has changed from a Regular Expression to a simple pattern that may include '*' as a wildcard (e.g. filename-pattern="*.txt"). We made this change since it seems that a majority of users only needed that simple form of pattern matching, and the requirement to use a regex in such cases was a bit excessive. However, if you do need the full power of regular expressions, then you can provide the new 'filename-regex' attribute instead.