spring-integration/src/reference/docbook/changes-3.0-4.0.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="migration-3.0-4.0"
    xmlns:xlink="http://www.w3.org/1999/xlink">
    <title>Changes between 3.0 and 4.0</title>
	<para>
		Please be sure to also see the
		<ulink url="https://github.com/spring-projects/spring-integration/wiki/Spring-Integration-3.0-to-4.0-Migration-Guide"
				>Migration Guide</ulink> for important changes that might affect your applications.
		Migration guides for all versions back to <emphasis>2.1</emphasis> can be found on the
		<ulink url="https://github.com/spring-projects/spring-integration/wiki">Wiki</ulink>.
	</para>
	<section id="4.0-new-components">
		<title>New Components</title>
		<section id="4.0-mqtt">
			<title>MQTT Channel Adapters</title>
			<para>
				The MQTT channel adapters (previously available in the Spring Integration Extensions repository)
				are now available as part of the normal Spring Integration distribution.
				See <xref linkend="mqtt"/>
			</para>
		</section>
		<section id="4.0-enable-configuration">
			<title>@EnableIntegration</title>
			<para>
				The <code>@EnableIntegration</code> annotation has been added, to permit declaration of
				standard Spring Integration beans when using <code>@Configuration</code> classes.
				See <xref linkend="enable-integration"/> for more information.
			</para>
		</section>
		<section id="4.0-component-scan">
			<title>@IntegrationComponentScan</title>
			<para>
				The <code>@IntegrationComponentScan</code> annotation has been added, to permit classpath
				scanning for Spring Integration specific components.
				See <xref linkend="enable-integration"/> for more information.
			</para>
		</section>
		<section id="4.0-message-history">
			<title>@EnableMessageHistory</title>
			<para>
				Message history can now be enabled with the <code>@EnableMessageHistory</code> annotation in a
				<code>@Configuration</code> class; in addition the message history settings can be modified
				by a JMX MBean. In addition auto-created <interfacename>MessageHandler</interfacename>s for
				annotated endpoints (e.g. <classname>@ServiceActivator</classname>, <classname>@Splitter</classname> etc.)
				now are also trackable by <code>MessageHistory</code>. For more information, see <xref linkend="message-history"/>.
			</para>
		</section>
		<section id="4.0-messaging-gateway">
			<title>@MessagingGateway</title>
			<para>
				Messaging gateway interfaces can now be configured with the <code>@MessagingGateway</code> annotation.
				It is an analogue of the <code>&lt;int:gateway/&gt;</code> xml element.
				For more information, see <xref linkend="messaging-gateway-annotation"/>.
			</para>
		</section>
		<section id="4.0-boot">
			<title>Spring Boot @EnableAutoConfiguration</title>
			<para>
				As well as the <code>@EnableIntegration</code> annotation mentioned above, a
				a hook has been introduced to allow the
				Spring Integration infrastructure beans to be configured using Spring Boot's
				<code>@EnableAutoConfiguration</code>.
				For more information see
				<ulink url="http://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-auto-configuration.html"
						>Spring Boot - AutoConfigure</ulink>.
			</para>
		</section>
		<section id="4.0-global-channel-interceptor">
			<title>@GlobalChannelInterceptor</title>
			<para>
				As well as the <code>@EnableIntegration</code> annotation mentioned above,
				the <code>@GlobalChannelInterceptor</code> annotation has bean introduced.
				For more information, see <xref linkend="enable-integration"/>.
			</para>
		</section>
		<section id="4.0-integration-converter">
			<title>@IntegrationConverter</title>
			<para>
				The <code>@IntegrationConverter</code> annotation has bean introduced,
				as an analogue of <code>&lt;int:converter/&gt;</code> component.
				For more information, see <xref linkend="enable-integration"/>.
			</para>
		</section>
		<section id="4.0-enable-publisher">
			<title>@EnablePublisher</title>
			<para>
				The <code>@EnablePublisher</code> annotation has been added, to allow the specification of a
				<code>default-publisher-channel</code> for <classname>@Publisher</classname> annotations.
				See <xref linkend="enable-integration"/> for more information.
			</para>
		</section>
		<section id="4.0-redis-cms">
			<title>Redis Channel Message Stores</title>
			<para>
				A new Redis <interfacename>MessageGroupStore</interfacename>, that is optimized for
				use when backing a <classname>QueueChannel</classname> for persistence, is now
				provided.
				For more information, see <xref linkend="redis-cms"/>.
			</para>
			<para>
				A new Redis <interfacename>ChannelPriorityMessageStore</interfacename> is now
				provided. This can be used to retrieve messages by priority.
				For more information, see <xref linkend="redis-cms"/>.
			</para>
		</section>
		<section id="4.0-priority-channel-mondodb">
			<title>MongodDB Channel Message Store</title>
			<para>
				MongoDB support now provides the <classname>MongoDbChannelMessageStore</classname> -
				a <emphasis>channel</emphasis> specific <interfacename>MessageStore</interfacename> implementation.
				With <code>priorityEnabled = true</code>, it can be used in
				<code>&lt;int:priority-queue&gt;</code>s to achieve <emphasis>priority</emphasis> order polling of
				persisted messages. For more information see <xref linkend="mongodb-priority-channel-message-store"/>.
			</para>
		</section>
		<section id="4.0-MBeanExport-annotation">
			<title>@EnableIntegrationMBeanExport</title>
			<para>
				The <classname>IntegrationMBeanExporter</classname> can now be enabled with the <code>@EnableIntegrationMBeanExport</code>
				annotation in a <code>@Configuration</code> class. For more information, see <xref linkend="jmx-mbean-exporter"/>.
			</para>
		</section>
		<section id="4.0-channel-security-interceptor">
			<title>ChannelSecurityInterceptorFactoryBean</title>
			<para>
				Configuration of Spring Security for message channels using <code>@Configuration</code> classes is
				now supported by using a <classname>ChannelSecurityInterceptorFactoryBean</classname>.
				For more information, see <xref linkend="security"/>.
			</para>
		</section>
		<section id="4.0-redis-outbound-gateway">
			<title>Redis Command Gateway</title>
			<para>
				The Redis support now provides the <code>&lt;outbound-gateway&gt;</code> component
				to perform generic Redis commands using the <code>RedisConnection#execute</code> method.
				For more information, see <xref linkend="redis-outbound-gateway"/>.
			</para>
		</section>
		<section id="4.0-redis-gemfire-lock-registry">
			<title>RedisLockRegistry and GemfireLockRegistry</title>
			<para>
				The <classname>RedisLockRegistry</classname> and <classname>GemfireLockRegistry</classname> are now
				available supporting global locks visible to multiple application instances/servers.
				These can be used with aggregating message handlers across multiple application instances such
				that group release will occur on only one instance.
				For more information, see <xref linkend="redis-lock-registry"/>, <xref linkend="gemfire-lock-registry"/>
				and <xref linkend="aggregator"/>.
			</para>
		</section>
		<section id="4.0-poller-annotation">
			<title>@Poller</title>
			<para>
				Annotation-based messaging configuration can now have a <code>poller</code> attribute.
				This means that methods annotated with (<interfacename>@ServiceActivator</interfacename>,
				<interfacename>@Aggregator</interfacename> etc.) can now use an <code>inputChannel</code> that
				is a reference to a <interfacename>PollableChannel</interfacename>.
				For more information, see <xref linkend="annotations"/>.
			</para>
		</section>
		<section id="4.0-inbound-channel-adapter-annotation">
			<title>@InboundChannelAdapter and SmartLifecycle for Annotated Endpoints</title>
			<para>
				The <interfacename>@InboundChannelAdapter</interfacename> method annotation is now available.
				It is an analogue of the <code>&lt;int:inbound-channel-adapter&gt;</code> XML component.
				In addition, all Messaging Annotations now provide <interfacename>SmartLifecycle</interfacename> options.
				For more information, see <xref linkend="annotations"/>.
			</para>
		</section>
		<section id="4.0-twitter-sog">
			<title>Twitter Search Outbound Gateway</title>
			<para>
				A new twitter endpoint <classname>&lt;int-twitter-search-outbound-gateway/&gt;</classname>
				has been added. Unlike the search inbound adapter which polls using the same search
				query each time, the outbound gateway allows on-demand customized queries.
				For more information, see <xref linkend="twitter-sog"/>.
			</para>
		</section>
		<section id="4.0-gemfire-metadata">
			<title>Gemfire Metadata Store</title>
			<para>
				The <classname>GemfireMetadataStore</classname> is provided, allowing it to be used, for example,
				in a <classname>AbstractPersistentAcceptOnceFileListFilter</classname>
				implementation in a multiple application instance/server environment.
				For more information, see <xref linkend="metadata-store"/>,
				<xref linkend="file-reading"/>, <xref linkend="ftp-inbound"/> and
				<xref linkend="sftp-inbound"/>.
			</para>
		</section>
		<section id="4.0-bridge-annotations">
			<title>@BridgeFrom and @BridgeTo Annotations</title>
			<para>
				Annotation and Java configuration has introduced <classname>@BridgeFrom</classname> and
				<classname>@BridgeTo</classname> <classname>@Bean</classname> method annotations to mark
				<interfacename>MessageChannel</interfacename> beans in
				<interfacename>@Configuration</interfacename> classes.
				For more information, see <xref linkend="annotations"/>.
			</para>
		</section>
		<section id="4.0-meta-messaging-annotations">
			<title>Meta Messaging Annotations</title>
			<para>
				Messaging Annotations (<classname>@ServiceActivator</classname>, <classname>@Router</classname>,
				<classname>@MessagingGateway</classname> etc.) can now be configured as meta-annotations for user-defined
				Messaging Annotations. In addition the user-defined annotations can have the same attributes
				(<code>inputChannel</code>, <code>@Poller</code>, <code>autoStartup</code> etc.).
				For more information, see <xref linkend="annotations"/>.
			</para>
		</section>
	</section>

	<section id="4.0-general">
		<title>General Changes</title>
		<section>
			<title>Requires Spring Framework 4.0</title>
			<para>
				Core messaging abstractions (<interfacename>Message</interfacename>,
				<interfacename>MessageChannel</interfacename> etc) have moved to the Spring
				Framework <code>spring-messaging</code> module. Users who reference these
				classes directly in their code will need to make changes as described in
				the first section of the
				<ulink url="https://github.com/spring-projects/spring-integration/wiki/Spring-Integration-3.0-to-4.0-Migration-Guide"
						>Migration Guide</ulink>.
			</para>
		</section>
		<section id="4.0-xpath-header-enricher-header-type">
			<title>Header Type for XPath Header Enricher</title>
			<para>
				The <code>header-type</code> attribute has been introduced for the <code>header</code> sub-element of the
				<code>&lt;int-xml:xpath-header-enricher&gt;</code>. This attribute provides the target type for
				the header value to which the result of the XPath expression evaluation will be converted.
				For more information see <xref linkend="xml-xpath-header-enricher"/>.
			</para>
		</section>
		<section id="4.0-object-to-json-transformer-result-type">
			<title>Object To Json Transformer: Node Result</title>
			<para>
				The <code>result-type</code> attribute has been introduced for the  <code>&lt;int:object-to-json-transformer&gt;</code>.
				This attribute provides the target type for the result of object mapping to JSON.
				It supports <code>STRING</code> (default) and <code>NODE</code>.
				For more information see <xref linkend="transformer-xpath-spel-function"/>.
			</para>
		</section>
		<section id="4.0-jms-header-mapping">
			<title>JMS Header Mapping</title>
			<para>
				The <classname>DefaultJmsHeaderMapper</classname> now maps an incoming <code>JMSPriority</code> header to
				the Spring Integration <code>priority</code> header. Previously <code>priority</code> was only
				considered for outbound messages. For more information see <xref linkend="jms-header-mapping"/>.
			</para>
		</section>
		<section id="4.0-jms-ob">
			<title>JMS Outbound Channel Adapter</title>
			<para>
				The JMS outbound channel adapter now supports the <code>session-transacted</code> attribute
				(default false). Previously, you had to inject a customized <classname>JmsTemplate</classname>
				to use transactions. See <xref linkend="jms-outbound-channel-adapter"/>.
			</para>
		</section>
		<section id="4.0-jms-ib">
			<title>JMS Inbound Channel Adapter</title>
			<para>
				The JMS inbound channel adapter now supports the <code>session-transacted</code> attribute
				(default false). Previously, you had to inject a customized <classname>JmsTemplate</classname>
				to use transactions (the adapter allowed 'transacted' in the acknowledgeMode which was
				incorrect, and didn't work; this value is no longer allowed). See
				<xref linkend="jms-inbound-channel-adapter"/>.
			</para>
		</section>
		<section id="4.0-datatype-channel">
			<title>Datatype Channels</title>
			<para>
				You can now specify a <interfacename>MessageConverter</interfacename> to be used when converting
				(if necessary) payloads to one of the accepted <code>datatype</code>s in a Datatype channel.
				For more information see <xref linkend="channel-datatype-channel"/>.
			</para>
		</section>
		<section id="4.0-retry-config">
			<title>Simpler Retry Advice Configuration</title>
			<para>
				Simplified namespace support has been added to configure a
				<classname>RequestHandlerRetryAdvice</classname>.
				For more information see <xref linkend="retry-config"/>.
			</para>
		</section>
		<section id="4.0-release-strategy-group-timeout">
			<title>Correlation Endpoint: Time-based Release Strategy</title>
			<para>
				The mutually exclusive <code>group-timeout</code> and <code>group-timeout-expression</code>
				attributes have been added to the <code>&lt;int:aggregator&gt;</code> and <code>&lt;int:resequencer&gt;</code>.
				These attributes allow forced completion of a partial <code>MessageGroup</code>,
				if the <interfacename>ReleaseStrategy</interfacename> does not release a group and no
				further messages arrive within the time specified.
				For more information see <xref linkend="aggregator-config"/>.
			</para>
		</section>
		<section id="4.0-redis-metadata">
			<title>Redis Metadata Store</title>
			<para>
				The <classname>RedisMetadataStore</classname> now implements <interfacename
					>ConcurrentMetadataStore</interfacename>, allowing it to be used, for example,
				in a <classname>AbstractPersistentAcceptOnceFileListFilter</classname>
				implementation in a multiple application instance/server environment.
				For more information, see <xref linkend="redis-metadata-store"/>,
				<xref linkend="file-reading"/>, <xref linkend="ftp-inbound"/> and
				<xref linkend="sftp-inbound"/>.
			</para>
		</section>
		<section id="4.0-jdbc-cs">
			<title>JdbcChannelMessageStore and PriorityChannel</title>
			<para>
				The <classname>JdbcChannelMessageStore</classname> now implements
				<interfacename>PriorityCapableChannelMessageStore</interfacename>, allowing it to be used as
				a <code>message-store</code> reference for <code>priority-queue</code>s.
				For more information, see <xref linkend="jdbc-message-store-channels"/>.
			</para>
		</section>
		<section id="4.0-amqp">
			<title>AMQP Endpoints Delivery Mode</title>
			<para>
				Spring AMQP, by default, creates persistent messages on the broker. This behavior can be
				overridden by setting the <code>amqp_deliveryMode</code> header and/or customizing the
				mappers. A convenient <code>default-delivery-mode</code> attribute has now been added
				to the adapters to provide easier configuration of this important setting.
				For more information, see <xref linkend="amqp-outbound-channel-adapter"/> and
				<xref linkend="amqp-outbound-gateway"/>.
			</para>
		</section>
		<section id="4.0-ftp">
			<title>FTP Timeouts</title>
			<para>
				The <classname>DefaultFtpSessionFactory</classname> now exposes the
				<code>connectTimeout</code>, <code>defaultTimeout</code> and <code>dataTimeout</code>
				properties, avoiding the need to subclass the factory just to set these common
				properties. The <code>postProcess*</code> methods are still available for more
				advanced configuration. See <xref linkend="ftp-session-factory"/> for more information.
			</para>
		</section>
		<section id="4.0-twitter-status-updating">
			<title>Twitter: StatusUpdatingMessageHandler</title>
			<para>
				The <classname>StatusUpdatingMessageHandler</classname> (<code>&lt;int-twitter:outbound-channel-adapter&gt;</code>)
				now supports the <code>tweet-data-expression</code> attribute to build a
				<classname>org.springframework.social.twitter.api.TweetData</classname> object for updating the
				timeline status allowing, for example, attaching an image.
				See <xref linkend="outbound-twitter-update"/> for more information.
			</para>
		</section>
		<section id="4.0-jpa-id-expression">
			<title>JPA Retrieving Gateway: id-expression</title>
			<para>
				The <code>id-expression</code> attribute has been introduced for
				<code>&lt;int-jpa:retrieving-outbound-gateway&gt;</code> to perform
				<code>EntityManager.find(Class entityClass, Object primaryKey)</code>.
				See <xref linkend="jpa-retrieving-outbound-gateway"/> for more information.
			</para>
		</section>
		<section id="4.0-tcp-deserializer-events">
			<title>TCP Deserialization Events</title>
			<para>
				When one of the standard deserializers encounters a problem decoding the input stream to
				a message, it will now emit a <classname>TcpDeserializationExceptionEvent</classname>, allowing
				applications to examine the data at the point the exception occurred.
				See <xref linkend="tcp-events"/> for more information.
			</para>
		</section>
		<section id="4.0-bean-messaging-annotations">
			<title>Messaging Annotations on @Bean Definitions</title>
			<para>
				Messaging Annotations (<classname>@ServiceActivator</classname>, <classname>@Router</classname>,
				<classname>@InboundChannelAdapter</classname> etc.) can now be configured on <classname>@Bean</classname>
				definitions in <interfacename>@Configuration</interfacename> classes.
				For more information, see <xref linkend="annotations"/>.
			</para>
		</section>
	</section>
</section>