Spring/spring-integration
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

removed spring build artifacts and externals

Browse Source
This commit is contained in:
Chris Beams
2010-05-25 12:12:41 +00:00
parent 41e55caf36
commit b97b2fb090
72 changed files with 0 additions and 9171 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
build-spring-integration/build.xml
View File

@@ -1,37 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="build-spring-integration" default="precommit">
<path id="bundles">
<pathelement location="${basedir}/../spring-integration-parent"/>
<pathelement location="${basedir}/../org.springframework.integration"/>
<pathelement location="${basedir}/../org.springframework.integration.security"/>
<pathelement location="${basedir}/../org.springframework.integration.xml"/>
<pathelement location="${basedir}/../org.springframework.integration.event"/>
<pathelement location="${basedir}/../org.springframework.integration.file"/>
<pathelement location="${basedir}/../org.springframework.integration.http"/>
<pathelement location="${basedir}/../org.springframework.integration.httpinvoker"/>
<pathelement location="${basedir}/../org.springframework.integration.ip"/>
<pathelement location="${basedir}/../org.springframework.integration.jdbc"/>
<pathelement location="${basedir}/../org.springframework.integration.jms"/>
<pathelement location="${basedir}/../org.springframework.integration.jmx"/>
<pathelement location="${basedir}/../org.springframework.integration.mail"/>
<pathelement location="${basedir}/../org.springframework.integration.rmi"/>
<pathelement location="${basedir}/../org.springframework.integration.stream"/>
<pathelement location="${basedir}/../org.springframework.integration.ws"/>
<pathelement location="${basedir}/../org.springframework.integration.test"/>
</path>
<property file="${basedir}/../build.properties"/>
<import file="${basedir}/package-top-level.xml"/>
<import file="${basedir}/publish-top-level.xml"/>
<import file="${basedir}/../spring-build/multi-bundle/default.xml"/>
<target name="precommit" depends="clean,clean-integration,test"/>
<target name="clean" depends="common-multi-bundle.clean">
<delete verbose="true" includeemptydirs="true">
<fileset dir="${basedir}/../spring-integration-samples" includes="*/target/**" defaultexcludes="false"/>
</delete>
</target>
</project>

12
build-spring-integration/generate-pom.xml
View File

@@ -1,12 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="org.springframework.core" xmlns:ivy="antlib:org.apache.ivy.ant">
<target name="generate-pom" depends="ivy.init">
<ivy:makepom ivyfile="ivy.xml" pomfile="pom-generated-from-ivy.xml">
<mapping conf="compile" scope="compile"/>
<mapping conf="test" scope="test"/>
<mapping conf="provided" scope="provided"/>
</ivy:makepom>
</target>
</project>

36
build-spring-integration/package-bundle.xml
View File

@@ -1,36 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="package-bundle">
<import file="publish-maven.xml"/>
<target name="package" depends="ivy.init">
<dist-jar/>
<src-jar/>
<ext-jars/>
<delete>
<fileset dir="${package.lib.dir}">
<present targetdir="${package.dist.dir}"/>
</fileset>
<fileset dir="${package.lib.dir}" includes="*.jackson.*"/>
</delete>
<mkdir dir="${package.output.dir}/samples" />
<copy todir="${package.output.dir}/samples">
<fileset dir="${basedir}/../spring-integration-samples">
<include name="cafe/**" />
<include name="errorhandling/**"/>
<include name="filecopy/**"/>
<include name="helloworld/**"/>
<include name="jms/**"/>
<include name="loan-broker/**"/>
<include name="oddeven/**"/>
<include name="quote/**"/>
<include name="ws/**"/>
<include name="ws-inbound-gateway/**"/>
<include name="xml/**"/>
<include name="pom.xml"/>
<include name="README.txt"/>
</fileset>
</copy>
</target>
</project>

38
build-spring-integration/package-top-level.xml
View File

@@ -1,38 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="package-top-level">
<target name="package">
<delete dir="${package.output.dir}" quiet="true"/>
<mkdir dir="${package.output.dir}"/>
<delete file="${package.output.file}" quiet="true"/>
<mkdir dir="${artifacts.dir}"/>
<all-bundles target="package">
<property name="package.output.dir" value="${package.output.dir}"/>
</all-bundles>
<ant target="javadoc-api" inheritAll="false">
<property name="target.dir" value="${package.docs.dir}"/>
</ant>
<path id="doc.projects">
<path location="${basedir}/../spring-integration-reference"/>
</path>
<all-bundles target="doc" buildpathRef="doc.projects"/>
<all-bundles target="package" buildpathRef="doc.projects">
<property name="package.output.dir" value="${package.output.dir}"/>
</all-bundles>
<copy todir="${package.output.dir}">
<fileset dir="${basedir}/resources"/>
</copy>
<zip destfile="${package.output.file}">
<zipfileset dir="${package.dir}" includes="${package.basename}/samples/**" filemode="755"/>
<zipfileset dir="${package.dir}" excludes="${package.basename}/samples/**"/>
</zip>
</target>
</project>

128
build-spring-integration/pom.xml
View File

@@ -1,128 +0,0 @@
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.springframework.integration</groupId>
<artifactId>spring-integration</artifactId>
<name>Spring Integration</name>
<description>Spring Integration is a new addition to the Spring portfolio. It provides an
extension of the Spring programming model to support the well-known Enterprise Integration
Patterns while building on the Spring Framework's existing support for enterprise integration.
It enables simple messaging within Spring-based applications and integrates with external
systems via simple adapters. Those adapters provide a higher-level of abstraction over Spring's
support for remoting, messaging, and scheduling. Spring Integration's primary goal is to provide
a simple model for building enterprise integration solutions while maintaining the separation of
concerns that is essential for producing maintainable, testable code.
</description>
<version>2.0.0.BUILD-SNAPSHOT</version>
<packaging>pom</packaging>
<modules>
<module>../spring-integration-parent</module>
<module>../org.springframework.integration</module>
<module>../org.springframework.integration.security</module>
<module>../org.springframework.integration.event</module>
<module>../org.springframework.integration.file</module>
<module>../org.springframework.integration.http</module>
<module>../org.springframework.integration.httpinvoker</module>
<module>../org.springframework.integration.jdbc</module>
<module>../org.springframework.integration.jms</module>
<module>../org.springframework.integration.mail</module>
<module>../org.springframework.integration.rmi</module>
<module>../org.springframework.integration.stream</module>
<module>../org.springframework.integration.ip</module>
<module>../org.springframework.integration.ws</module>
<module>../org.springframework.integration.xml</module>
</modules>
<url>http://www.springsource.org/spring-integration</url>
<organization>
<name>SpringSource</name>
<url>http://www.springsource.com</url>
</organization>
<scm>
<url>https://fisheye.springsource.org/browse/spring-integration</url>
<connection>scm:svn:https://src.springsource.org/svn/spring-integration</connection>
<developerConnection>scm:svn:https://src.springsource.org/svn/spring-integration/trunk</developerConnection>
</scm>
<issueManagement>
<system>JIRA</system>
<url>http://jira.springframework.org/browse/INT</url>
</issueManagement>
<mailingLists>
<mailingList>
<name> Spring Integration Forum
</name>
<post>http://forum.springsource.org/forumdisplay.php?f=42</post>
<archive>http://forum.springsource.org/forumdisplay.php?f=42</archive>
</mailingList>
</mailingLists>
<ciManagement>
<system>Bamboo</system>
<url>https://build.springsource.org/browse/INT</url>
</ciManagement>
<licenses>
<license>
<name> Apache 2.0
</name>
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
</license>
</licenses>
<profiles>
<profile>
<id>staging</id>
<distributionManagement>
<site>
<id>staging</id>
<url>file:///${user.dir}/target/staging</url>
</site>
<repository>
<id>staging</id>
<url>file:///${user.dir}/target/staging</url>
</repository>
<snapshotRepository>
<id>staging</id>
<url>file:///${user.dir}/target/staging</url>
</snapshotRepository>
</distributionManagement>
</profile>
<profile>
<id>release</id>
<build>
<plugins>
<plugin>
<artifactId>maven-source-plugin</artifactId>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
<pluginRepositories>
<pluginRepository>
<id>com.springsource.repository.bundles.milestone</id>
<name>SpringSource Enterprise Bundle Repository - SpringSource Bundle Milestones</name>
<url>http://repository.springsource.com/maven/bundles/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>com.springsource.repository.bundles.snapshot</id>
<name>SpringSource Enterprise Bundle Repository - SpringSource Bundle Snapshots</name>
<url>http://repository.springsource.com/maven/bundles/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>agilejava</id>
<url>http://agilejava.com/maven</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
</project>

73
build-spring-integration/publish-maven.xml
View File

@@ -1,73 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="publish-maven-central-only-pom" xmlns:maven="antlib:org.apache.maven.artifact.ant">
<description> This build file publishes to a maven repository and two ways. 1. Publish jar,
source-jar, and pom artifacts. 2. Publish only the pom artifact. The additional complexity
in the implementation is due to a bug in the maven ant tasks version 2.0.8 that prevents
deploying to a local file repository on windows. </description>
<condition property="is.windows" value="windows">
<os family="windows"/>
</condition>
<!-- top level targets -->
<target name="publish-maven-central-only-pom-artifacts"
depends="publish-only-pom-windows,publish-only-pom-unix"> </target>
<target name="publish-maven-central-code-artifacts"
depends="publish-code-windows,publish-code-unix"> </target>
<target name="install-pom" depends="maven.init">
<maven:install>
<pom file="${local.pom.output.file}"/>
</maven:install>
</target>
<!-- Supporting targets -->
<!-- POM only deployment -->
<target name="publish-only-pom-windows" depends="maven.init" if="is.windows">
<maven:deploy>
<!-- Due to http://jira.codehaus.org/browse/MANTTASKS-103 in 2.0.8 on windows, fixed in 2.0.9 -->
<!-- Assuming using local file, value of variable should be of the form L:\temp\maven-repo-test -->
<remoteRepository id="localDisk" url="file:${maven.central.repository}"/>
<pom file="${local.pom.output.file}"/>
</maven:deploy>
</target>
<target name="publish-only-pom-unix" depends="maven.init" unless="is.windows">
<maven:deploy>
<remoteRepository url="${maven.central.repository}"/>
<pom file="${local.pom.output.file}"/>
</maven:deploy>
</target>
<!-- jar, source-jar and POM deployment -->
<target name="publish-code-windows" depends="maven.init">
<maven:deploy file="${jar.output.file}">
<!-- Due to http://jira.codehaus.org/browse/MANTTASKS-103 in 2.0.8 on windows, fixed in 2.0.9 -->
<!-- Assuming using local file, value of variable should be of the form L:\temp\maven-repo-test -->
<remoteRepository id="localDisk" url="file:${maven.central.repository}"/>
<pom file="${local.pom.output.file}"/>
<attach file="${source-jar.output.file}" classifier="sources"/>
</maven:deploy>
</target>
<target name="publish-code-unix" depends="maven.init" unless="is.windows">
<maven:deploy file="${jar.output.file}">
<remoteRepository url="${maven.central.repository}"/>
<pom file="${local.pom.output.file}"/>
<attach file="${source-jar.output.file}" classifier="sources"/>
</maven:deploy>
</target>
</project>

6
build-spring-integration/publish-top-level.xml
View File

@@ -1,6 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="publish-top-level">
<target name="publish" depends="publish-package, publish-multi-bundle.publish"/>
</project>

42
build-spring-integration/publish.xml
View File

@@ -1,42 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="publish-spring-framework" xmlns:maven="antlib:org.apache.maven.artifact.ant">
<property file="${basedir}/../build.properties"/>
<import file="${basedir}/../spring-build/multi-bundle/default.xml"/>
<path id="modules-with-code-artifacts">
<pathelement location="${basedir}/../org.springframework.integration"/>
<pathelement location="${basedir}/../org.springframework.integration.security"/>
<pathelement location="${basedir}/../org.springframework.integration.xml"/>
<pathelement location="${basedir}/../org.springframework.integration.event"/>
<pathelement location="${basedir}/../org.springframework.integration.file"/>
<pathelement location="${basedir}/../org.springframework.integration.http"/>
<pathelement location="${basedir}/../org.springframework.integration.httpinvoker"/>
<pathelement location="${basedir}/../org.springframework.integration.jdbc"/>
<pathelement location="${basedir}/../org.springframework.integration.jms"/>
<pathelement location="${basedir}/../org.springframework.integration.mail"/>
<pathelement location="${basedir}/../org.springframework.integration.rmi"/>
<pathelement location="${basedir}/../org.springframework.integration.stream"/>
<pathelement location="${basedir}/../org.springframework.integration.ip"/>
<pathelement location="${basedir}/../org.springframework.integration.ws"/>
<pathelement location="${basedir}/../org.springframework.integration.osgi"/>
</path>
<path id="modules-with-only-pom-artifacts">
<pathelement location="../spring-integration-parent"/>
</path>
<target name="publish-maven-central-spring" depends="publish-maven-central-only-pom-spring">
<all-bundles target="publish-maven-central-code-artifacts" buildpathRef="modules-with-code-artifacts"/>
</target>
<target name="publish-maven-central-only-pom-spring">
<all-bundles target="publish-maven-central-only-pom-artifacts"
buildpathRef="modules-with-only-pom-artifacts"/>
</target>
</project>

408
build-spring-integration/resources/changelog.txt
View File

@@ -1,408 +0,0 @@
SPRING INTEGRATION CHANGELOG
============================
For the full detailed changelog, see:
https://fisheye.springsource.org/changelog/spring-integration
Changes in version 2.0.0 Milestone 4 (May 8, 2010)
http://jira.springsource.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=11389
Changes in version 2.0.0 Milestone 3 (Mar 12, 2010)
http://jira.springsource.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=11307
Changes in version 2.0.0 Milestone 2 (Dec 24, 2009)
---------------------------------------------------
http://jira.springsource.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=11306
Changes in version 2.0.0 Milestone 1 (Oct 12, 2009)
---------------------------------------------------
http://jira.springframework.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=11178
Changes in version 1.0.3 (Jul 18, 2009)
---------------------------------------
http://jira.springframework.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=11209
Changes in version 1.0.2 (Mar 31, 2009)
---------------------------------------
http://jira.springframework.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=11153
Changes in version 1.0.1 (Dec 17, 2008)
---------------------------------------
For changes in this release, see:
http://jira.springframework.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=11146
Changes in version 1.0.0 (Nov 26, 2008)
---------------------------------------
For changes in this release, see:
http://jira.springframework.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=10791
Changes in version 1.0.0.RC2 (Nov 14, 2008)
-------------------------------------------
For changes in this release, see:
http://jira.springframework.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=11102
Changes in version 1.0.0.RC1 (Nov 03, 2008)
-------------------------------------------
For changes in this release, see:
http://jira.springframework.org/secure/IssueNavigator.jspa?reset=true&pid=10121&fixfor=11101
*** GENERAL ***
Upgraded Spring Framework dependency to 2.5.6
Upgraded Spring Security dependency to 2.0.4
Broke 'adapter' module into individual JARs
Added JMS samples
*** CORE API ***
Added Message Filter
Added error handling strategy so that ErrorMessage can be routed to an error channel
Added support for a 'defaultChannel' property on MessageChannelTemplate
Added @Gateway annotation for per-method configuration of request and/or reply channels
Simplified GatewayProxyFactoryBean reply Message correlation
GatewayProxyFactoryBean now supports non-pollable replyChannel
DefaultMethodResolver now correctly resolves annotated method on Proxy
Fixed CronTrigger end of month rollover issue
Added <interval-trigger/> and <cron-trigger/> elements for pollers
Added transaction support for annotation-based polling
AbstractPollingEndpoint now supports an Advice chain
Fixed endless loop issue in Router (INT-358)
MethodInvokingRouter now accepts a target object only (no method name required)
MethodInvokingRouter will check for @Router method-level annotation
Added 'default-output-channel' attribute to the <router/> element
The 'splitter' element does not require a "ref" (for a DefaultSplitter instance)
The 'resequencer' element accepts an "input-channel" attribute
AbstractMessageBarrierHandler no longer calls processMessages twice
The <pool-executor/> element was renamed to <thread-pool-task-executor/>
Default TaskExecutor created for MessageBus sets max-size for pool instead of core
Endpoints registered after ApplicationContext refresh are still activated
MessageBus started/stopped events are fired
Removed the MessageBusInterceptor
Stopping/destroying context/MessageBus properly stops all Threads
MessageHeaders no longer supports clear
MessageHeaders constructor copies the original map for immutability
*** ADAPTERS ***
Added JMS header enricher
Added JmsOutboundGateway and refactored JmsGateway to JmsInboundGateway
JMS gateways recognize a payload that is already a Spring Integration Message
Added namespace support for JmsOutboundGateway
MessageHeader values are propagated when using JMS gateways
Enabled configuration of MessageConverter for JmsOutboundGateway
FileToStringTransformer is encoding-aware
Added inbound Mail Channel Adapters (POP3, IMAP, and IMAP IDLE)
Mail outbound-channel-adapter accepts the "channel" attribute
Added mail header enricher namespace support
Enabled configuration of a WebServiceMessageSender instance for WS outbound gateways
WebService gateway supports a Document payload in addition to Source and String
RMI and HttpInvoker outbound gateways remove but copy non-serializable Message headers
*** OTHER ***
Channel security provides a ChannelInvocation instance
Channel security interceptor now extends AbstractSecurityInterceptor
XML Document Builders are now Namespace-aware
Added XPath Message Selector
Added XPath Message Splitter
Changes in version 1.0.0.M6 (Aug 20, 2008)
------------------------------------------
*** CORE API ***
Refactored Message object to be unmodifiable after initial creation
Refactored MessageHeaders object to be an implementation of (unmodifiable) Map<String, Object>
Added MessageBuilder for constructing Messages (now used within internal handlers and endpoints)
Added Quartz-based MessagingTaskScheduler to support Cron-based polling
Reimplemented base Scheduling infrastructure to provide an SPI
MessageBus no longer provides an option for auto-creating channels
Added HeaderTransformer strategy interface
MethodArgumentMessageMapper (f.k.a AnnotationMethodMessageMapper) is used across handler types
PublishSubscribeChannels now provide an 'applySequence' property for adding sequence number/size headers
SimpleDispatcher no longer attempts retries and does not mask exceptions with rejection limit error
Default 'maxMessagesPerPoll' value is now unbounded
Aggregator gives precedence to outputChannel and falls back to the returnAddress (consistent with other handlers)
Added support for arguments, return-value, and thrown exception payload types for MessagePublishingInterceptor
AbstractMessageDispatcher uses a Set (to avoid duplicate subscriptions) instead of a List
AbstractMessageBarrierHandler uses returnAddress if outputChannel is null
PublisherAnnotationPostProcessor proxies classes if the annotated method is not declared on an interface method
Method reference is used for @Subscriber annotation (avoids NoSuchMethodException for method name ambiguity)
MethodInvokingSource and MethodInvokingTarget now accept the actual Method reference instead of method name
ChannelFactory behavior is now consistent with channels that are defined explicitly (no longer creates proxies)
MessageHandlerDecorator (f.k.a. InterceptingMessageHandler) now supports setter injection
InboundChannelAdapter (replacement for SourceEndpoint) calls MessageDeliveryAware onSend/onFailure methods
*** ADAPTERS ***
Added an FTP Target adapter
FileEntryParser can be customized for the FtpSource
Added PollingMailSource adapter to support (polled) inbound e-mail messages
Added SubscribableMailSource adapter to support (event-driven) inbound e-mail messages
JMS header-mapping MessageConverter is no longer nested twice when used for source and target
JMS message headers are now propagated (JMS-specific and user-prefixed values)
AbstractMailHeaderMapper correctly maps the FROM/REPLY_TO attributes
*** CONFIGURATION ***
Channel Adapter now creates a DirectChannel implicitly if no "channel" is configured
Added namespace support for WireTap
The "max-messages-per-poll" value can be configured on <poller/> elements
The <poller/> element now accepts a "cron" attribute (as an alternative to "period") if Quartz support is available
The <poller/> element now provides "initial-delay" and "fixed-rate" attributes
Added support for hybrid XML and annotations configuration (method-level annotations with XML-based endpoint)
Added namespace support for configuring the MessageBus' TaskScheduler
The "error-handler" attribute is available for XML-based Message Endpoint configuration
The "errorChannel" bean is detected within the Application Context rather than being configured on the MessageBus
The "channelFactory" bean is detected within the Application Context rather than being configured on the MessageBus
Exposed configuration of concurrent-consumers for the JmsGateway
The @HeaderProperty and @HeaderAttribute annotations have been replaced with @Header
Splitter endpoint's 'output-channel' is now configured correctly when using annotations
*** WEB SERVICES AND XML ***
Added XPathRouter
DOMResultFactory now creates a DOMResult with a node for OXM Marshaller
*** GENERAL ***
Upgraded to Spring 2.5.5.A
Upgraded to Spring Security 2.0.2.A
Upgraded to Spring WS 1.5.4.A
Changes in version 1.0.0.M5 (Jul 08, 2008)
------------------------------------------
*** CORE API ***
SimpleMessagingTaskScheduler now has a configurable shutdown (for 'shutdown' vs 'shutdownNow')
QueueChannel uses TRACE logging for preReceive and only uses DEBUG in postReceive if the Message is not null
Added <concurrency-interceptor> for endpoints
Added <transaction-interceptor> for endpoints
The MessageBus tries to register new channels before starting (on ContextRefreshedEvent)
Aggregator now uses its endpoint's output-channel
Added MessageTransformer and @Transformer support
Added a MessageTransformingChannelInterceptor
MessageBus is now an interface
MessageHeader is now an interface
Added ChannelFactory
Added PublishSubscribeChannel and <publish-subscribe-channel/>
Channels specified in source-endpoint (now channel-adapter) are now auto-created
Added EndpointTrigger for invoking endpoints with a poll command
Removed the DispatcherPolicy from channel configuration
Added BroadcastingDispatcher
*** ADAPTERS ***
Added regular expression pattern FilenameFilter implementation
The <file-source/> now accepts one of "file-filter", "filename-filter", or "filename-pattern"
FileSource now uses a Resource to locate its directory
FtpSource closes the connection after poll
WebServiceHandler namespace support includes 'message-factory' and 'fault-message-resolver'
WebServiceHandler namespace supports injection of the WebServiceMessageCallback
Refactored FtpSource and FileSource to be better aligned
AggregatorBarrier correctly stops processing messages after completion
*** CONFIGURATION ***
Method-level @Handler can now be used without class-level @MessageEndpoint
The <channel-adapter/> with "ref" and "source" attributes replaces <source-endpoint/>
The <channel-adapter/> with "ref" and "target" attributes replaces <target-endpoint/>
The <channel-adapter/> accepts a "method" replacing <source-adapter/> and <target-adapter/>
The <router/> element is now a self-sufficient endpoint (rather than just creating a handler)
The <splitter/> element is now a self-sufficient endpoint (rather than just creating a handler)
The <aggregator/> element is now a self-sufficient endpoint (rather than just creating a handler)
Added namespace support for creating a MessageSelectorChain
*** WEB SERVICES AND XML ***
Added XML module
Added XSLT Transformer
Add Spring OXM transformer
Add XML Result transformer to convert from a Result to a Document
*** SECURITY ***
Added support for Spring Security on MessageChannels
Added support for Spring Security on endpoints
*** GENERAL ***
More Exceptions now provide the 'failedMessage'
Added a MessageRejectedException. It is thrown when a MessageSelector rejects a Message
Changes in version 1.0.0.M4 (May 23, 2008)
------------------------------------------
*** CORE API ***
Improved consistency of 'endpoint' with SourceEndpoint, TargetEndpoint, and HandlerEndpoint implementations
SourceEndpoint replaces PollingSourceAdapter and also provides better separation from the actual Source
ReplyCorrelator is now encapsulated within RequestReplyTemplate
Added MessagingGatewaySupport, SimpleMessagingGateway, and GatewayProxyFactoryBean for Request-Reply operations
Renamed SynchronousChannel to DirectChannel, also factored out ThreadLocalChannel
@Splitter-annotated methods now attempt to convert the Message payload (consistent with @Handler)
Added support for parameter-binding with @HeaderAttribute and @HeaderProperty annotations
Handler methods configured with namespace support now accept a Message payload
Implemented a MessageSelectorChain (consistent with MessageHandlerChain)
Added @CompletionStrategy annotation and CompletionStrategyAdapter for aggregators
The sequence number and sequence size are propagated correctly for POJO-based handler methods.
Source implementations may be connected to a DirectChannel
The ErrorHandler is now provided to ConcurrentTargets
Implemented RootCauseErrorMessageRouter
Added removeAttribute() and removeProperty() methods to MessageHeader
When passing to a handling method, primitive arrays are no longer cast to Object[]
Failed Messages (when available) are now propagated within MessageHandlingException and MessageDeliveryException
Provided configurable property for registering an asynchronous TaskExecutor for the ApplicationEventMulticaster
*** ADAPTERS ***
Provided namespace support for configuring the MessageHeaderMapper for JMS sources and targets
FileNameGenerator is now configurable for a FileTarget
File-Message mapping now supports text, binary, and File object
Mapping to JMS properties from the MessageHeader no longer fails on JMSException
*** CONFIGURATION ***
Added namespace support for the <gateway/> element
Added namespace support for the <splitter/> element
Added namespace support for the <router/> element
Added namespace support for different channel types (queue, priority, rendezvous, direct, thread-local)
Defined ChannelFactory strategy for the plain <channel/> elements and for the MessageBus 'auto-create' mode
Added namespace support for <console-source/> and <console-target/> elements
The <source-adapter/> element now produces a MethodInvokingSource
The <target-adapter/> element now produces a MethodInvokingTarget
Added annotation support for scheduling metadata on a message endpoint
@Splitter no longer accepts a "channel" attribute (now uses endpoint's output-channel)
A @MessageEndpoint annotated class now requires the presence of a handler method
The endpoint's <selector/> sub-element has been replaced by the "selector" attribute
The endpoint's <concurrency/> and <schedule/> elements can now occur in any order
Fixed timing issue between <annotation-driven/> and <message-bus/> in a ClasspathXmlApplicationContext
*** GENERAL ***
Now using the SpringSource Enterprise Bundle Repository for dependencies
Updated MANIFEST.MF files for imports, exports, and bundle metadata
Adjusted ivy configuration for provided and runtime dependency scopes
Moved spring.schemas and spring.handlers files to src/main/resources
Refactored the core's org.springframework.integration.adapter package contents into other packages
Added several diagrams to the Reference Documentation's "overview" section
Upgraded to Spring 2.5.4.A and Spring-WS 1.5.1.A
Changes in version 1.0.0.M3 (Apr 07, 2008)
------------------------------------------
*** CORE API ***
Handler method invocation now uses Spring's default type-conversion strategies
Message priorities are now defined in the MessagePriority enum
Added ResponseCorrelator for polling a reply channel with a correlationId
Added SynchronousChannel that invokes handlers on the sender's thread
or receives from a PollableSource on the receiver's thread
Implemented the WireTap pattern with a ChannelInterceptor that publishes to a secondary channel
Calling setErrorChannel on MessageBus no longer throws NullPointerException upon activation
ChannelPurger now accepts multiple MessageChannels (as varargs) in its constructors
RouterMessageHandlerAdapter now sets the ChannelRegistry on its target Object if it is ChannelRegistryAware
DefaultMessageEndpoint now sets the ChannelRegistry on any ChannelRegistryAware handler
MessageEndpointAnnotationPostProcessor now sets the ChannelRegistry for any annotated ChannelRegistryAware Object
*** ADAPTERS ***
Added FtpSourceAdapter
Added HttpInvokerSourceAdapter
Added HttpInvokerTargetAdapter
Added RmiSourceAdapter
Added RmiTargetAdapter
Added SimpleWebServiceTargetAdapter
Added MarshallingWebServiceTargetAdapter
Added a DefaultMailHeaderGenerator and defined constants in MailAttributeKeys
CharacterStreamSourceAdapter now requires a Reader (not InputStream)
CharacterStreamTargetAdapter now requires a Writer (not OutputStream)
The stdoutAdapter and stderrAdapter factory methods now accept a 'charsetName'
JMS source adapters now copy properties from the received JMS Message header
JMS source and target adapter parsers now consider "connectionFactory" as the default bean-name reference
*** CONFIGURATION ***
Added namespace support for PriorityChannel with the <priority-channel/> element
Added @Concurrency annotation for configuring a @MessageEndpoint's ConcurrencyPolicy
Added @Aggregator annotation for specifying aggregating handler methods
Added <aggregator/> element for defining an aggregating handler in XML
Annotation-based BeanPostProcessors now handle proxies correctly
Annotation-based BeanPostProcessors now recognize inherited class-level annotations
even if they are not explicitly @Inherited and even if they are on an interface
Added support for <rmi-source/> and <rmi-target/> elements
Added support for <httpinvoker-source/> and <httpinvoker-target/> elements
Added support for the <ftp-source/> element
Added support for the <ws-target/> element
Added support for the <mail-target/> element
*** GENERAL ***
The Spring Web Services support is included in a new 'spring-integration-ws' module
Updated manifest properties for OSGi-compliance in "core" and "adapters"
Added manifest properties for OSGi-compliance for "ws" and "samples"
Added "Bundle-Name" to each manifest file
Changes in version 1.0.0.m2 (Feb 28, 2008)
------------------------------------------
*** CORE API ***
Defined the ChannelInterceptor strategy interface
Implemented new priority-based MessageChannel (PriorityChannel)
Created a MessageSelectingInterceptor, a ChannelInterceptor that delegates to a MessageSelector
Added clear and purge methods to MessageChannel (purge accepts a MessageSelector)
Implemented a ChannelPurger that delegates to one or more MessageSelectors
ChannelRegistry now provides 'unregister' method for runtime removal of channels
Added RequestReplyTemplate for synchronous, blocking request/reply behavior over an asynchronous channel
Added isExpired() method to Message
Added a constructor to GenericMessage that copies MessageHeader properties and attributes
Using the header-copying constructor in MessageHandler adapters to preserve header information
Undeliverable replies from endpoint are passed to its ErrorHandler
ErrorHandler is now a configurable strategy for MessageEndpoints
ReplyHandler is now a configurable strategy for MessageEndpoints
Subscription is now immutable
Errors in ConcurrentHandler are now always logged at DEBUG level, and at WARN level if no 'errorHandler' is available
Endpoints now set the 'correlationId' on reply Messages
Defined Aggregator and CompletionStrategy and implemented an AggregatingMessageHandler
SplitterMessageHandlerAdapter now sets sequenceNumber and sequenceSize header properties automatically
Added 'sendTimeout' property to SplitterMessageHandlerAdapter
*** ADAPTERS ***
Added Mail target adapter
Acknowledge modes are now configurable for JmsMessageDrivenSourceAdapter
JMS attributes are now set from the MessageHeader prior to sending via JmsTargetAdapter
The <jms-source/> element now accepts a 'message-converter' attribute
*** CONFIGURATION ***
Added <interceptor/> sub-element for <channel/>
Added <selector/> sub-element for <endpoint/>
Added <handler-chain> element that accepts <handler/> sub-elements for creating a MessageHandlerChain
Added <aggregator/> element to the namespace for creating AggregatingMessageHandlers
Added "dataype" attribute to the <channel/> element for message payload datatype enforcement
Added 'initialDelay' and 'fixedRate' attributes to the @Polled annotation
Added 'destination-name' attribute for JmsTargetAdapter
Added 'autoStartup' property to MessageBus (and corresponding XML attribute) with a default value of 'true'
Added 'defaultConcurrencyPolicy' property to MessageBus (and corresponding XML sub-element)
Defined default error channel key as "errorChannel" (also added ERROR_CHANNEL_NAME constant in MessageBus)
*** GENERAL ***
Separated "spring-integration-core" from "spring-integration-adapters"
Added manifest properties for OSGi-compliance
Refactored package structure to remove all cycles
Using java.util.UUID for default ID generation strategy
Increased DEBUG logging throughout, especially for channel and endpoint
Components delegating to (Scheduled)ExecutorService are now configurable through standard injection

201
build-spring-integration/resources/license.txt
View File

@@ -1,201 +0,0 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

21
build-spring-integration/resources/notice.txt
View File

@@ -1,21 +0,0 @@
========================================================================
== NOTICE file corresponding to section 4 d of the Apache License, ==
== Version 2.0, in this case for the Spring Integration distribution. ==
========================================================================
This product includes software developed by
the Apache Software Foundation (http://www.apache.org).
The end-user documentation included with a redistribution, if any,
must include the following acknowledgement:
"This product includes software developed by the Spring Framework
Project (http://www.springframework.org)."
Alternatively, this acknowledgement may appear in the software itself,
if and wherever such third-party acknowledgements normally appear.
The names "Spring", "Spring Framework", and "Spring Integration" must
not be used to endorse or promote products derived from this software
without prior written permission. For written permission, please contact
enquiries@springsource.com.

29
build-spring-integration/resources/readme.txt
View File

@@ -1,29 +0,0 @@
SPRING INTEGRATION 2.0.0 Milestone 4 (May 8, 2010)
--------------------------------------------------
To find out what has changed since version 1.0.4 or 2.0 M3, see 'changelog.txt'
Please consult the documentation located within the 'docs/reference' directory of this
release and also visit the official Spring Integration home at:
http://www.springsource.org/spring-integration
There you will find links to the forum, issue tracker, and several other resources.
To build and run the sample applications that are included with this distribution,
view the README.txt file in the 'samples' directory.
To checkout the project from the SVN head and build from source, do the following
(NOTE: this requires Ant 1.7.1):
svn co https://src.springsource.org/svn/spring-integration/trunk .
cd build-spring-integration
ant jar test package
The result is available as a zip file in "build-spring-integration/target/artifacts"
An expanded version is also available in "build-spring-integration/target/package-expanded"
To build the JavaDoc, run 'ant javadoc-api' from within 'build-spring-integration'. The
result will be available in "build-spring-integration/target/javadoc-api".
The projects are Maven enabled, so you should be able to import them into any IDE that
has support for Maven (2.0.9 or greater).

12
build.properties
View File

@@ -1,12 +0,0 @@
version=2.0.0
release.type=integration
natural.name=spring-integration
project.name=Spring Integration
project.key=INT
ivy.cache.dir=${basedir}/../ivy-cache
integration.repo.dir=${basedir}/../integration-repo
javadoc.exclude.package.names=org/springframework/integration/samples/**
# dependency versions
spring.version=3.0.2.RELEASE
junit.version=4.7.0
mockito.version=1.8.0

6
spring-integration-parent/.classpath
View File

@@ -1,6 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
<classpathentry kind="con" path="org.maven.ide.eclipse.MAVEN2_CLASSPATH_CONTAINER"/>
<classpathentry kind="output" path="target/classes"/>
</classpath>

23
spring-integration-parent/.project
View File

@@ -1,23 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>spring-integration-parent</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
<buildCommand>
<name>org.maven.ide.eclipse.maven2Builder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.jdt.core.javanature</nature>
<nature>org.maven.ide.eclipse.maven2Nature</nature>
</natures>
</projectDescription>

7
spring-integration-parent/build.xml
View File

@@ -1,7 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="org.springframework.integration.spring-integration-parent">
<property file="${basedir}/../build.properties"/>
<import file="${basedir}/../spring-build/resource/default.xml"/>
</project>

19
spring-integration-parent/ivy.xml
View File

@@ -1,19 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="http://ivyrep.jayasoft.org/ivy-doc.xsl"?>
<ivy-module
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://incubator.apache.org/ivy/schemas/ivy.xsd"
version="1.3">
<info organisation="org.springframework.integration" module="${ant.project.name}">
<license name="Apache 2.0" url="http://www.apache.org/licenses/LICENSE-2.0"/>
</info>
<configurations>
<include file="${spring.build.dir}/common/default-ivy-configurations.xml"/>
</configurations>
<publications>
</publications>
</ivy-module>

277
spring-integration-parent/pom.xml
View File

@@ -1,277 +0,0 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.springframework.integration</groupId>
<artifactId>spring-integration-parent</artifactId>
<version>2.0.0.BUILD-SNAPSHOT</version>
<name>Spring Integration Parent</name>
<url>http://www.springsource.org/spring-integration</url>
<description> Spring Integration parent project. Defines dependencies and common configuration for
the build process. </description>
<packaging>pom</packaging>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<!-- versions for commonly-used dependencies -->
<cglib.version>2.2</cglib.version>
<junit.version>4.7</junit.version>
<log4j.version>1.2.12</log4j.version>
<org.aspectj.version>1.6.5</org.aspectj.version>
<org.easymock.version>2.3</org.easymock.version>
<org.eclipse.jdt.core.version>3.4.2.v_883_R34x</org.eclipse.jdt.core.version>
<org.mockito.version>1.8.4</org.mockito.version>
<org.slf4j.version>1.5.10</org.slf4j.version>
<org.springframework.version>3.0.2.RELEASE</org.springframework.version>
</properties>
<profiles>
<profile>
<id>non-strict</id>
<properties>
<maven.test.failure.ignore>true</maven.test.failure.ignore>
</properties>
</profile>
<profile>
<id>fast</id>
<properties>
<maven.test.skip>true</maven.test.skip>
<maven.javadoc.skip>true</maven.javadoc.skip>
</properties>
</profile>
<profile>
<id>staging</id>
<distributionManagement>
<site>
<id>staging</id>
<url>file:///${user.dir}/target/staging</url>
</site>
<repository>
<id>staging</id>
<url>file:///${user.dir}/target/staging</url>
</repository>
<snapshotRepository>
<id>staging</id>
<url>file:///${user.dir}/target/staging</url>
</snapshotRepository>
</distributionManagement>
</profile>
<profile>
<id>release</id>
<build>
<plugins>
<plugin>
<artifactId>maven-source-plugin</artifactId>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
<distributionManagement>
<site>
<id>staging</id>
<url>file:///${user.dir}/target/staging</url>
</site>
<repository>
<id>spring-milestone</id>
<name>Spring Milestone Repository</name>
<url>s3://maven.springframework.org/milestone</url>
</repository>
<snapshotRepository>
<id>spring-snapshot</id>
<name>Spring Snapshot Repository</name>
<url>s3://maven.springframework.org/snapshot</url>
</snapshotRepository>
</distributionManagement>
<build>
<extensions>
<extension>
<groupId>org.springframework.build.aws</groupId>
<artifactId>org.springframework.build.aws.maven</artifactId>
<version>2.0.0.RELEASE</version>
</extension>
</extensions>
<resources>
<resource>
<directory>${project.basedir}/src/main/java
</directory>
<includes>
<include>**/*</include>
</includes>
<excludes>
<exclude>**/*.java</exclude>
</excludes>
</resource>
<resource>
<directory>${project.basedir}/src/main/resources
</directory>
<includes>
<include>**/*</include>
</includes>
</resource>
</resources>
<testResources>
<testResource>
<directory>src/test/java</directory>
<includes>
<include>**/*</include>
</includes>
<excludes>
<exclude>**/*.java</exclude>
</excludes>
</testResource>
<testResource>
<directory>src/main/java</directory>
<includes>
<include>**/*</include>
</includes>
<excludes>
<exclude>**/*.java</exclude>
</excludes>
</testResource>
</testResources>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.5</source>
<target>1.5</target>
</configuration>
</plugin>
<!--
<plugin> <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.0.2</version> <configuration> <source>1.5</source>
<target>1.5</target> <compilerVersion>1.6</compilerVersion>
<fork>true</fork> <executable>java -jar
"${env.M2_REPO_C}/org/eclipse/jdt/core/${org.eclipse.jdt.core.version}/core-${org.eclipse.jdt.core.version}.jar"
-classpath rt.jar -sourcepath "src/main"</executable>
</configuration> <dependencies> <dependency>
<groupId>org.eclipse.jdt</groupId> <artifactId>core</artifactId>
<version>${org.eclipse.jdt.core.version}</version> </dependency>
</dependencies> </plugin>
-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<useFile>false</useFile>
<includes>
<include>**/*Tests.java</include>
</includes>
<excludes>
<exclude>**/Abstract*.java</exclude>
<exclude>**/PropertyPlaceholderTests.java</exclude>
</excludes>
<junitArtifactName>junit:junit</junitArtifactName>
</configuration>
</plugin>
</plugins>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant</artifactId>
<version>1.7.0</version>
</dependency>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant-trax</artifactId>
<version>1.7.0</version>
</dependency>
<dependency>
<groupId>org.apache.ant</groupId>
<artifactId>ant-apache-regexp</artifactId>
<version>1.7.0</version>
</dependency>
<dependency>
<groupId>foundrylogic.vpp</groupId>
<artifactId>vpp</artifactId>
<version>2.2.1</version>
</dependency>
</dependencies>
</plugin>
</plugins>
</pluginManagement>
</build>
<repositories>
<repository>
<id>glassfish</id>
<name> Glassfish Repository </name>
<url>http://download.java.net/maven/glassfish</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>jboss</id>
<name>JBoss Repository</name>
<url>http://repository.jboss.org/maven2</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>com.springsource.repository.bundles.release</id>
<name>SpringSource Enterprise Bundle Repository - SpringSource Bundle Releases</name>
<url>http://repository.springsource.com/maven/bundles/release</url>
</repository>
<repository>
<id>com.springsource.repository.bundles.external</id>
<name>SpringSource Enterprise Bundle Repository - External Bundle Releases</name>
<url>http://repository.springsource.com/maven/bundles/external</url>
</repository>
<repository>
<id>objectstyle</id>
<name>ObjectStyle.org Repository</name>
<url>http://objectstyle.org/maven2/</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>com.springsource.repository.bundles.milestone</id>
<name>SpringSource Enterprise Bundle Repository - SpringSource Bundle Milestones</name>
<url>http://repository.springsource.com/maven/bundles/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>com.springsource.repository.bundles.snapshot</id>
<name>SpringSource Enterprise Bundle Repository - SpringSource Bundle Snapshots</name>
<url>http://repository.springsource.com/maven/bundles/snapshot</url>
</pluginRepository>
<pluginRepository>
<id>agilejava</id>
<url>http://agilejava.com/maven</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
<dependencies>
<!-- including log4j to quell respect src/test log4j.xml settings -->
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>${log4j.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>

9
spring-integration-reference/build.xml
View File

@@ -1,9 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<project name="spring-integration-reference" default="doc">
<property name="doc.type" value="reference"/>
<property file="${basedir}/../build.properties"/>
<import file="../spring-build/docbook/default.xml"/>
</project>

35
spring-integration-reference/css/html/highlight.css
View File

@@ -1,35 +0,0 @@
/*
code highlight CSS resemblign the Eclipse IDE default color schema
@author Costin Leau
*/
.hl-keyword {
color: #7F0055;
font-weight: bold;
}
.hl-comment {
color: #3F5F5F;
font-style: italic;
}
.hl-multiline-comment {
color: #3F5FBF;
font-style: italic;
}
.hl-tag {
color: #3F7F7F;
}
.hl-attribute {
color: #7F007F;
}
.hl-value {
color: #2A00FF;
}
.hl-string {
color: #2A00FF;
}

99
spring-integration-reference/css/html/stylesheet.css
View File

@@ -1,99 +0,0 @@
@IMPORT url("highlight.css");
html {
padding: 0pt;
margin: 0pt;
}
body {
margin-left: 10%;
margin-right: 10%;
font-family: Arial, Sans-serif;
}
div {
margin: 0pt;
}
p {
text-align: justify;
}
hr {
border: 1px solid gray;
background: gray;
}
h1,h2,h3,h4 {
color: #234623;
font-family: Arial, Sans-serif;
}
pre {
line-height: 1.0;
color: black;
}
pre.programlisting {
font-size: 10pt;
padding: 7pt 3pt;
border: 1pt solid black;
background: #eeeeee;
clear: both;
}
div.table {
margin: 1em;
padding: 0.5em;
text-align: center;
}
div.table table {
display: table;
width: 100%;
}
div.table td {
padding-left: 7px;
padding-right: 7px;
}
.sidebar {
float: right;
margin: 10px 0 10px 30px;
padding: 10px 20px 20px 20px;
width: 33%;
border: 1px solid black;
background-color: #F4F4F4;
font-size: 14px;
}
.mediaobject {
padding-top: 30px;
padding-bottom: 30px;
}
.legalnotice {
font-family: Verdana, Arial, helvetica, sans-serif;
font-size: 12px;
font-style: italic;
}
p.releaseinfo {
font-size: 100%;
font-weight: bold;
font-family: Verdana, Arial, helvetica, sans-serif;
padding-top: 10px;
}
p.pubdate {
font-size: 120%;
font-weight: bold;
font-family: Verdana, Arial, helvetica, sans-serif;
}
span.productname {
font-size: 200%;
font-weight: bold;
font-family: Verdana, Arial, helvetica, sans-serif;
}

BIN
spring-integration-reference/images/cafe-demo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 34 KiB

BIN
spring-integration-reference/images/channel.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 23 KiB

BIN
spring-integration-reference/images/handler-endpoint.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 34 KiB

BIN
spring-integration-reference/images/handler.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 23 KiB

BIN
spring-integration-reference/images/logo.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 9.4 KiB

BIN
spring-integration-reference/images/message-bus.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 42 KiB

BIN
spring-integration-reference/images/message.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

BIN
spring-integration-reference/images/router.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
spring-integration-reference/images/source-endpoint.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 25 KiB

BIN
spring-integration-reference/images/source.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 21 KiB

BIN
spring-integration-reference/images/target-endpoint.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 25 KiB

BIN
spring-integration-reference/images/target.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 22 KiB

23
spring-integration-reference/ivy.xml
View File

@@ -1,23 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="http://ivyrep.jayasoft.org/ivy-doc.xsl"?>
<ivy-module
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://incubator.apache.org/ivy/schemas/ivy.xsd"
version="1.3">
<info organisation="org.springframework.integration" module="${ant.project.name}"/>
<configurations>
<include file="${spring.build.dir}/common/default-ivy-configurations.xml"/>
<conf name="doc" visibility="public" description="Documentation"/>
</configurations>
<publications>
<artifact name="${ant.project.name}" ext="pdf" type="pdf"/>
<artifact name="${ant.project.name}" ext="zip" type="zip"/>
<artifact name="${ant.project.name}-single" ext="zip" type="zip"/>
</publications>
<dependencies/>
</ivy-module>

519
spring-integration-reference/src/aggregator.xml
View File

@@ -1,519 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="aggregator">
<title>Aggregator</title>
<section id="aggregator-introduction">
<title>Introduction</title>
<para>Basically a mirror-image of the Splitter, the Aggregator is a type
of Message Handler that receives multiple Messages and combines them into
a single Message. In fact, Aggregators are often downstream consumers in a
pipeline that includes a Splitter.</para>
<para>Technically, the Aggregator is more complex than a Splitter, because
it is required to maintain state (the Messages to-be-aggregated), to
decide when the complete group of Messages is available.</para>
</section>
<section id="aggregator-functionality">
<title>Functionality</title>
<para>The Aggregator combines a group of related messages, by correlating
and storing them, until the group is deemed complete. At that point, the
Aggregator will create a single message by processing the whole group, and
will send that aggregated message as output.</para>
<para>An important aspect of
implementing an Aggregator is providing the logic that has to be executed
when the aggregation (creation of a single message out of many) takes
place.</para>
<para>In Spring Integration, the grouping of the messages for aggregation
is done by default based on their CORRELATION_ID message header (i.e. the
messages with the same CORRELATION_ID will be grouped together). However,
this can be customized, and the users can opt for other ways of
specifying how the messages should be grouped together, by using a
CorrelationStrategy (see below).</para>
<para>Another important concern is, what happens if
late messages arrive after the aggregation has taken place? In this case,
the user needs to be able to decide whether they should be
discarded or not.</para>
</section>
<section id="aggregator-api">
<title>Programming model</title>
<para>The Aggregation API consists of a number of classes:</para>
<itemizedlist>
<listitem>
<para>The interface <code>MessageGroupProcessor</code> and related
base class <code>AbstractAggregatingMessageGroupProcessor</code> and its
subclass <code>MethodInvokingAggregatingMessageGroupProcessor</code></para>
</listitem>
<listitem>
<para>The <code>ReleaseStrategy</code> interface and its default
implementation <code>SequenceSizeReleaseStrategy</code></para>
</listitem>
<listitem>
<para>The <code>CorrelationStrategy</code> interface and its default
implementation <code>HeaderAttributeCorrelationStrategy</code></para>
</listitem>
</itemizedlist>
<section>
<title>CorrelatingMessageHandler</title>
<para>The <code>CorrelatingMessageHandler</code> is a
<code>MessageHandler</code> implementation, encapsulating the common
functionalities of an Aggregator (and other correlating use cases), which are:
<itemizedlist>
<listitem>
<para>correlating messages into a group to be aggregated</para>
</listitem>
<listitem>
<para>maintaining those messages until the group is complete</para>
</listitem>
<listitem>
<para>deciding when the group is in fact complete</para>
</listitem>
<listitem>
<para>processing the completed group into a single aggregated message</para>
</listitem>
<listitem>
<para>recognizing and responding to an expired group</para>
</listitem>
</itemizedlist>
The responsibility of deciding how the messages should be grouped together
is delegated to a <code>CorrelationStrategy</code> instance. The responsibility
of deciding whether the message group can be released is delegated to a
<code>ReleaseStrategy</code> instance.</para>
<para>Here is a brief highlight of the base
<code>AbstractAggregatingMessageGroupProcessor</code> (the responsibility of
implementing the aggregateMessages method is left to the
developer):</para>
<programlisting language="java">public abstract class AbstractAggregatingMessageGroupProcessor
implements MessageGroupProcessor {
protected Map&lt;String, Object&gt; aggregateHeaders(MessageGroup group) {
....
}
protected abstract Object aggregatePayloads(MessageGroup group);
}</programlisting>
The CorrelationStrategy is owned by the <code>CorrelatingMessageHandler</code> and it has
a default value based on the correlation ID message header:
<programlisting language="java">private volatile CorrelationStrategy correlationStrategy =
new HeaderAttributeCorrelationStrategy(MessageHeaders.CORRELATION_ID);</programlisting>
<para>When appropriate, the simplest option is the <code>DefaultAggregatingMessageGroupProcessor</code>.
It creates a single Message whose payload is a List of the payloads received
for a given group. It uses the default <code>CorrelationStrategy</code> and
<code>CompletionStrategy</code> as shown above. This works well for simple
Scatter Gather implementations with either a Splitter, Publish Subscribe Channel,
or Recipient List Router upstream.</para>
<note>
<para>When using a Publish Subscribe Channel or Recipient List Router in this
type of scenario, be sure to enable the flag to <emphasis>apply sequence</emphasis>.
That will add the necessary headers (correlation id, sequence number and sequence
size). That behavior is enabled by default for Splitters in Spring Integration,
but it is not enabled for the Publish Subscribe Channel or Recipient List
Router because those components may be used in a variety of contexts where
those headers are not necessary.</para>
</note>
<para>When implementing a specific aggregator object for an application,
a developer can extend <code>AbstractAggregatingMessageGroupProcessor</code> and
implement the <code>aggregatePayloads</code> method. However, there are
better suited (which reads, less coupled to the API) solutions for
implementing the aggregation logic, which can be configured easily
either through XML or through annotations.</para>
<para>In general, any ordinary Java class (i.e. POJO) can implement the
aggregation algorithm. For doing so, it must provide a method that
accepts as an argument a single java.util.List (parametrized lists are
supported as well). This method will be invoked for aggregating
messages, as follows:</para>
<itemizedlist>
<listitem>
<para>if the argument is a parametrized java.util.List, and the
parameter type is assignable to Message, then the whole list of
messages accumulated for aggregation will be sent to the
aggregator</para>
</listitem>
<listitem>
<para>if the argument is a non-parametrized java.util.List or the
parameter type is not assignable to Message, then the method will
receive the payloads of the accumulated messages</para>
</listitem>
<listitem>
<para>if the return type is not assignable to Message, then it will
be treated as the payload for a Message that will be created
automatically by the framework.</para>
</listitem>
</itemizedlist>
<note>
<para>In the interest of code simplicity, and promoting best practices
such as low coupling, testability, etc., the preferred way of
implementing the aggregation logic is through a POJO, and using the
XML or annotation support for setting it up in the application.</para>
</note>
</section>
<section>
<title>ReleaseStrategy</title>
<para>The <code>ReleaseStrategy</code> interface is defined as
follows:</para>
<programlisting language="java">public interface ReleaseStrategy {
boolean canRelease(MessageGroup messages);
}</programlisting>
<para>In general, any ordinary Java class (i.e. POJO) can implement the
completion decision mechanism. For doing so, it must provide a method
that accepts as an argument a single java.util.List (parametrized lists
are supported as well), and returns a boolean value. This method will be
invoked after the arrival of a new message, to decide whether the group
is complete or not, as follows:</para>
<itemizedlist>
<listitem>
<para>if the argument is a parametrized java.util.List, and the
parameter type is assignable to Message, then the whole list of
messages accumulated in the group will be sent to the method</para>
</listitem>
<listitem>
<para>if the argument is a non-parametrized java.util.List or the
parameter type is not assignable to Message, then the method will
receive the payloads of the accumulated messages</para>
</listitem>
<listitem>
<para>the method must return true if the message group is ready
for aggregation, and false otherwise.</para>
</listitem>
</itemizedlist>
<para>When the group is released for aggregation, all its
unmarked messages are processed and then marked so they will not
be processed again. If the group is also complete (i.e. if all
messages from a sequence have arrived or if there is no sequence
defined) then the group is removed from the message store.
Partial sequences can be released, in which case the next time
the <code>ReleaseStrategy</code> is called it will be presented
with a group containing marked messages (already processed) and
unmarked messages (a potential new partial sequence)</para>
<para>Spring Integration provides an out-of-the box implementation for
<code>ReleaseStrategy</code>, the
<code>SequenceSizerReleaseStrategy</code>. This implementation uses
the SEQUENCE_NUMBER and SEQUENCE_SIZE of the arriving messages for
deciding when a message group is complete and ready to be
aggregated. As shown above, it is also the default strategy.</para>
</section>
<section>
<title>CorrelationStrategy</title>
<para>The <code>CorrelationStrategy</code> interface is defined as
follows:</para>
<programlisting language="java">public interface CorrelationStrategy {
Object getCorrelationKey(Message&lt;?&gt; message);
}</programlisting>
<para>The method shall return an Object which represents the correlation
key used for grouping messages together. The key must satisfy the
criteria used for a key in a Map with respect to the implementation of
equals() and hashCode().</para>
<para>In general, any ordinary Java class (i.e. POJO) can implement the
correlation decision mechanism, and the rules for mapping a message to
a method's argument (or arguments) are the same as for a
<code>ServiceActivator</code> (including support for @Header
annotations). The method must return a value, and the value must not be
<code>null</code>.</para>
<para>Spring Integration provides an out-of-the box implementation for
<code>CorrelationStrategy</code>, the
<code>HeaderAttributeCorrelationStrategy</code>. This implementation
returns the value of one of the message headers (whose name is specified
by a constructor argument) as the correlation key. By default, the
correlation strategy is a HeaderAttributeCorrelationStrategy returning
the value of the CORRELATION_ID header attribute.</para>
</section>
</section>
<section id="aggregator-xml">
<title>Configuring an Aggregator with XML</title>
<para>Spring Integration supports the configuration of an aggregator via
XML through the &lt;aggregator/&gt; element. Below you can see an example of
an aggregator with all optional parameters defined.</para>
<programlisting lang="xml">&lt;channel id="inputChannel"/&gt;
&lt;aggregator id="completelyDefinedAggregator" <co id="aggxml1" />
input-channel="inputChannel" <co id="aggxml2" />
output-channel="outputChannel" <co id="aggxml3" />
discard-channel="discardChannel" <co id="aggxml4" />
ref="aggregatorBean" <co id="aggxml5" />
method="add" <co id="aggxml6" />
release-strategy="releaseStrategyBean" <co id="aggxml7" />
release-strategy-method="canRelease" <co id="aggxml8" />
correlation-strategy="correlationStrategyBean" <co
id="aggxmlCorrelationStrategy" />
correlation-strategy-method="groupNumbersByLastDigit" <co
id="aggxmlCorrelationStrategyMethod" />
message-store="messageStore" <co id="aggxml11-co" linkends="aggxml11"/>
send-partial-result-on-expiry="true" <co id="aggxml9" />
send-timeout="86420000" <co id="aggxml10" /> /&gt;
&lt;channel id="outputChannel"/&gt;
&lt;bean id="aggregatorBean" class="sample.PojoAggregator"/&gt;
&lt;bean id="releaseStrategyBean" class="sample.PojoReleaseStrategy"/&gt;
&lt;bean id="correlationStrategyBean" class="sample.PojoCorrelationStrategy"/&gt;</programlisting>
<calloutlist>
<callout arearefs="aggxml1">
<para>The id of the aggregator is
<emphasis>optional</emphasis>.</para>
</callout>
<callout arearefs="aggxml2">
<para>The input channel of the aggregator.
<emphasis>Required</emphasis>.</para>
</callout>
<callout arearefs="aggxml3">
<para>The channel where the aggregator will send the aggregation
results. <emphasis>Optional (because incoming messages can specify a
reply channel themselves)</emphasis>.</para>
</callout>
<callout arearefs="aggxml4">
<para>The channel where the aggregator will send the messages that
timed out (if <code>send-partial-results-on-timeout</code> is
<emphasis>false</emphasis>). <emphasis>Optional</emphasis>.</para>
</callout>
<callout arearefs="aggxml5">
<para>A reference to a bean defined in the application context. The
bean must implement the aggregation logic as described above.
<emphasis>Required</emphasis>.</para>
</callout>
<callout arearefs="aggxml6">
<para>A method defined on the bean referenced by <code>ref</code>,
<emphasis>that implements the message aggregation
algorithm.</emphasis> <emphasis>Optional, with restrictions (see
above).</emphasis></para>
</callout>
<callout arearefs="aggxml7">
<para>A reference to a bean that implements the decision algorithm as
to whether a given message group is complete. The bean can be an
implementation of the CompletionStrategy interface or a POJO. In the
latter case the completion-strategy-method attribute must be defined
as well. <emphasis>Optional (by default, the aggregator will use
sequence size) </emphasis>.</para>
</callout>
<callout arearefs="aggxml8">
<para>A method defined on the bean referenced by
<code>release-strategy</code>, <emphasis>that implements the
completion decision algorithm.</emphasis> <emphasis>Optional, with
restrictions (requires <code>completion-strategy</code> to be
present).</emphasis></para>
</callout>
<callout arearefs="aggxmlCorrelationStrategy">
<para>A reference to a bean that implements the correlation strategy.
The bean can be an implementation of the CorrelationStrategy interface
or a POJO. In the latter case the correlation-strategy-method
attribute must be defined as well. <emphasis>Optional (by default, the
aggregator will use the correlation id header attribute)
</emphasis>.</para>
</callout>
<callout arearefs="aggxmlCorrelationStrategyMethod">
<para>A method defined on the bean referenced by
<code>correlation-strategy</code>, <emphasis>that implements the
correlation key algorithm.</emphasis> <emphasis>Optional, with
restrictions (requires <code>correlation-strategy</code> to be
present).</emphasis></para>
</callout>
<callout arearefs="aggxml11-co" id="aggxml11">
<para>A reference to a <code>MessageGroupStore</code> that
can be used to store groups of messages under their
correlation key until they are
complete. <emphasis>Optional</emphasis> with default a
volatile in-memory store.</para>
</callout>
<callout arch="" arearefs="aggxml9">
<para>Whether upon the expiration of the message group, the aggregator will
try to aggregate the messages that have already arrived. <emphasis>Optional
(false by default)</emphasis>.</para>
</callout>
<callout arearefs="aggxml10">
<para>The timeout for sending the aggregated messages to the
output or reply channel. <emphasis>Optional</emphasis>.</para>
</callout>
</calloutlist>
<para>Using a "ref" attribute is generally recommended if a custom aggregator handler
implementation can be reused in other <code>&lt;aggregator&gt;</code> definitions.
However if a custom aggregator handler implementation should be scoped to a concrete
definition of the <code>&lt;aggregator&gt;</code>, you can use an inner bean definition
(starting with version 1.0.3) for custom aggregator handlers within the
<code>&lt;aggregator&gt;</code> element:
<programlisting language="xml"><![CDATA[<aggregator input-channel="input" method="sum" output-channel="output">
<beans:bean class="org.foo.ExampleAggregator"/>
</aggregator>]]></programlisting>
</para>
<note>
<para>Using both a "ref" attribute and an inner bean definition in the same
<code>&lt;aggregator&gt;</code> configuration is not allowed, as it creates an
ambiguous condition. In such cases, an Exception will be thrown.
</para>
</note>
<para>An example implementation of the aggregator bean looks as follows:</para>
<programlisting language="java">public class PojoAggregator {
public Long add(List&lt;Long&gt; results) {
long total = 0l;
for (long partialResult: results) {
total += partialResult;
}
return total;
}
}</programlisting>
<para>An implementation of the completion strategy bean for the example
above may be as follows:</para>
<para><programlisting language="java">public class PojoReleaseStrategy {
...
public boolean canRelease(List&lt;Long&gt; numbers) {
int sum = 0;
for (long number: numbers) {
sum += number;
}
return sum &gt;= maxValue;
}
}</programlisting>
<note>
<para>Wherever it makes sense, the release strategy method and
the aggregator method can be combined in a single bean.</para>
</note>
</para>
<para>An implementation of the correlation strategy bean for the example
above may be as follows:</para>
<para><programlisting language="java">public class PojoCorrelationStrategy {
...
public Long groupNumbersByLastDigit(Long number) {
return number % 10;
}
}</programlisting></para>
<para>For example, this aggregator would group numbers by some criterion
(in our case the remainder after dividing by 10) and will hold the group
until the sum of the numbers which represents the payload exceeds a
certain value.</para>
<note>
<para>Wherever it makes sense, the release strategy method, correlation
strategy method and the aggregator method can be combined in a single bean
(all of them or any two).</para>
</note>
</section>
<section id="aggregator-annotations">
<title>Configuring an Aggregator with Annotations</title>
<para>An aggregator configured using annotations can look like
this.</para>
<programlisting language="java">public class Waiter {
...
@Aggregator <co id="aggann" />
public Delivery aggregatingMethod(List&lt;OrderItem&gt; items) {
...
}
@ReleaseStrategy <co id="agganncs" />
public boolean releaseChecker(List&lt;Message&lt;?&gt;&gt; messages) {
...
}
@CorrelationStrategy <co id="agganncorrs" />
public String correlateBy(OrderItem item) {
...
}
}</programlisting>
<calloutlist>
<callout arearefs="aggann">
<para>An annotation indicating that this method shall be used as an
aggregator. Must be specified if this class will be used as an
aggregator.</para>
</callout>
<callout arearefs="agganncs">
<para id="aggann2">An annotation indicating that this method shall be
used as the release strategy of an aggregator. If not present on
any method, the aggregator will use the
SequenceSizeCompletionStrategy.</para>
</callout>
<callout arearefs="agganncorrs">
<para id="agann3">An annotation indicating that this method shall be
used as the correlation strategy of an aggregator. If no correlation
strategy is indicated, the aggregator will use the
HeaderAttributeCorrelationStrategy based on CORRELATION_ID.</para>
</callout>
</calloutlist>
<para>All of the configuration options provided by the xml element are also
available for the @Aggregator annotation.</para>
<para>The aggregator can be either referenced explicitly from XML or, if
the @MessageEndpoint is defined on the class, detected automatically
through classpath scanning.</para>
</section>
</chapter>

62
spring-integration-reference/src/bridge.xml
View File

@@ -1,62 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="bridge">
<title>Messaging Bridge</title>
<section id="bridge-introduction">
<title>Introduction</title>
<para>
A Messaging Bridge is a relatively trivial endpoint that simply connects two Message Channels or Channel
Adapters. For example, you may want to connect a <interfacename>PollableChannel</interfacename> to a
<interfacename>SubscribableChannel</interfacename> so that the subscribing endpoints do not have to worry
about any polling configuration. Instead, the Messaging Bridge provides the polling configuration.
</para>
<para>
By providing an intermediary poller between two channels, a Messaging Bridge can be used to throttle inbound
Messages. The poller's trigger will determine the rate at which messages arrive on the second channel, and the
poller's "maxMessagesPerPoll" property will enforce a limit on the throughput.
</para>
<para>
Another valid use for a Messaging Bridge is to connect two different systems. In such a scenario, Spring
Integration's role would be limited to making the connection between these systems and managing a poller
if necessary. It is probably more common to have at least a <emphasis>Transformer</emphasis> between the
two systems to translate between their formats, and in that case, the channels would be provided as the
'input-channel' and 'output-channel' of a Transformer endpoint. If data format translation is not required,
the Messaging Bridge may indeed be sufficient.
</para>
</section>
<section id="bridge-namespace">
<title>The &lt;bridge&gt; Element</title>
<para>
The &lt;bridge&gt; element is used to create a Messaging Bridge between two Message Channels or Channel Adapters.
Simply provide the "input-channel" and "output-channel" attributes:
<programlisting language="xml"><![CDATA[ <bridge input-channel="input" output-channel="output"/>]]></programlisting>
As mentioned above, a common use case for the Messaging Bridge is to connect a
<interfacename>PollableChannel</interfacename> to a <interfacename>SubscribableChannel</interfacename>, and when
performing this role, the Messaging Bridge may also serve as a throttler:
<programlisting language="xml"><![CDATA[ <bridge input-channel="pollable" output-channel="subscribable">
<poller max-messages-per-poll="10">
<interval-trigger interval="5" time-unit="SECONDS"/>
</poller>
</bridge>]]></programlisting>
</para>
<para>
Connecting Channel Adapters is just as easy. Here is a simple echo example between the "stdin" and "stdout"
adapters from Spring Integration's "stream" namespace.
<programlisting language="xml"><![CDATA[ <stream:stdin-channel-adapter id="stdin"/>
<stream:stdout-channel-adapter id="stdout"/>
<bridge id="echo" input-channel="stdin" output-channel="stdout"/>]]></programlisting>
Of course, the configuration would be similar for other (potentially more useful) Channel Adapter bridges, such
as File to JMS, or Mail to File. The various Channel Adapters will be discussed in upcoming chapters.
</para>
<note>
<para>If no 'output-channel' is defined on a bridge, the reply channel provided by the inbound Message will
be used, if available. If neither output or reply channel is available, an Exception will be thrown.</para>
</note>
</section>
</chapter>

115
spring-integration-reference/src/chain.xml
View File

@@ -1,115 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="chain">
<title>Message Handler Chain</title>
<section id="chain-introduction">
<title>Introduction</title>
<para>
The <classname>MessageHandlerChain</classname> is an implementation of
<interfacename>MessageHandler</interfacename> that can be configured as a single Message Endpoint while
actually delegating to a chain of other handlers, such as Filters, Transformers, Splitters, and so on.
This can lead to a much simpler configuration when several handlers need to be connected in a fixed, linear
progression. For example, it is fairly common to provide a Transformer before other components. Similarly, when
providing a <emphasis>Filter</emphasis> before some other component in a chain, you are essentially creating a
<ulink url="http://www.eaipatterns.com/MessageSelector.html">Selective Consumer</ulink>. In either case, the
chain only requires a single input-channel and a single output-channel as opposed to the configuration of
channels for each individual component.
<tip>
Spring Integration's <emphasis>Filter</emphasis> provides a boolean property 'throwExceptionOnRejection'. When
providing multiple Selective Consumers on the same point-to-point channel with different acceptance criteria,
this value should be set to 'true' (the default is false) so that the dispatcher will know that the Message was
rejected and as a result will attempt to pass the Message on to other subscribers. If the Exception were not
thrown, then it would appear to the dispatcher as if the Message had been passed on successfully even though
the Filter had <emphasis>dropped</emphasis> the Message to prevent further processing.
</tip>
</para>
<para>
The handler chain simplifies configuration while internally maintaining the same degree of loose coupling between
components, and it is trivial to modify the configuration if at some point a non-linear arrangement is required.
</para>
<para>
Internally, the chain will be expanded into a linear setup of the listed endpoints, separated by direct channels.
The reply channel header will not be taken into account within the chain: only after the last handler is invoked
will the resulting message be forwarded on to the reply channel or the chain's output channel. Because of this
setup all handlers except the last require a <methodname>setOutputChannel</methodname> implementation. The last
handler only needs an output channel if the outputChannel on the MessageHandlerChain is set.
<note>
<para>
As with other endpoints, the output-channel is optional. If there is a reply Message at the end of the
chain, the output-channel takes precedence, but if not available, the chain handler will check for a
reply channel header on the inbound Message.
</para>
</note>
</para>
<para>
In most cases there is no need to implement MessageHandlers yourself. The next section will focus on namespace
support for the chain element. Most Spring Integration endpoints, like Service Activators and Transformers, are
suitable for use within a <classname>MessageHandlerChain</classname>.
</para>
</section>
<section id="chain-namespace">
<title>The &lt;chain&gt; Element</title>
<para>
The &lt;chain&gt; element provides an 'input-channel' attribute, and if the last element in the chain is capable
of producing reply messages (optional), it also supports an 'output-channel' attribute. The sub-elements are then
filters, transformers, splitters, and service-activators. The last element may also be a router.
<programlisting language="xml"><![CDATA[ <chain input-channel="input" output-channel="output">
<filter ref="someSelector" throw-exception-on-rejection="true"/>
<header-enricher error-channel="customErrorChannel">
<header name="foo" value="bar"/>
</header-enricher>
<service-activator ref="someService" method="someMethod"/>
</chain>]]></programlisting>
</para>
<para>
The &lt;header-enricher&gt; element used in the above example will set a message header with name "foo" and
value "bar" on the message. A header enricher is a specialization of Transformer that touches only header
values. You could obtain the same result by implementing a MessageHandler that did the header modifications
and wiring that as a bean.
</para>
<para>
Some time you need to make a nested call to another chain from within the chain and then come
back and continue execution within the original chain.
To accomplish this you can utilize Messaging Gateway by including light-configuration via &lt;gateway&gt; element.
For example:
<programlisting language="xml"><![CDATA[ <si:chain id="main-chain" input-channel="inputA" output-channel="inputB">
<si:header-enricher>
<si:header name="name" value="Many" />
</si:header-enricher>
<si:service-activator>
<bean class="org.foo.SampleService" />
</si:service-activator>
<si:gateway request-channel="inputC"/>  
</si:chain>
<si:chain id="nested-chain-a" input-channel="inputC">
<si:header-enricher>
<si:header name="name" value="Moe" />
</si:header-enricher>
<si:gateway request-channel="inputD"/> 
<si:service-activator>
<bean class="org.foo.SampleService" />
</si:service-activator>
</si:chain>
<si:chain id="nested-chain-b" input-channel="inputD">
<si:header-enricher>
<si:header name="name" value="Jack" />
</si:header-enricher>
<si:service-activator>
<bean class="org.foo.SampleService" />
</si:service-activator>
</si:chain>]]></programlisting>
In the above example the <emphasis>nested-chain-a</emphasis> will be called at the end of <emphasis>main-chain</emphasis> processing by the 'gateway' element
configured there. While in <emphasis>nested-chain-a</emphasis> a call to a <emphasis>nested-chain-b</emphasis> will be made after header enrichment and then it will
come back to finish execution in <emphasis>nested-chain-b</emphasis> finally getting back to the <emphasis>main-chain</emphasis>.
When light version of &lt;gateway&gt; element is defined in the chain SI will construct an instance <classname>SimpleMessagingGateway</classname>
(no need to provide 'service-interface' configuration) which will take the message in its current state and will place it on the channel defined via 'request-channel' attribute.
Upon processing <classname>Message</classname> will be returned to the gateway and continue its journey within the current chain.
</para>
</section>
</chapter>

83
spring-integration-reference/src/channel-adapter.xml
View File

@@ -1,83 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="channel-adapter">
<title>Channel Adapter</title>
<para>
A Channel Adapter is a Message Endpoint that enables connecting a single sender or receiver to a Message Channel.
Spring Integration provides a number of adapters out of the box to support various transports, such as JMS, File,
HTTP, Web Services, and Mail. Those will be discussed in upcoming chapters of this reference guide. However, this
chapter focuses on the simple but flexible Method-invoking Channel Adapter support. There are both inbound and
outbound adapters, and each may be configured with XML elements provided in the core namespace.
</para>
<section id="channel-adapter-namespace-inbound">
<title>The &lt;inbound-channel-adapter&gt; element</title>
<para>
An "inbound-channel-adapter" element can invoke any method on a Spring-managed Object and send a non-null return
value to a <interfacename>MessageChannel</interfacename> after converting it to a <classname>Message</classname>.
When the adapter's subscription is activated, a poller will attempt to receive messages from the source. The
poller will be scheduled with the <interfacename>TaskScheduler</interfacename> according to the provided
configuration. To configure the polling interval or cron expression for an individual channel-adapter,
provide a 'poller' element with either an 'interval-trigger' (in milliseconds) or 'cron-trigger'
sub-element.
<programlisting language="xml"><![CDATA[<inbound-channel-adapter ref="source1" method="method1" channel="channel1">
<poller>
<interval-trigger interval="5000"/>
</poller>
</inbound-channel-adapter>
<inbound-channel-adapter ref="source2" method="method2" channel="channel2">
<poller>
<cron-trigger expression="30 * 9-17 * * MON-FRI"/>
</poller>
</channel-adapter>]]></programlisting>
</para>
<note>
<para>
If no poller is provided, then a single default poller must be registered within the context.
See <xref linkend="endpoint-namespace"/> for more detail.
</para>
</note>
</section>
<section id="channel-adapter-namespace-outbound">
<title>The &lt;outbound-channel-adapter/&gt; element</title>
<para>
An "outbound-channel-adapter" element can also connect a <interfacename>MessageChannel</interfacename> to any POJO consumer
method that should be invoked with the payload of Messages sent to that channel.
<programlisting language="xml"><![CDATA[<outbound-channel-adapter channel="channel1" ref="target1" method="method1"/>]]></programlisting>
If the channel being adapted is a <interfacename>PollableChannel</interfacename>, provide a poller sub-element:
<programlisting language="xml"><![CDATA[<outbound-channel-adapter channel="channel2" ref="target2" method="method2">
]]><emphasis><![CDATA[<poller>
<interval-trigger interval="3000"/>
</poller>]]></emphasis><![CDATA[
</outbound-channel-adapter>
<beans:bean id="target1" class="org.bar.Foo"/>
]]></programlisting>
</para>
<para>
Using a "ref" attribute is generally recommended if the POJO consumer implementation can be reused
in other <code>&lt;outbound-channel-adapter&gt;</code> definitions. However if the consumer implementation
should be scoped to a single definition of the <code>&lt;outbound-channel-adapter&gt;</code>, you can define it as inner bean:
<programlisting language="xml"><![CDATA[<outbound-channel-adapter channel="channel2" method="method2">
<beans:bean class="org.bar.Foo"/>
]]><![CDATA[
</outbound-channel-adapter>
]]></programlisting>
</para>
<note>
<para>
Using both the "ref" attribute and an inner handler definition in the same <code>&lt;outbound-channel-adapter&gt;</code>
configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
</para>
</note>
<para>
Any Channel Adapter can be created without a "channel" reference in which case it will implicitly create an
instance of <classname>DirectChannel</classname>. The created channel's name will match the "id" attribute
of the &lt;inbound-channel-adapter/&gt; or &lt;outbound-channel-adapter&gtl; element. Therefore, if the "channel"
is not provided, the "id" is required.
</para>
</section>
</chapter>

595
spring-integration-reference/src/channel.xml
View File

@@ -1,595 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="channel">
<title>Message Channels</title>
<para>
While the <interfacename>Message</interfacename> plays the crucial role of encapsulating data, it is the
<interfacename>MessageChannel</interfacename> that decouples message producers from message consumers.
</para>
<section id="channel-interfaces">
<title>The MessageChannel Interface</title>
<para>
Spring Integration's top-level <interfacename>MessageChannel</interfacename> interface is defined as follows.
<programlisting language="java"><![CDATA[public interface MessageChannel {
String getName();
boolean send(Message message);
boolean send(Message message, long timeout);
}]]></programlisting>
When sending a message, the return value will be <emphasis>true</emphasis> if the message is sent successfully.
If the send call times out or is interrupted, then it will return <emphasis>false</emphasis>.
</para>
<section id="channel-interfaces-pollablechannel">
<title>PollableChannel</title>
<para>
Since Message Channels may or may not buffer Messages (as discussed in the overview), there are two
sub-interfaces defining the buffering (pollable) and non-buffering (subscribable) channel behavior. Here is the
definition of <interfacename>PollableChannel</interfacename>.
<programlisting language="java">public interface PollableChannel extends MessageChannel {
Message&lt;?&gt; receive();
Message&lt;?&gt; receive(long timeout);
List&lt;Message&lt;?&gt;&gt; clear();
List&lt;Message&lt;?&gt;&gt; purge(MessageSelector selector);
}</programlisting>
Similar to the send methods, when receiving a message, the return value will be <emphasis>null</emphasis> in the
case of a timeout or interrupt.
</para>
</section>
<section id="channel-interfaces-subscribablechannel">
<title>SubscribableChannel</title>
<para>
The <interfacename>SubscribableChannel</interfacename> base interface is implemented by channels that send
Messages directly to their subscribed <interfacename>MessageHandler</interfacename>s. Therefore, they do not
provide receive methods for polling, but instead define methods for managing those subscribers:
<programlisting language="java">public interface SubscribableChannel extends MessageChannel {
boolean subscribe(MessageHandler handler);
boolean unsubscribe(MessageHandler handler);
}</programlisting>
</para>
</section>
</section>
<section id="channel-implementations">
<title>Message Channel Implementations</title>
<para>
Spring Integration provides several different Message Channel implementations. Each is briefly described in the
sections below.
</para>
<section id="channel-implementations-publishsubscribechannel">
<title>PublishSubscribeChannel</title>
<para>
The <classname>PublishSubscribeChannel</classname> implementation broadcasts any Message
sent to it to all of its subscribed handlers. This is most often used for sending
<emphasis>Event Messages</emphasis> whose primary role is notification as opposed to
<emphasis>Document Messages</emphasis> which are generally intended to be processed by
a single handler. Note that the <classname>PublishSubscribeChannel</classname> is
intended for sending only. Since it broadcasts to its subscribers directly when its
<methodname>send(Message)</methodname> method is invoked, consumers cannot poll for
Messages (it does not implement <interfacename>PollableChannel</interfacename> and
therefore has no <methodname>receive()</methodname> method). Instead, any subscriber
must be a <interfacename>MessageHandler</interfacename> itself, and the subscriber's
<methodname>handleMessage(Message)</methodname> method will be invoked in turn.
</para>
</section>
<section id="channel-implementations-queuechannel">
<title>QueueChannel</title>
<para>
The <classname>QueueChannel</classname> implementation wraps a queue. Unlike the
<classname>PublishSubscribeChannel</classname>, the <classname>QueueChannel</classname> has point-to-point
semantics. In other words, even if the channel has multiple consumers, only one of them should receive any
Message sent to that channel. It provides a default no-argument constructor (providing an essentially unbounded
capacity of <code>Integer.MAX_VALUE</code>) as well as a constructor that accepts the queue capacity:
<programlisting language="java">public QueueChannel(int capacity)</programlisting>
A channel that has not reached its capacity limit will store messages in its internal queue, and the
<methodname>send()</methodname> method will return immediately even if no receiver is ready to handle the
message. If the queue has reached capacity, then the sender will block until room is available. Or, if using
the send call that accepts a timeout, it will block until either room is available or the timeout period
elapses, whichever occurs first. Likewise, a receive call will return immediately if a message is available
on the queue, but if the queue is empty, then a receive call may block until either a message is available
or the timeout elapses. In either case, it is possible to force an immediate return regardless of the
queue's state by passing a timeout value of 0. Note however, that calls to the no-arg versions of
<methodname>send()</methodname> and <methodname>receive()</methodname> will block indefinitely.
</para>
</section>
<section id="channel-implementations-prioritychannel">
<title>PriorityChannel</title>
<para>
Whereas the <classname>QueueChannel</classname> enforces first-in/first-out (FIFO) ordering, the
<classname>PriorityChannel</classname> is an alternative implementation that allows for messages
to be ordered within the channel based upon a priority. By default the priority is determined by the
'<literal>priority</literal>' header within each message. However, for custom priority determination
logic, a comparator of type <classname>Comparator&lt;Message&lt;?&gt;&gt;</classname> can be provided
to the <classname>PriorityChannel</classname>'s constructor.
</para>
</section>
<section id="channel-implementations-rendezvouschannel">
<title>RendezvousChannel</title>
<para>
The <classname>RendezvousChannel</classname> enables a "direct-handoff" scenario where a sender will block
until another party invokes the channel's <methodname>receive()</methodname> method or vice-versa. Internally,
this implementation is quite similar to the <classname>QueueChannel</classname> except that it uses a
<classname>SynchronousQueue</classname> (a zero-capacity implementation of
<interfacename>BlockingQueue</interfacename>). This works well in situations where the sender and receiver are
operating in different threads but simply dropping the message in a queue asynchronously is not appropriate.
In other words, with a <classname>RendezvousChannel</classname> at least the sender knows that some receiver
has accepted the message, whereas with a <classname>QueueChannel</classname>, the message would have been
stored to the internal queue and potentially never received.
</para>
<tip>
<para>
Keep in mind that all of these queue-based channels are storing messages in-memory only. When persistence
is required, you can either invoke a database operation within a handler or use Spring Integration's
support for JMS-based Channel Adapters. The latter option allows you to take advantage of any JMS provider's
implementation for message persistence, and it will be discussed in <xref linkend="jms"/>. However, when
buffering in a queue is not necessary, the simplest approach is to rely upon the
<classname>DirectChannel</classname> discussed next.
</para>
</tip>
<para>
The <classname>RendezvousChannel</classname> is also useful for implementing request-reply
operations. The sender can create a temporary, anonymous instance of <classname>RendezvousChannel</classname>
which it then sets as the 'replyChannel' header when building a Message. After sending that Message, the sender
can immediately call receive (optionally providing a timeout value) in order to block while waiting for a reply
Message. This is very similar to the implementation used internally by many of Spring Integration's
request-reply components.
</para>
</section>
<section id="channel-implementations-directchannel">
<title>DirectChannel</title>
<para>
The <classname>DirectChannel</classname> has point-to-point semantics but otherwise is more similar to the
<classname>PublishSubscribeChannel</classname> than any of the queue-based channel implementations described
above. It implements the <interfacename>SubscribableChannel</interfacename> interface instead of the
<interfacename>PollableChannel</interfacename> interface, so it dispatches Messages directly to a subscriber.
As a point-to-point channel, however, it differs from the <classname>PublishSubscribeChannel</classname> in
that it will only send each Message to a <emphasis>single</emphasis> subscribed
<classname>MessageHandler</classname>.
</para>
<para>
In addition to being the simplest point-to-point channel option, one of its most important features is that
it enables a single thread to perform the operations on "both sides" of the channel. For example, if a handler
is subscribed to a <classname>DirectChannel</classname>, then sending a Message to that channel will trigger
invocation of that handler's <methodname>handleMessage(Message)</methodname> method <emphasis>directly in the
sender's thread</emphasis>, before the send() method invocation can return.
</para>
<para>
The key motivation for providing a channel implementation with this behavior is to support transactions that
must span across the channel while still benefiting from the abstraction and loose coupling that the channel
provides. If the send call is invoked within the scope of a transaction, then the outcome of the handler's
invocation (e.g. updating a database record) will play a role in determining the ultimate result of that
transaction (commit or rollback).
<note>
Since the <classname>DirectChannel</classname> is the simplest option and does not add any additional
overhead that would be required for scheduling and managing the threads of a poller, it is the default
channel type within Spring Integration. The general idea is to define the channels for an application and
then to consider which of those need to provide buffering or to throttle input, and then modify those to
be queue-based <interfacename>PollableChannels</interfacename>. Likewise, if a channel needs to broadcast
messages, it should not be a <classname>DirectChannel</classname> but rather a
<classname>PublishSubscribeChannel</classname>. Below you will see how each of these can be configured.
</note>
</para>
<para>
The <classname>DirectChannel</classname> internally delegates to a Message Dispatcher to invoke its
subscribed Message Handlers, and that dispatcher can have a load-balancing strategy. The load-balancer
determines how invocations will be ordered in the case that there are multiple handlers subscribed to the
same channel. When using the namespace support described below, the default strategy is
"round-robin" which essentially load-balances across the handlers in rotation.
<note>
The "round-robin" strategy is currently the only implementation available out-of-the-box in Spring
Integration. Other strategy implementations may be added in future versions.
</note>
</para>
<para>
The load-balancer also works in combination with a boolean <emphasis>failover</emphasis> property.
If the "failover" value is true (the default), then the dispatcher will fall back to any subsequent
handlers as necessary when preceding handlers throw Exceptions. The order is determined by an optional
order value defined on the handlers themselves or, if no such value exists, the order in which the
handlers are subscribed.
</para>
<para>
If a certain situation requires that the dispatcher always try to invoke the first handler, then
fallback in the same fixed order sequence every time an error occurs, no load-balancing strategy should
be provided. In other words, the dispatcher still supports the failover boolean property even when no
load-balancing is enabled. Without load-balancing, however, the invocation of handlers will always begin
with the first according to their order. For example, this approach works well when there is a clear
definition of primary, secondary, tertiary, and so on. When using the namespace support, the "order"
attribute on any endpoint will determine that order.
</para>
<note>
Keep in mind that load-balancing and failover only apply when a channel has more than one
subscribed Message Handler. When using the namespace support, this means that more than one
endpoint shares the same channel reference in the "input-channel" attribute.
</note>
</section>
<section id="executor-channel">
<title>ExecutorChannel</title>
<para>
The <classname>ExecutorChannel</classname> is a point-to-point channel that supports
the same dispatcher configuration as <classname>DirectChannel</classname> (load-balancing strategy
and the failover boolean property). The key difference between these two dispatching channel types
is that the <classname>ExecutorChannel</classname> delegates to an instance of
<interfacename>TaskExecutor</interfacename> to perform the dispatch. This means that the send method
typically will not block, but it also means that the handler invocation may not occur in the sender's
thread. It therefore <emphasis>does not support transactions spanning the sender and receiving
handler</emphasis>.
<tip>
Note that there are occasions where the sender may block. For example, when using a
TaskExecutor with a rejection-policy that throttles back on the client (such as the
<code>ThreadPoolExecutor.CallerRunsPolicy</code>), the sender's thread will execute
the method directly anytime the thread pool is at its maximum capacity and the
executor's work queue is full. Since that situation would only occur in a non-predictable
way, that obviously cannot be relied upon for transactions.
</tip>
</para>
</section>
<section id="channel-implementations-threadlocalchannel">
<title>ThreadLocalChannel</title>
<para>
The final channel implementation type is <classname>ThreadLocalChannel</classname>. This channel also delegates
to a queue internally, but the queue is bound to the current thread. That way the thread that sends to the
channel will later be able to receive those same Messages, but no other thread would be able to access them.
While probably the least common type of channel, this is useful for situations where
<classname>DirectChannels</classname> are being used to enforce a single thread of operation but any reply
Messages should be sent to a "terminal" channel. If that terminal channel is a
<classname>ThreadLocalChannel</classname>, the original sending thread can collect its replies from it.
</para>
</section>
</section>
<section id="channel-interceptors">
<title>Channel Interceptors</title>
<para>
One of the advantages of a messaging architecture is the ability to provide common behavior and capture
meaningful information about the messages passing through the system in a non-invasive way. Since the
<interfacename>Messages</interfacename> are being sent to and received from
<interfacename>MessageChannels</interfacename>, those channels provide an opportunity for intercepting
the send and receive operations. The <interfacename>ChannelInterceptor</interfacename> strategy interface
provides methods for each of those operations:
<programlisting language="java"><![CDATA[public interface ChannelInterceptor {
Message<?> preSend(Message<?> message, MessageChannel channel);
void postSend(Message<?> message, MessageChannel channel, boolean sent);
boolean preReceive(MessageChannel channel);
Message<?> postReceive(Message<?> message, MessageChannel channel);
}]]></programlisting>
After implementing the interface, registering the interceptor with a channel is just a matter of calling:
<programlisting language="java">channel.addInterceptor(someChannelInterceptor);</programlisting>
The methods that return a Message instance can be used for transforming the Message or can return 'null'
to prevent further processing (of course, any of the methods can throw a RuntimeException). Also, the
<methodname>preReceive</methodname> method can return '<literal>false</literal>' to prevent the receive
operation from proceeding.
<note>
Keep in mind that <methodname>receive()</methodname> calls are only relevant for
<interfacename>PollableChannels</interfacename>. In fact the
<interfacename>SubscribableChannel</interfacename> interface does not even define a
<methodname>receive()</methodname> method. The reason for this is that when a Message is sent to a
<interfacename>SubscribableChannel</interfacename> it will be sent directly to one or more subscribers
depending on the type of channel (e.g. a PublishSubscribeChannel sends to all of its subscribers). Therefore,
the <methodname>preReceive(..)</methodname> and <methodname>postReceive(..)</methodname> interceptor methods
are only invoked when the interceptor is applied to a <interfacename>PollableChannel</interfacename>.
</note>
Spring Integration also provides an implementation of the
<ulink url="http://eaipatterns.com/WireTap.html">Wire Tap</ulink> pattern.
It is a simple interceptor that sends the Message to another channel without otherwise altering the
existing flow. It can be very useful for debugging and monitoring. An example is shown in
<xref linkend="channel-wiretap"/>.
</para>
<para>
Because it is rarely necessary to implement all of the interceptor methods, a
<classname>ChannelInterceptorAdapter</classname> class is also available for sub-classing. It provides no-op
methods (the <literal>void</literal> method is empty, the <classname>Message</classname> returning methods
return the Message as-is, and the <literal>boolean</literal> method returns <literal>true</literal>).
Therefore, it is often easiest to extend that class and just implement the method(s) that you need as in the
following example.
<programlisting language="java"><![CDATA[public class CountingChannelInterceptor extends ChannelInterceptorAdapter {
private final AtomicInteger sendCount = new AtomicInteger();
@Override
public Message<?> preSend(Message<?> message, MessageChannel channel) {
sendCount.incrementAndGet();
return message;
}
}]]></programlisting>
<tip>
The order of invocation for the interceptor methods depends on the type of channel. As described above,
the queue-based channels are the only ones where the receive method is intercepted in the first place.
Additionally, the relationship between send and receive interception depends on the timing of separate
sender and receiver threads. For example, if a receiver is already blocked while waiting for a message
the order could be: preSend, preReceive, postReceive, postSend. However, if a receiver polls after the
sender has placed a message on the channel and already returned, the order would be: preSend, postSend,
(some-time-elapses) preReceive, postReceive. The time that elapses in such a case depends on a number
of factors and is therefore generally unpredictable (in fact, the receive may never happen!).
Obviously, the type of queue also plays a role (e.g. rendezvous vs. priority). The bottom line is that
you cannot rely on the order beyond the fact that preSend will precede postSend and preReceive will
precede postReceive.
</tip>
</para>
</section>
<section id="channel-template">
<title>MessageChannelTemplate</title>
<para>
As you will see when the endpoints and their various configuration options are introduced, Spring Integration
provides a foundation for messaging components that enables non-invasive invocation of your application code
<emphasis>from the messaging system</emphasis>. However, sometimes it is necessary to invoke the messaging system
<emphasis>from your application code</emphasis>. For convenience when implementing such use-cases, Spring
Integration provides a <classname>MessageChannelTemplate</classname> that supports a variety of operations across
the Message Channels, including request/reply scenarios. For example, it is possible to send a request
and wait for a reply.
<programlisting language="java">MessageChannelTemplate template = new MessageChannelTemplate();
Message reply = template.sendAndReceive(new StringMessage("test"), someChannel);</programlisting>
In that example, a temporary anonymous channel would be created internally by the template. The
'sendTimeout' and 'receiveTimeout' properties may also be set on the template, and other exchange
types are also supported.
<programlisting language="java"><![CDATA[public boolean send(final Message<?> message, final MessageChannel channel) { ... }
public Message<?> sendAndReceive(final Message<?> request, final MessageChannel channel) { .. }
public Message<?> receive(final PollableChannel<?> channel) { ... }]]></programlisting>
</para>
<note>
<para>
A less invasive approach that allows you to invoke simple interfaces with payload and/or header
values instead of Message instances is described in <xref linkend="gateway-proxy"/>.
</para>
</note>
</section>
<section id="channel-configuration">
<title>Configuring Message Channels</title>
<para>
To create a Message Channel instance, you can use the 'channel' element:
<programlisting language="xml">&lt;channel id="exampleChannel"/&gt;</programlisting>
</para>
<para>
The default channel type is <emphasis>Point to Point</emphasis>. To create a
<emphasis>Publish Subscribe</emphasis> channel, use the "publish-subscribe-channel" element:
<programlisting language="xml">&lt;publish-subscribe-channel id="exampleChannel"/&gt;</programlisting>
</para>
<para>
To create a <ulink url="http://www.eaipatterns.com/DatatypeChannel.html">Datatype Channel</ulink> that only
accepts messages containing a certain payload type, provide the fully-qualified class name in the
channel element's <literal>datatype</literal> attribute:
<programlisting language="xml"><![CDATA[<channel id="numberChannel" datatype="java.lang.Number"/>]]></programlisting>
Note that the type check passes for any type that is <emphasis>assignable</emphasis> to the channel's
datatype. In other words, the "numberChannel" above would accept messages whose payload is
<classname>java.lang.Integer</classname> or <classname>java.lang.Double</classname>. Multiple types can be
provided as a comma-delimited list:
<programlisting language="xml"><![CDATA[<channel id="stringOrNumberChannel" datatype="java.lang.String,java.lang.Number"/>]]></programlisting>
</para>
<para>
When using the "channel" element without any sub-elements, it will create a <classname>DirectChannel</classname>
instance (a <interfacename>SubscribableChannel</interfacename>).
</para>
<para>
However, you can alternatively provide a variety of "queue" sub-elements to create any of
the pollable channel types (as described in
<xref linkend="channel-implementations"/>). Examples of each are shown below.
</para>
<section id="channel-configuration-directchannel">
<title>DirectChannel Configuration</title>
<para>
As mentioned above, <classname>DirectChannel</classname> is the default type.
<programlisting language="xml"><![CDATA[<channel id="directChannel"/>]]></programlisting>
</para>
<para>
A default channel will have a <emphasis>round-robin</emphasis> load-balancer and will also have
failover enabled (See the discussion in <xref linkend="channel-implementations-directchannel"/>
for more detail). To disable one or both of these, add a &lt;dispatcher/&gt; sub-element and
configure the attributes:
<programlisting language="xml"><![CDATA[<channel id="failFastChannel">
<dispatcher failover="false"/>
</channel>
<channel id="channelWithFixedOrderSequenceFailover">
<dispatcher load-balancer="none"/>
</channel>
]]></programlisting>
</para>
</section>
<section id="channel-configuration-queuechannel">
<title>QueueChannel Configuration</title>
<para>
To create a <classname>QueueChannel</classname>, use the "queue" sub-element.
You may specify the channel's capacity:
<programlisting language="xml">&lt;channel id="queueChannel"&gt;
&lt;queue capacity="25"/&gt;
&lt;/channel&gt;</programlisting>
<note>
If you do not provide a value for the 'capacity' attribute on this &lt;queue/&gt; sub-element,
the resulting queue will be unbounded. To avoid issues such as OutOfMemoryErrors, it is highly
recommended to set an explicit value for a bounded queue.
</note>
</para>
</section>
<section id="channel-configuration-pubsubchannel">
<title>PublishSubscribeChannel Configuration</title>
<para>
To create a <classname>PublishSubscribeChannel</classname>, use the "publish-subscribe-channel" element.
When using this element, you can also specify the "task-executor" used for publishing
Messages (if none is specified it simply publishes in the sender's thread):
<programlisting language="xml">&lt;publish-subscribe-channel id="pubsubChannel" task-executor="someExecutor"/&gt;</programlisting>
If you are providing a <emphasis>Resequencer</emphasis> or <emphasis>Aggregator</emphasis> downstream
from a <classname>PublishSubscribeChannel</classname>, then you can set the 'apply-sequence' property
on the channel to <code>true</code>. That will indicate that the channel should set the sequence-size
and sequence-number Message headers as well as the correlation id prior to passing the Messages along.
For example, if there are 5 subscribers, the sequence-size would be set to 5, and the Messages would
have sequence-number header values ranging from 1 to 5.
<programlisting language="xml">&lt;publish-subscribe-channel id="pubsubChannel" apply-sequence="true"/&gt;</programlisting>
<note>
The 'apply-sequence' value is <code>false</code> by default so that a Publish Subscribe Channel
can send the exact same Message instances to multiple outbound channels. Since Spring Integration
enforces immutability of the payload and header references, the channel creates new Message
instances with the same payload reference but different header values when the flag is set to
<code>true</code>.
</note>
</para>
</section>
<section id="channel-configuration-executorchannel">
<title>ExecutorChannel</title>
<para>
To create an <classname>ExecutorChannel</classname>, add the &lt;dispatcher&gt; sub-element along
with a 'task-executor' attribute. Its value can reference any <interfacename>TaskExecutor</interfacename>
within the context. For example, this enables configuration of a thread-pool for dispatching messages
to subscribed handlers. As mentioned above, this does break the "single-threaded" execution context
between sender and receiver so that any active transaction context will not be shared by the invocation
of the handler (i.e. the handler may throw an Exception, but the send invocation has already returned
successfully).
<programlisting language="xml"><![CDATA[<channel id="executorChannel">
<dispatcher task-executor="someExecutor"/>
</channel>]]></programlisting>
</para>
<note>
The "load-balancer" and "failover" options are also both available on the dispatcher sub-element
as described above in <xref linkend="channel-configuration-directchannel"/>. The same defaults
apply as well. So, the channel will have a round-robin load-balancing strategy with failover
enabled unless explicit configuration is provided for one or both of those attributes.
<programlisting language="xml"><![CDATA[<channel id="executorChannelWithoutFailover">
<dispatcher task-executor="someExecutor" failover="false"/>
</channel>]]></programlisting>
</note>
</section>
<section id="channel-configuration-prioritychannel">
<title>PriorityChannel Configuration</title>
<para>
To create a <classname>PriorityChannel</classname>, use the "priority-queue" sub-element:
<programlisting language="xml"><![CDATA[<channel id="priorityChannel">
<priority-queue capacity="20"/>
</channel>]]></programlisting>
By default, the channel will consult the <classname>MessagePriority</classname> header of the
message. However, a custom <interfacename>Comparator</interfacename> reference may be
provided instead. Also, note that the <classname>PriorityChannel</classname> (like the other types)
does support the "datatype" attribute. As with the QueueChannel, it also supports a "capacity" attribute.
The following example demonstrates all of these:
<programlisting language="xml"><![CDATA[<channel id="priorityChannel" datatype="example.Widget">
<priority-queue comparator="widgetComparator"
capacity="10"/>
</channel>
]]></programlisting>
</para>
</section>
<section id="channel-configuration-rendezvouschannel">
<title>RendezvousChannel Configuration</title>
<para>
A <classname>RendezvousChannel</classname> is created when the queue sub-element is
a &lt;rendezvous-queue&gt;. It does not provide any additional configuration options to
those described above, and its queue does not accept any capacity value since it is a
0-capacity direct handoff queue.
<programlisting language="xml"><![CDATA[<channel id="rendezvousChannel"/>
<rendezvous-queue/>
</channel>
]]></programlisting>
</para>
</section>
<section id="channel-configuration-threadlocalchannel">
<title>ThreadLocalChannel Configuration</title>
<para>
The <classname>ThreadLocalChannel</classname> does not provide any additional configuration options.
<programlisting language="xml"><![CDATA[<thread-local-channel id="threadLocalChannel"/>]]></programlisting>
</para>
</section>
<section id="channel-configuration-interceptors">
<title>Channel Interceptor Configuration</title>
<para>
Message channels may also have interceptors as described in <xref linkend="channel-interceptors"/>. The
&lt;interceptors&gt; sub-element can be added within &lt;channel&gt; (or the more specific element
types). Provide the "ref" attribute to reference any Spring-managed object that implements the
<interfacename>ChannelInterceptor</interfacename> interface:
<programlisting language="xml"><![CDATA[<channel id="exampleChannel">
]]><emphasis><![CDATA[<interceptors>
<ref bean="trafficMonitoringInterceptor"/>
</interceptors>]]></emphasis><![CDATA[
</channel>]]></programlisting>
In general, it is a good idea to define the interceptor implementations in a separate location since they
usually provide common behavior that can be reused across multiple channels.
</para>
</section>
<section id="global-channel-configuration-interceptors">
<title>Global Channel Interceptor Configuration</title>
<para>
Channel Interceptors allow you for a clean and concise way of applying cross-cutting behavior per individual channel.
But what if the same behavior should be applied on multiple channels, configuring the same set of interceptors for
each channel <emphasis>would not be</emphasis> the most efficient way. The better way would be to configure interceptors globally and apply
them on multiple channels in one shot. Spring Integration provides capabilities to configure <emphasis>Global Interceptor Chains</emphasis>
and apply them on multiple channels.
Look at the example below:
<programlisting language="xml"><![CDATA[<int:channel-interceptor-chain channel-name-pattern="input*, bar*, foo" order="3">
<bean class="foo.barSampleInterceptor"/>
<ref bean="someOtherInterceptor"/>
</int:channel-interceptor-chain>]]></programlisting>
&lt;channel-interceptor-chain&gt; element will assemble the chain of interceptors and will apply them on all the
channels defined in the &lt;channel-name-patter&gt; attribute. In the above case the two interceptors that are defined
within the chain are going to be applied on 'foo' channel and all other channels that begin with 'bar' and 'input'.
The &lt;order&gt; attribute allows you to manage the place where this interceptor chain will be injected.
For example, channel 'inputChannel' could have individual interceptors configured locally (see below):
<programlisting language="xml"><![CDATA[<int:channel id="inputChannel"> 
<int:interceptors>
<int:wire-tap channel="logger"/> 
</int:interceptors>
</int:channel>]]></programlisting>
The reasonable question would be where interceptors defined by <emphasis>channel-interceptor-cahin</emphasis> should be injected
in relation to the existing one(s) (configured locally or through other global chains)? Current implementation provides
a very simple and clever mechanism of handling this. Positive number in the <emphasis>order</emphasis> attribute will ensure interceptor injection
after existing interceptors and negative number will ensure that such interceptors injected before.
This means that in the above example interceptors configured in global interceptor chain would be injected after
'wire-tap' interceptor configured locally. If there was another global chain with matching <emphasis>channel-name-pattern</emphasis> the
order between the interceptors defined in two chains would be determined based on who's got the higher or lower
value in <emphasis>order</emphasis> attribute.
</para>
</section>
<section id="channel-wiretap">
<title>Wire Tap</title>
<para>
As mentioned above, Spring Integration provides a simple <emphasis>Wire Tap</emphasis> interceptor out of
the box. You can configure a <emphasis>Wire Tap</emphasis> on any channel within an 'interceptors' element.
This is especially useful for debugging, and can be used in conjunction with Spring Integration's logging
Channel Adapter as follows: <programlisting language="xml"><![CDATA[ <channel id="in">
<interceptors>
<wire-tap channel="logger"/>
</interceptors>
</channel>
<logging-channel-adapter id="logger" level="DEBUG"/>]]></programlisting>
<tip>
The 'logging-channel-adapter' also accepts a boolean attribute: <emphasis>'log-full-message'</emphasis>.
That is <emphasis>false</emphasis> by default so that only the payload is logged. Setting that to
<emphasis>true</emphasis> enables logging of all headers in addition to the payload.
</tip>
</para>
</section>
<note>
<para>
If namespace support is enabled, there are also two special channels defined within the context by default:
<code>errorChannel</code> and <code>nullChannel</code>. The 'nullChannel' acts like <code>/dev/null</code>,
simply logging any Message sent to it at DEBUG level and returning immediately. Any time you face channel
resolution errors for a reply that you don't care about, you can set the affected component's 'output-channel'
to reference 'nullChannel' (the name 'nullChannel' is reserved within the context). The 'errorChannel' is
used internally for sending error messages, and it can be overridden with a custom configuration. It is
discussed in greater detail in <xref linkend="namespace-errorhandler"/>.
</para>
</note>
</section>
</chapter>

502
spring-integration-reference/src/configuration.xml
View File

@@ -1,502 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<appendix id="configuration">
<title>Configuration</title>
<section id="configuration-introduction">
<title>Introduction</title>
<para>
Spring Integration offers a number of configuration options. Which option you choose depends upon your particular
needs and at what level you prefer to work. As with the Spring framework in general, it is also possible to mix
and match the various techniques according to the particular problem at hand. For example, you may choose the
XSD-based namespace for the majority of configuration combined with a handful of objects that are configured with
annotations. As much as possible, the two provide consistent naming. XML elements defined by the XSD schema will
match the names of annotations, and the attributes of those XML elements will match the names of annotation
properties. Direct usage of the API is of course always an option, but we expect that most users will choose one
of the higher-level options, or a combination of the namespace-based and annotation-driven configuration.
</para>
</section>
<section id="configuration-namespace">
<title>Namespace Support</title>
<para>
Spring Integration components can be configured with XML elements that map directly to the terminology and
concepts of enterprise integration. In many cases, the element names match those of the
<ulink url="http://www.eaipatterns.com">Enterprise Integration Patterns</ulink>.
</para>
<para>
To enable Spring Integration's core namespace support within your Spring configuration files, add the following
namespace reference and schema mapping in your top-level 'beans' element:
<programlisting language="xml"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
]]><emphasis>xmlns:integration="http://www.springframework.org/schema/integration"</emphasis><![CDATA[
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
]]><emphasis>http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration-1.0.xsd"</emphasis>&gt;</programlisting>
</para>
<para>
You can choose any name after "xmlns:"; <emphasis>integration</emphasis> is used here for clarity, but you might
prefer a shorter abbreviation. Of course if you are using an XML-editor or IDE support, then the availability of
auto-completion may convince you to keep the longer name for clarity. Alternatively, you can create configuration
files that use the Spring Integration schema as the primary namespace:
<programlisting language="xml"><emphasis>&lt;beans:beans xmlns="http://www.springframework.org/schema/integration"</emphasis><![CDATA[
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
]]><emphasis>xmlns:beans="http://www.springframework.org/schema/beans"</emphasis><![CDATA[
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration-1.0.xsd">]]></programlisting>
</para>
<para>
When using this alternative, no prefix is necessary for the Spring Integration elements. On the other hand, if
you want to define a generic Spring "bean" within the same configuration file, then a prefix would be required
for the bean element (&lt;beans:bean ... /&gt;). Since it is generally a good idea to modularize the
configuration files themselves based on responsibility and/or architectural layer, you may find it appropriate to
use the latter approach in the integration-focused configuration files, since generic beans are seldom necessary
within those same files. For purposes of this documentation, we will assume the "integration" namespace is
primary.
</para>
<para>
Many other namespaces are provided within the Spring Integration distribution. In fact, each adapter type (JMS,
File, etc.) that provides namespace support defines its elements within a separate schema. In order to use these
elements, simply add the necessary namespaces with an "xmlns" entry and the corresponding "schemaLocation" mapping.
For example, the following root element shows several of these namespace declarations:
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:integration="http://www.springframework.org/schema/integration"
xmlns:file="http://www.springframework.org/schema/integration/file"
xmlns:jms="http://www.springframework.org/schema/integration/jms"
xmlns:mail="http://www.springframework.org/schema/integration/mail"
xmlns:rmi="http://www.springframework.org/schema/integration/rmi"
xmlns:ws="http://www.springframework.org/schema/integration/ws"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration-1.0.xsd
http://www.springframework.org/schema/integration/file
http://www.springframework.org/schema/integration/file/spring-integration-file-1.0.xsd
http://www.springframework.org/schema/integration/jms
http://www.springframework.org/schema/integration/jms/spring-integration-jms-1.0.xsd
http://www.springframework.org/schema/integration/mail
http://www.springframework.org/schema/integration/mail/spring-integration-mail-1.0.xsd
http://www.springframework.org/schema/integration/rmi
http://www.springframework.org/schema/integration/rmi/spring-integration-rmi-1.0.xsd
http://www.springframework.org/schema/integration/ws
http://www.springframework.org/schema/integration/ws/spring-integration-ws-1.0.xsd">
...
</beans>]]></programlisting>
The reference manual provides specific examples of the various elements in their corresponding chapters. Here, the
main thing to recognize is the consistency of the naming for each namespace URI and schema location.
</para>
</section>
<section id="namespace-taskscheduler">
<title>Configuring the Task Scheduler</title>
<para>
In Spring Integration, the ApplicationContext plays the central role of a Message Bus, and there are only a
couple configuration options to be aware of. First, you may want to control the central TaskScheduler instance.
You can do so by providing a single bean with the name "taskScheduler". This is also defined as a constant:
<programlisting><![CDATA[ IntegrationContextUtils.TASK_SCHEDULER_BEAN_NAME ]]></programlisting>
By default Spring Integration uses the <classname>SimpleTaskScheduler</classname> implementation. That in turn
just delegates to any instance of Spring's <interfacename>TaskExecutor</interfacename> abstraction. Therefore,
it's rather trivial to supply your own configuration. The "taskScheduler" bean is then responsible for managing
all pollers. The TaskScheduler will startup automatically by default. If you provide your own instance of
SimpleTaskScheduler however, you can set the 'autoStartup' property to <emphasis>false</emphasis> instead.
</para>
<para>
When Polling Consumers provide an explicit task-executor reference in their configuration, the invocation of
the handler methods will happen within that executor's thread pool and not the main scheduler pool. However,
when no task-executor is provided for an endpoint's poller, it will be invoked by one of the main scheduler's
threads.
<note>
An endpoint is a <emphasis>Polling Consumer</emphasis> if its input channel is one of the queue-based
(i.e. pollable) channels. On the other hand, <emphasis>Event Driven Consumers</emphasis> are those whose
input channels have dispatchers instead of queues (i.e. they are subscribable). Such endpoints have no
poller configuration since their handlers will be invoked directly.
</note>
<para>
The next section will describe what happens if Exceptions occur within the asynchronous invocations.
</para>
</para>
</section>
<section id="namespace-errorhandler">
<title>Error Handling</title>
<para>
As described in the overview at the very beginning of this manual, one of the main motivations behind a
Message-oriented framework like Spring Integration is to promote loose-coupling between components. The
Message Channel plays an important role in that producers and consumers do not have to know about each
other. However, the advantages also have some drawbacks. Some things become more complicated in a very
loosely coupled environment, and one example is error handling.
</para>
<para>
When sending a Message to a channel, the component that ultimately handles that Message may or may not
be operating within the same thread as the sender. If using a simple default DirectChannel (with the
&lt;channel&gt; element that has no &lt;queue&gt; sub-element and no 'task-executor' attribute), the
Message-handling will occur in the same thread as the Message-sending. In that case, if an Exception
is thrown, it can be caught by the sender (or it may propagate past the sender if it is an uncaught
RuntimeException). So far, everything is fine. This is the same behavior as an Exception-throwing
operation in a normal call stack. However, when adding the asynchronous aspect, things become much
more complicated. For instance, if the 'channel' element <emphasis>does</emphasis> provide a 'queue'
sub-element, then the component that handles the Message <emphasis>will</emphasis> be operating in a
different thread than the sender. The sender may have dropped the Message into the channel and moved
on to other things. There is no way for the Exception to be thrown directly back to that sender using
standard Exception throwing techniques. Instead, to handle errors for asynchronous processes requires
an asynchronous error-handling mechanism as well.
</para>
<para>
Spring Integration supports error handling for its components by publishing errors to a Message Channel.
Specifically, the Exception will become the payload of a Spring Integration Message. That Message will
then be sent to a Message Channel that is resolved in a way that is similar to the 'replyChannel'
resolution. First, if the request Message being handled at the time the Exception occurred contains
an 'errorChannel' header (the header name is defined in the constant: MessageHeaders.ERROR_CHANNEL),
the ErrorMessage will be sent to that channel. Otherwise, the error handler will send to a "global"
channel whose bean name is "errorChannel" (this is also defined as a constant:
IntegrationContextUtils.ERROR_CHANNEL_BEAN_NAME).
</para>
<para>
Whenever relying on Spring Integration's XML namespace support, a default "errorChannel" bean will be
created behind the scenes. However, you can just as easily define your own if you want to control the
settings.
<programlisting language="xml"><![CDATA[ <channel id="errorChannel">
<queue capacity="500"/>
</channel>]]></programlisting>
<note>
The default "errorChannel" is a PublishSubscribeChannel.
</note>
</para>
<para>
The most important thing to understand here is that the messaging-based error handling will only apply
to Exceptions that are thrown by a Spring Integration task that is executing within a TaskExecutor.
This does <emphasis>not</emphasis> apply to Exceptions thrown by a handler that is operating within
the same thread as the sender (e.g. through a DirectChannel as described above).
</para>
<note>
When Exceptions occur in a scheduled poller task's execution, those exceptions will be wrapped in
<classname>ErrorMessages</classname> and sent to the 'errorChannel' as well.
</note>
<para>
To enable global error handling, simply register a handler on that channel. For example, you can configure
Spring Integration's <classname>ErrorMessageExceptionTypeRouter</classname> as the handler of an endpoint
that is subscribed to the 'errorChannel'. That router can then spread the error messages across multiple
channels based on <classname>Exception</classname> type.
</para>
</section>
<section id="annotations">
<title>Annotation Support</title>
<para>
In addition to the XML namespace support for configuring Message Endpoints, it is also possible to use
annotations. First, Spring Integration provides the class-level <interfacename>@MessageEndpoint</interfacename>
as a <emphasis>stereotype</emphasis> annotation meaning that is itself annotated with Spring's @Component
annotation and therefore is recognized automatically as a bean definition when using Spring component-scanning.
</para>
<para>
Even more importantly are the various Method-level annotations that indicate the annotated method is capable of
handling a message. The following example demonstrates both:
<programlisting language="java">@MessageEndpoint
public class FooService {
@ServiceActivator
public void processMessage(Message message) {
...
}
}</programlisting>
</para>
<para>
Exactly what it means for the method to "handle" the Message depends on the particular annotation. The following
are available with Spring Integration, and the behavior of each is described in its own chapter or section within
this reference: @Transformer, @Router, @Splitter, @Aggregator, @ServiceActivator, and @ChannelAdapter.
</para>
<note>
The @MessageEndpoint is not required if using XML configuration in combination with annotations. If you want to
configure a POJO reference from the "ref" attribute of a &lt;service-activator/&gt; element, it is sufficient to
provide the method-level annotations. In that case, the annotation prevents ambiguity even when no "method"
attribute exists on the &lt;service-activator/&gt; element.
</note>
<para>
In most cases, the annotated handler method should not require the <classname>Message</classname> type as its
parameter. Instead, the method parameter type can match the message's payload type.
<programlisting language="java">public class FooService {
@ServiceActivator
public void bar(<emphasis>Foo foo</emphasis>) {
...
}
}</programlisting>
</para>
<para>
When the method parameter should be mapped from a value in the <classname>MessageHeaders</classname>, another
option is to use the parameter-level <interfacename>@Header</interfacename> annotation. In general, methods
annotated with the Spring Integration annotations can either accept the <classname>Message</classname> itself, the
message payload, or a header value (with @Header) as the parameter. In fact, the method can accept a combination,
such as:
<programlisting language="java">public class FooService {
@ServiceActivator
public void bar(String payload, @Header("x") int valueX, @Header("y") int valueY) {
...
}
}</programlisting>
There is also a @Headers annotation that provides all of the Message headers as a Map:
<programlisting language="java">public class FooService {
@ServiceActivator
public void bar(String payload, @Headers Map&lt;String, Object&gt; headerMap) {
...
}
}</programlisting>
<para>
A more powerful and flexible way to map Messages to method arguments is to use <interfacename>@MessageMapping</interfacename>
annotation which allows you to define expression via Spring 3.0 Expression Language support to help parse
the message payload and/or header and map the parsed values to method arguments.
</para>
<para>For example:</para>
<para>
<programlisting language="java">public void fromMessageToMethod(@MessageMapping("headers.day") String argA,
@MessageMapping("#this") Message message,
@MessageMapping("payload") Employee payloadArg,
@MessageMapping("payload.fname") String value,
@MessageMapping("headers") Map headers) { ... } </programlisting>
As you can see, the above method takes 5 arguments where:
<itemizedlist>
<listitem>
<para>First - will be mapped to the value of 'day' header</para>
</listitem>
<listitem>
<para>Second - will be mapped to the Message itself</para>
</listitem>
<listitem>
<para>Third - will be mapped to the Payload</para>
</listitem>
<listitem>
<para>Fourth - will be mapped to the 'fname' property of a Payload object</para>
</listitem>
<listitem>
<para>Fifth - will be mapped to MessageHeaders</para>
</listitem>
</itemizedlist>
</para>
<tip>
A Map-typed argument does not strictly require the use of the @Headers annotation. In other words
the following is also valid: <programlisting language="java">public void bar(String payload, Map&lt;String, Object&gt; headerMap)</programlisting>
However this can lead to unresolvable ambiguities if the payload is itself a Map. For that reason, we
highly recommend using the annotation whenever expecting the headers. For a much more detailed
description, see the javadoc for <classname>MethodParameterMessageMapper</classname>.
</tip>
</para>
<para>
For several of these annotations, when a Message-handling method returns a non-null value, the endpoint will
attempt to send a reply. This is consistent across both configuration options (namespace and annotations) in
that such an endpoint's output channel will be used if available, and the REPLY_CHANNEL message header value
will be used as a fallback.
</para>
<tip>
The combination of output channels on endpoints and the reply channel message header enables a pipeline approach
where multiple components have an output channel, and the final component simply allows the reply message to be
forwarded to the reply channel as specified in the original request message. In other words, the final component
depends on the information provided by the original sender and can dynamically support any number of clients as a
result. This is an example of <ulink url="http://eaipatterns.com/ReturnAddress.html">Return Address</ulink>.
</tip>
<para>
In addition to the examples shown here, these annotations also support inputChannel and outputChannel properties.
<programlisting language="java">public class FooService {
@ServiceActivator(inputChannel="input", outputChannel="output")
public void bar(String payload, @Headers Map&lt;String, Object&gt; headerMap) {
...
}
}</programlisting>
That provides a pure annotation-driven alternative to the XML configuration. However, it is generally recommended
to use XML for the endpoints, since it is easier to keep track of the overall configuration in a single, external
location (and besides the namespace-based XML configuration is not very verbose). If you do prefer to provide
channels with the annotations however, you just need to enable a SI Annotations BeanPostProcessor. The following element should
be added: <programlisting language="xml"><![CDATA[ <int:annotation-config/> ]]></programlisting>
<note>
When configuring the "inputChannel" and "outputChannel" with annotations, the "inputChannel"
<emphasis>must</emphasis> be a reference to a <interfacename>SubscribableChannel</interfacename> instance.
Otherwise, it would be necessary to also provide the full poller configuration via annotations, and those
settings (e.g. the trigger for scheduling the poller) should be externalized rather than hard-coded within
an annotation. If the input channel that you want to receive Messages from is indeed a
<interfacename>PollableChannel</interfacename> instance, one option to consider is the Messaging Bridge.
Spring Integration's "bridge" element can be used to connect a PollableChannel directly to a
SubscribableChannel. Then, the polling metadata is externally configured, but the annotation option is
still available. For more detail see <xref linkend="bridge"/>.
</note>
</para>
</section>
<section id="message-mapping-rules">
<title>Message Mapping rules and conventions</title>
<para>Spring Integration implements a flexible facility to map Messages to Methods and their arguments without
providing extra configuration by relying on some default rules as well as defining certain conventions.
</para>
<section id="sample-scenarios">
<title>Simple Scenarios</title>
<para>
<emphasis>Single un-annotated parameter (object or primitive) which is not a Map/Properties with non-void return type;</emphasis>
</para>
<programlisting language="java">public String foo(Object o);</programlisting>
<para>Details:</para>
<para>Input parameter is Message Payload. If parameter type is not compatible with Message Payload an
attempt will be made to convert it using Conversion Service provided by Spring 3.0. The return value
will be incorporated as a Payload of the returned Message</para>
<para>
<emphasis>Single un-annotated parameter (object or primitive) which is not a Map/Properties with Message return type;</emphasis>
</para>
<programlisting language="java">public Message  foo(Object o);</programlisting>
<para>Details:</para>
<para>Input parameter is Message Payload. If parameter type is not compatible with Message Payload an attempt
will be made to convert it using Conversion Service provided by Spring 3.0. The return value is a newly constructed
Message that will be sent to the next destination.</para>
<para>
<emphasis>Single parameter which is a Message or its subclass with arbitrary object/primitive return type; </emphasis>
</para>
<programlisting language="java">public int foo(Message  msg);</programlisting>
<para>Details:</para>
<para>Input parameter is Message itself. The return value will become a payload of the
Message that will be sent to the next destination.</para>
<para>
<emphasis>Single parameter which is a Message or its subclass with Message or its subclass as a return type;</emphasis>
</para>
<programlisting language="java">public Message foo(Message msg);</programlisting>
<para>Details:</para>
<para>Input parameter is Message itself. The return value is a newly constructed Message that will be sent to the next destination.</para>
<para>
<emphasis>Single parameter which is of type Map or Properties with Message as a return type;</emphasis>
</para>
<programlisting language="java">public Message foo(Map m);</programlisting>
<para>Details:</para>
<para>This one is a bit interesting. Although at first it might seem like an easy mapping straight to Message Headers,
the preference is always given to a Message Payload. This means that if Message Payload is of type Map, this input argument will
represent Message Payload. However if Message Payload is not of type Map, then no conversion via Conversion Service will be
attempted and the input argument will be mapped to Message Headers.</para>
<para>
<emphasis>Two parameters where one of them is arbitrary non-Map/Properties type object/primitive and another is Map/Properties type object (regardless of the return)</emphasis>
</para>
<programlisting language="java">public Message foo(Map h, &lt;T&gt; t);</programlisting>
<para>Details:</para>
<para>This combination contains two input parameters where one of them is of type Map. Naturally the non-Map parameters (regardless of the order) will
be mapped to a Message Payload and the Map/Properties (regardless of the order) will be mapped to  Message Headers giving you a nice POJO way
of interacting with Message structure.</para>
<para>
<emphasis>No parameters (regardless of the return)</emphasis>
</para>
<programlisting language="java">public String foo();</programlisting>
<para>Details:</para>
<para>This Message Handler method will be invoked based on the Message sent to the input channel this handler is hooked up to,
however no Message data will be mapped, thus making Message act as event/trigger to invoke such handlerThe output will be
mapped according to the rules above</para>
<para>
<emphasis>No parameters, void return</emphasis>
</para>
<programlisting language="java">public void foo();</programlisting>
<para>Details:</para>
<para>Same as above, but no output </para>
<para>
<emphasis>Annotation based mappings</emphasis>
</para>
<para>Annotation based mapping is the safest and least ambiguous approach to map Messages to Methods. There wil be many pointers to annotation
based mapping throughout this manual, however here are couple of examples:
</para>
<programlisting language="java">public String foo(@Payload String s,  @Header("foo") String b) </programlisting>
<para>Very simple and explicite way of mapping Messages to method. As you'll see later on without annotation this signature
would result in the ambiguous condition, however by explicitly mapping first argument to a Message Payload and second argument to
a value of the 'foo' Message Header we have avoided ambiguity.</para>
<programlisting language="java">public String foo(@Payload String s,  @RequestParam("foo") String b) </programlisting>
<para>Looks almost identical to the previous example, however @RequestMapping or any other non-SI mapping annotation
is irrelevant  and therefore will be ignored leaving the second parameter unmapped. And although the second parameters could
easily be mapped to a Payload, there can only be one Payload, therefore this method becomes ambiguous. </para>
<programlisting language="java">public String foo(String s,  @Header("foo") String b) </programlisting>
<para>The same as above. The only difference is that the first argument will be mapped to Message Payload implicitly.</para>
<programlisting language="java">public String foo(@Headers Map m,  @Header("foo")Map f, @Header("bar") String bar)</programlisting>
<para>Yet another signature that would definitely be treated as ambiguous because it has more then 2 arguments,
plus two of them are Maps, however with annotation-based mapping ambiguity is easily avoided. In this example
the first argument is mapped to all the Message Headers, while second and third argument map to the values of Message Headers 'foo' and 'bar'.</para>
</section>
<section id="complex-scenarios">
<title>Complex Scenarios</title>
<para><emphasis>Multiple parameters:</emphasis> </para>
<para>Multiple parameters could create a lot of ambiguity with regards to determining the appropriate mappings. The general advice is to annotate your method parameters with @Payload and/or @Header/@Headers
Below are some of the examples of ambiguous conditions which result in exception being raised.
</para>
<programlisting language="java">public String foo(String s, int i)</programlisting>
<para> - the two parameters are equal in weight, therefore no way to determine which one is a payload and what to do with another.</para>
<programlisting language="java">public String foo(String s, Map m, String b) </programlisting>
<para> - almost the same as above. Although Map could be easily mapped to Message Headers, there is no way to determine what to do with two Strings.</para>
<programlisting language="java">public String foo(Map m, Map f)</programlisting>
<para> - although one might argue that one Map could be mapped to Message Payload and another one to Message Headers, it would be unreasonable to rely on the order (e.g., first is Payload, second Headers)</para>
<para>
<tip>Basically any method signature with more then one method argument which is not (Map, &lt;T&gt;) and those parameters are not annotated will result in the ambiguous condition thus triggering an exception.</tip>
</para>
<para>
<emphasis>Multiple methods:</emphasis>
</para>
<para>Message Handlers with multiple methods are mapped based on the same rules that are described above, however some scenarios might still look confusing.</para>
<para><emphasis>Multiple methods (same or different name) with legal (mappable) signatures:</emphasis> </para>
<programlisting language="java">public class Foo{
public String foo(String str, Map m);
public String foo(Map m)
}</programlisting>
<para>As you can see, the Message could be mapped to either method. The first method would be invoked where Message Payload
could be mapped to 'str'  and Message Headers could be mapped to 'm'. The second method could easily also be a candidate where
only Message Headers are mapped to 'm'. To make meters worse both methods have the same name which at first might look very
ambiguous considering the following configuration:</para>
<programlisting language="xml"><![CDATA[<si:service-activator input-channel="input" output-channel="output" method="foo">
<bean class="org.bar.Foo"/>
</si:service-activator>]]></programlisting>
<para>At this point it would be important to understand Spring Integration mapping Conventions where at the very core,
mappings are based on Payload first and everything else next. In other words the method whose argument could be mapped
to a Payload will take precedence over all other methods.</para>
<para>On the other hand let's look at slightly different example:</para>
<programlisting language="java">public class Foo{
public String foo(String str, Map m);
public String foo(String str)
}</programlisting>
<para>If you look at it you can probably see a truly an ambiguous condition. In this example since both methods have signatures that
could be mapped to a Message Payload. They also have the same name. Such handler will trigger an exception.
However if method names were different you could influence the mapping with 'method' attribute (see below):</para>
<programlisting language="java">public class Foo{
public String foo(String str, Map m);
public String bar(String str)
}</programlisting>
<programlisting language="xml"><![CDATA[<si:service-activator input-channel="input" output-channel="output" method="bar">
<bean class="org.bar.Foo"/>
</si:service-activator>]]></programlisting>
<para>Now there is no ambiguity since the configuration explicitly maps to 'bar' method which has no name conflicts.</para>
</section>
</section>
</appendix>

62
spring-integration-reference/src/delayer.xml
View File

@@ -1,62 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="delayer">
<title>Delayer</title>
<section id="delayer-introduction">
<title>Introduction</title>
<para>
A Delayer is a simple endpoint that allows a Message flow to be delayed by a certain interval. When
a Message is delayed, the original sender will not block. Instead, the delayed Messages will be
scheduled with an instance of <interfacename>java.util.concurrent.ScheduledExecutorService</interfacename>
to be sent to the output channel after the delay has passed. This approach is scalable even for
rather long delays, since it does not result in a large number of blocked sender Threads. On the
contrary, in the typical case a thread pool will be used for the actual execution of releasing the
Messages. Below you will find several examples of configuring a Delayer.
</para>
</section>
<section id="delayer-namespace">
<title>The &lt;delayer&gt; Element</title>
<para>
The &lt;delayer&gt; element is used to delay the Message flow between two Message Channels.
As with the other endpoints, you can provide the "input-channel" and "output-channel" attributes,
but the delayer also requires at least the 'default-delay' attribute with the number of milliseconds
that each Message should be delayed.
<programlisting language="xml"><![CDATA[ <delayer input-channel="input" default-delay="3000" output-channel="output"/>]]></programlisting>
If you need per-Message determination of the delay, then you can also provide the name of a header
within the 'delay-header-name' attribute:
<programlisting language="xml"><![CDATA[ <delayer input-channel="input" output-channel="output"
default-delay="3000" delay-header-name="delay"/>]]></programlisting>
In the example above the 3 second delay would only apply in the case that the header value is
not present for a given inbound Message. If you only want to apply a delay to Messages that have
an explicit header value, then you can set the 'default-delay' to 0. For any Message that has a
delay of 0 (or less), the Message will be sent directly. In fact, if there is not a positive delay
value for a Message, it will be sent to the output channel on the calling Thread.
<tip>
The delay handler actually supports header values that represent an interval in milliseconds (any
Object whose <methodname>toString()</methodname> method produces a value that can be parsed into a
Long) as well as <classname>java.util.Date</classname> instances representing an absolute time.
In the former case, the milliseconds will be counted from the current time (e.g. a value of 5000
would delay the Message for at least 5 seconds from the time it is received by the Delayer). In
the latter case, with an actual Date instance, the Message will not be released until that Date
occurs. In either case, a value that equates to a non-positive delay, or a Date in the past, will
not result in any delay. Instead, it will be sent directly to the output channel in the original
sender's Thread.
</tip>
</para>
<para>
The delayer delegates to an instance of Spring's <interfacename>TaskScheduler</interfacename> abstraction.
The default scheduler is a <classname>ThreadPoolTaskScheduler</classname> instance with a pool size of 1.
If you want to delegate to a different scheduler, you can provide a reference through the delayer element's
'scheduler' attribute:
<programlisting language="xml"><![CDATA[ <delayer input-channel="input" output-channel="output"
default-delay="0" delay-header-name="delay"
scheduler="exampleTaskScheduler"/>
<task:scheduler id="exampleTaskScheduler" pool-size="3"/>]]></programlisting>
</para>
</section>
</chapter>

272
spring-integration-reference/src/endpoint.xml
View File

@@ -1,272 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="endpoint">
<title>Message Endpoints</title>
<para>
The first part of this chapter covers some background theory and reveals quite a bit about the underlying API
that drives Spring Integration's various messaging components. This information can be helpful if you want to
really understand what's going on behind the scenes. However, if you want to get up and running with the
simplified namespace-based configuration of the various elements, feel free to skip ahead to
<xref linkend="endpoint-namespace"/> for now.
</para>
<para>
As mentioned in the overview, Message Endpoints are responsible for connecting the various messaging components to
channels. Over the next several chapters, you will see a number of different components that consume Messages. Some
of these are also capable of sending reply Messages. Sending Messages is quite straightforward. As shown above in
<xref linkend="channel"/>, it's easy to <emphasis>send</emphasis> a Message to a Message Channel. However,
receiving is a bit more complicated. The main reason is that there are two types of consumers:
<ulink url="http://www.eaipatterns.com/PollingConsumer.html">Polling Consumers</ulink> and
<ulink url="http://www.eaipatterns.com/EventDrivenConsumer.html">Event Driven Consumers</ulink>.
</para>
<para>
Of the two, Event Driven Consumers are much simpler. Without any need to manage and schedule a separate poller
thread, they are essentially just listeners with a callback method. When connecting to one of Spring Integration's
subscribable Message Channels, this simple option works great. However, when connecting to a buffering, pollable
Message Channel, some component has to schedule and manage the polling thread(s). Spring Integration provides
two different endpoint implementations to accommodate these two types of consumers. Therefore, the consumers
themselves can simply implement the callback interface. When polling is required, the endpoint acts as a
"container" for the consumer instance. The benefit is similar to that of using a container for hosting
Message Driven Beans, but since these consumers are simply Spring-managed Objects running within an
ApplicationContext, it more closely resembles Spring's own MessageListener containers.
</para>
<section id="endpoint-handler">
<title>Message Handler</title>
<para>
Spring Integration's <interfacename>MessageHandler</interfacename> interface is implemented by many of the
components within the framework. In other words, this is not part of the public API, and a developer would not
typically implement <interfacename>MessageHandler</interfacename> directly. Nevertheless, it is used by a Message
Consumer for actually handling the consumed Messages, and so being aware of this strategy interface does help in
terms of understanding the overall role of a consumer. The interface is defined as follows:
<programlisting language="java">public interface MessageHandler {
void handleMessage(Message&lt;?&gt; message);
}</programlisting>
Despite its simplicity, this provides the foundation for most of the components that will be covered in the
following chapters (Routers, Transformers, Splitters, Aggregators, Service Activators, etc). Those components
each perform very different functionality with the Messages they handle, but the requirements for actually
receiving a Message are the same, and the choice between polling and event-driven behavior is also the same.
Spring Integration provides two endpoint implementations that "host" these callback-based handlers and allow
them to be connected to Message Channels.
</para>
</section>
<section id="endpoint-eventdrivenconsumer">
<title>Event Driven Consumer</title>
<para>
Because it is the simpler of the two, we will cover the Event Driven Consumer endpoint first. You may recall that
the <interfacename>SubscribableChannel</interfacename> interface provides a <methodname>subscribe()</methodname>
method and that the method accepts a <interfacename>MessageHandler</interfacename> parameter (as shown in
<xref linkend="channel-interfaces-subscribablechannel"/>):
<programlisting language="java">
subscribableChannel.subscribe(messageHandler);
</programlisting>
Since a handler that is subscribed to a channel does not have to actively poll that channel, this is an
Event Driven Consumer, and the implementation provided by Spring Integration accepts a
a <interfacename>SubscribableChannel</interfacename> and a <interfacename>MessageHandler</interfacename>:
<programlisting language="java">SubscribableChannel channel = (SubscribableChannel) context.getBean("subscribableChannel");
EventDrivenConsumer consumer = new EventDrivenConsumer(channel, exampleHandler);</programlisting>
</para>
</section>
<section id="endpoint-pollingconsumer">
<title>Polling Consumer</title>
<para>
Spring Integration also provides a <classname>PollingConsumer</classname>, and it can be instantiated in
the same way except that the channel must implement <interfacename>PollableChannel</interfacename>:
<programlisting language="java">PollableChannel channel = (PollableChannel) context.getBean("pollableChannel");
PollingConsumer consumer = new PollingConsumer(channel, exampleHandler);</programlisting>
</para>
<para>
There are many other configuration options for the Polling Consumer. For example, the trigger is a required property:
<programlisting language="java">
PollingConsumer consumer = new PollingConsumer(channel, handler);
consumer.setTrigger(new IntervalTrigger(30, TimeUnit.SECONDS));</programlisting>
Spring Integration currently provides two implementations of the <interfacename>Trigger</interfacename>
interface: <classname>IntervalTrigger</classname> and <classname>CronTrigger</classname>. The
<classname>IntervalTrigger</classname> is typically defined with a simple interval (in milliseconds), but
also supports an 'initialDelay' property and a boolean 'fixedRate' property (the default is false, i.e.
fixed delay):
<programlisting language="java">IntervalTrigger trigger = new IntervalTrigger(1000);
trigger.setInitialDelay(5000);
trigger.setFixedRate(true);</programlisting>
The <classname>CronTrigger</classname> simply requires a valid cron expression (see the Javadoc for details):
<programlisting language="java">CronTrigger trigger = new CronTrigger("*/10 * * * * MON-FRI");</programlisting>
</para>
<para>
In addition to the trigger, several other polling-related configuration properties may be specified:
<programlisting language="java">
PollingConsumer consumer = new PollingConsumer(channel, handler);
consumer.setMaxMessagesPerPoll(10);
consumer.setReceiveTimeout(5000);</programlisting>
</para>
<para>
The 'maxMessagesPerPoll' property specifies the maximum number of messages to receive within a given poll
operation. This means that the poller will continue calling receive() <emphasis>without waiting</emphasis>
until either <code>null</code> is returned or that max is reached. For example, if a poller has a 10 second
interval trigger and a 'maxMessagesPerPoll' setting of 25, and it is polling a channel that has 100 messages
in its queue, all 100 messages can be retrieved within 40 seconds. It grabs 25, waits 10 seconds, grabs the
next 25, and so on.
</para>
<para>
The 'receiveTimeout' property specifies the amount of time the poller should wait if no messages are
available when it invokes the receive operation. For example, consider two options that seem similar on
the surface but are actually quite different: the first has an interval trigger of 5 seconds and a receive
timeout of 50 milliseconds while the second has an interval trigger of 50 milliseconds and a receive timeout
of 5 seconds. The first one may receive a message up to 4950 milliseconds later than it arrived on the channel
(if that message arrived immediately after one of its poll calls returned). On the other hand, the second
configuration will never miss a message by more than 50 milliseconds. The difference is that the second
option requires a thread to wait, but as a result it is able to respond much more quickly to arriving messages.
This technique, known as "long polling", can be used to emulate event-driven behavior on a polled source.
</para>
<para>
A Polling Consumer may also delegate to a Spring <interfacename>TaskExecutor</interfacename>, and it can
be configured to participate in Spring-managed transactions. The following example shows the configuration of both:
<programlisting language="java">
PollingConsumer consumer = new PollingConsumer(channel, handler);
TaskExecutor taskExecutor = (TaskExecutor) context.getBean("exampleExecutor");
consumer.setTaskExecutor(taskExecutor);
PlatformTransactionManager txManager = (PlatformTransationManager) context.getBean("exampleTxManager");
consumer.setTransactionManager(txManager);</programlisting>
The examples above show dependency lookups, but keep in mind that these consumers will most often be configured
as Spring <emphasis>bean definitions</emphasis>. In fact, Spring Integration also provides a
<interfacename>FactoryBean</interfacename> that creates the appropriate consumer type based on the type of
channel, and there is full XML namespace support to even further hide those details. The namespace-based
configuration will be featured as each component type is introduced.
<note>
Many of the <interfacename>MessageHandler</interfacename> implementations are also capable of generating reply
Messages. As mentioned above, sending Messages is trivial when compared to the Message reception. Nevertheless,
<emphasis>when</emphasis> and <emphasis>how many</emphasis> reply Messages are sent depends on the handler
type. For example, an <emphasis>Aggregator</emphasis> waits for a number of Messages to arrive and is often
configured as a downstream consumer for a <emphasis>Splitter</emphasis> which may generate multiple
replies for each Message it handles. When using the namespace configuration, you do not strictly need to know
all of the details, but it still might be worth knowing that several of these components share a common base
class, the <classname>AbstractReplyProducingMessageHandler</classname>, and it provides a
<methodname>setOutputChannel(..)</methodname> method.
</note>
</para>
</section>
<section id="endpoint-namespace">
<title>Namespace Support</title>
<para>
Throughout the reference manual, you will see specific configuration examples for endpoint elements, such as
router, transformer, service-activator, and so on. Most of these will support an "input-channel" attribute and
many will support an "output-channel" attribute. After being parsed, these endpoint elements produce an instance
of either the <classname>PollingConsumer</classname> or the
<classname>EventDrivenConsumer</classname> depending on the type of the "input-channel" that is
referenced: <interfacename>PollableChannel</interfacename> or <interfacename>SubscribableChannel</interfacename>
respectively. When the channel is pollable, then the polling behavior is determined based on the endpoint
element's "poller" sub-element. For example, a simple interval-based poller with a 1-second interval would be
configured like this: <programlisting language="xml"><![CDATA[ <transformer input-channel="pollable"
ref="transformer"
output-channel="output">
<poller>
<interval-trigger interval="1000"/>
</poller>
</transformer>]]></programlisting>
For a poller based on a Cron expression, use the "cron-trigger" child element instead:
<programlisting language="xml"><![CDATA[ <transformer input-channel="pollable"
ref="transformer"
output-channel="output">
<poller>
<cron-trigger expression="*/10 * * * * MON-FRI"/>
</poller>
</transformer>]]></programlisting>
</para>
<para>
If the input channel is a <interfacename>PollableChannel</interfacename>, then the poller configuration is
required. Specifically, as mentioned above, the 'trigger' is a required property of the PollingConsumer class.
Therefore, if you omit the "poller" sub-element for a Polling Consumer endpoint's configuration, an Exception
may be thrown. However, it is also possible to create top-level pollers in which case only a "ref" is required:
<programlisting language="xml"><![CDATA[ <poller id="weekdayPoller">
<cron-trigger expression="*/10 * * * * MON-FRI"/>
</poller>
<transformer input-channel="pollable"
ref="transformer"
output-channel="output">
<poller ref="weekdayPoller"/>
</transformer>]]></programlisting>
In fact, to simplify the configuration, you can define a global default poller. A single top-level poller within
an ApplicationContext may have the <code>default</code> attribute with a value of "true". In that case, any
endpoint with a PollableChannel for its input-channel that is defined within the same ApplicationContext and has
no explicitly configured 'poller' sub-element will use that default.
<programlisting language="xml"><![CDATA[ <poller id="defaultPoller" default="true" max-messages-per-poll="5">
<interval-trigger interval="3" time-unit="SECONDS"/>
</poller>
<!-- No <poller/> sub-element is necessary since there is a default -->
<transformer input-channel="pollable"
ref="transformer"
output-channel="output"/>]]></programlisting>
</para>
<para>
Spring Integration also provides transaction support for the pollers so that each receive-and-forward
operation can be performed as an atomic unit-of-work. To configure transactions for a poller, simply add the
&lt;transactional/&gt; sub-element. The attributes for this element should be familiar to anyone who has
experience with Spring's Transaction management:
<programlisting language="xml"><![CDATA[<poller>
<interval-trigger interval="1000"/>
<transactional transaction-manager="txManager"
propagation="REQUIRED"
isolation="REPEATABLE_READ"
timeout="10000"
read-only="false"/>
</poller>]]></programlisting>
</para>
<para>
The polling threads may be executed by any instance of Spring's <interfacename>TaskExecutor</interfacename>
abstraction. This enables concurrency for an endpoint or group of endpoints. As of Spring 3.0, there is a "task"
namespace in the core Spring Framework, and its &lt;executor/&gt; element supports the creation of a simple thread
pool executor. That element accepts attributes for common concurrency settings such as pool-size and queue-capacity.
Configuring a thread-pooling executor can make a substantial difference in how the endpoint performs under load. These
settings are available per-endpoint since the performance of an endpoint is one of the major factors to consider
(the other major factor being the expected volume on the channel to which the endpoint subscribes). To enable
concurrency for a polling endpoint that is configured with the XML namespace support, provide the 'task-executor'
reference on its &lt;poller/&gt; element and then provide one or more of the properties shown below:
<programlisting language="xml"><![CDATA[ <poller task-executor="pool"/>
<interval-trigger interval="5" time-unit="SECONDS"/>
</poller>
<task:executor id="pool"
pool-size="5-25"
queue-capacity="20"
keep-alive="120"/>]]></programlisting>
If no 'task-executor' is provided, the consumer's handler will be invoked in the caller's thread. Note that the
"caller" is usually the default <interfacename>TaskScheduler</interfacename>
(see <xref linkend="namespace-taskscheduler"/>). Also, keep in mind that the 'task-executor' attribute can
provide a reference to any implementation of Spring's <interfacename>TaskExecutor</interfacename> interface by
specifying the bean name. The "executor" element above is simply provided for convenience.
</para>
<para>
As mentioned in the background section for Polling Consumers above, you can also configure a Polling Consumer
in such a way as to emulate event-driven behavior. With a long receive-timeout and a short interval-trigger,
you can ensure a very timely reaction to arriving messages even on a polled message source. Note that this
will only apply to sources that have a blocking wait call with a timeout. For example, the File poller does
not block, each receive() call returns immediately and either contains new files or not. Therefore, even if
a poller contains a long receive-timeout, that value would never be usable in such a scenario. On the other
hand when using Spring Integration's own queue-based channels, the timeout value does have a chance to
participate. The following example demonstrates how a Polling Consumer will receive Messages nearly
instantaneously.
<programlisting language="xml"><![CDATA[ <service-activator input-channel="someQueueChannel"
output-channel="output">
<poller receive-timeout="30000">
<interval-trigger interval="10"/>
</poller>
</service-activator>]]></programlisting>
Using this approach does not carry much overhead since internally it is nothing more then a timed-wait thread
which does not require nearly as much CPU resource usage as a thrashing, infinite while loop for example.
</para>
</section>
</chapter>

35
spring-integration-reference/src/event.xml
View File

@@ -1,35 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="applicationevent">
<title>Spring ApplicationEvent Support</title>
<para>
Spring Integration provides support for inbound and outbound <classname>ApplicationEvents</classname>
as defined by the underlying Spring Framework. For more information about the events and listeners,
refer to the <ulink url="http://static.springsource.org/spring/docs/2.5.x/reference/beans.html#context-functionality-events">Spring Reference Manual</ulink>.
</para>
<section id="applicationevent-inbound">
<title>Receiving Spring ApplicationEvents</title>
<para>
To receive events and send them to a channel, simply define an instance of Spring Integration's
<classname>ApplicationEventListeningChannelAdapter</classname>. This class is an implementation of
Spring's <interfacename>ApplicationListener</interfacename> interface. By default it will pass all
received events as Spring Integration Messages. To limit based on the type of event, configure the
list of event types that you want to receive with the 'eventTypes' property.
</para>
</section>
<section id="applicationevent-outbound">
<title>Sending Spring ApplicationEvents</title>
<para>
To send Spring <classname>ApplicationEvents</classname>, create an instance of the
<classname>ApplicationEventPublishingMessageHandler</classname> and register it within an endpoint.
This implementation of the <interfacename>MessageHandler</interfacename> interface also implements
Spring's <interfacename>ApplicationEventPublisherAware</interfacename> interface and thus acts as a
bridge between Spring Integration Messages and <classname>ApplicationEvents</classname>.
</para>
</section>
</chapter>

199
spring-integration-reference/src/file.xml
View File

@@ -1,199 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="files">
<title>File Support</title>
<section id="file-intro">
<title>Introduction</title>
<para>
Spring Integration's File support extends the Spring Integration Core with
a dedicated vocabulary to deal with reading, writing, and transforming files.
It provides a namespace that enables elements defining Channel Adapters dedicated
to files and support for Transformers that can read file contents into strings or
byte arrays.
</para>
<para>
This section will explain the workings of <classname>FileReadingMessageSource</classname>
and <classname>FileWritingMessageHandler</classname> and how to configure them as
<emphasis>beans</emphasis>. Also the support for dealing with files through file specific
implementations of <interfacename>Transformer</interfacename> will be discussed. Finally the
file specific namespace will be explained.
</para>
</section>
<section id="file-reading">
<title>Reading Files</title>
<para>
A <classname>FileReadingMessageSource</classname> can be used to consume files from the filesystem.
This is an implementation of <interfacename>MessageSource</interfacename> that creates messages from
a file system directory. <programlisting language="xml"><![CDATA[<bean id="pollableFileSource"
class="org.springframework.integration.file.FileReadingMessageSource"
p:inputDirectory="file:${input.directory}"/>]]></programlisting>
</para>
<para>
To prevent creating messages for certain files, you may supply a
<interfacename>FileListFilter</interfacename>. By default, an
<classname>AcceptOnceFileListFilter</classname> is used. This filter
ensures files are picked up only once from the directory.
<programlisting language="xml"><![CDATA[<bean id="pollableFileSource"
class="org.springframework.integration.file.FileReadingMessageSource"
p:inputDirectory="file:${input.directory}"
p:filter-ref="customFilterBean"/>]]></programlisting>
</para>
<para>
A common problem with reading files is that a file may be detected before
it is ready. The default <classname>AcceptOnceFileListFilter</classname>
does not prevent this. In most cases, this can be prevented if the
file-writing process renames each file as soon as it is ready for
reading. A pattern-matching filter that accepts only files that are
ready (e.g. based on a known suffix), composed with the default
<classname>AcceptOnceFileListFilter</classname> allows for this.
The <classname>CompositeFileListFilter</classname> enables the
composition.
<programlisting language="xml"><![CDATA[<bean id="pollableFileSource"
class="org.springframework.integration.file.FileReadingMessageSource"
p:inputDirectory="file:${input.directory}"
p:filter-ref="compositeFilter"/>
<bean id="compositeFilter" class="org.springframework.integration.file.CompositeFileListFilter">
<constructor-arg>
<list>
<bean class="org.springframework.integration.file.AcceptOnceFileListFilter" />
<bean class="org.springframework.integration.file.PatternMatchingFileListFilter">
<constructor-arg value="^test.*$"/>
</bean>
</list>
</constructor-arg>
</bean>]]></programlisting>
</para>
<para>
The configuration can be simplified using the file specific namespace. To do
this use the following template.
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:integration="http://www.springframework.org/schema/integration"
xmlns:file="http://www.springframework.org/schema/integration/file"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration-1.0.xsd
http://www.springframework.org/schema/integration/file
http://www.springframework.org/schema/integration/file/spring-integration-file-1.0.xsd">
</beans>]]></programlisting>
Within this namespace you can reduce the FileReadingMessageSource and wrap
it in an inbound Channel Adapter like this:
<programlisting language="xml"><![CDATA[ <file:inbound-channel-adapter id="filesIn"
directory="file:${input.directory}" prevent-duplicates="true"/>
<file:inbound-channel-adapter id="filesIn"
directory="file:${input.directory}"
filter="customFilterBean" />
<file:inbound-channel-adapter id="filesIn"
directory="file:${input.directory}"
filename-pattern="^test.*$" /> ]]></programlisting>
The first channel adapter is relying on the default filter that just prevents
duplication, the second is using a custom filter, and the third is using the
<emphasis>filename-pattern</emphasis> attribute to add a <classname>Pattern</classname>
based filter to the <classname>FileReadingMessageSource</classname>.
The <emphasis>file-name-pattern</emphasis> and <emphasis>filter</emphasis> attributes are mutually exclusive, but
you can use a <classname>CompositeFileListFilter</classname> to use any combination of filters, including a
pattern based filter to fit your particular needs.
</para>
</section>
<section id="file-writing">
<title>Writing files</title>
<para>
To write messages to the file system you can use a
<classname>FileWritingMessageHandler</classname>. This class can deal with
File, String, or byte array payloads. In its simplest form the
<classname>FileWritingMessageHandler </classname> only requires a
destination directory for writing the files. The name of the file to be
written is determined by the handler's <classname>FileNameGenerator</classname>.
The default implementation looks for a Message header whose key matches
the constant defined as <code>FileHeaders.FILENAME</code>.
</para>
<para>
Additionally, you can configure the encoding and the charset that
will be used in case of a String payload.
</para>
<para>
To make things easier you can configure the FileWritingMessageHandler as
part of an outbound channel adapter using the namespace.
<programlisting language="xml"><![CDATA[ <file:outbound-channel-adapter id="filesOut" directory="file:${input.directory.property}"/>]]></programlisting>
</para>
<para>
The namespace based configuration also supports a <code>delete-source-files</code> attribute.
If set to <code>true</code>, it will trigger deletion of the original source files after writing
to a destination. The default value for that flag is <code>false</code>.
<programlisting language="xml"><![CDATA[ <file:outbound-channel-adapter id="filesOut"
directory="file:${output.directory}"
delete-source-files="true"/>]]></programlisting>
<note>
<para>
The <code>delete-source-files</code> attribute will only have an effect if the inbound
Message has a File payload or if the <classname>FileHeaders.ORIGINAL_FILE</classname> header
value contains either the source File instance or a String representing the original file path.
</para>
</note>
</para>
<para>
In cases where you want to continue processing messages based on the written File you can use
the <code>outbound-gateway</code> instead. It plays a very similar role as the
<code>outbound-channel-adapter</code>. However after writing the File, it will also send it
to the reply channel as the payload of a Message.
<programlisting language="xml"><![CDATA[ <file:outbound-gateway id="mover" request-channel="moveInput"
reply-channel="output"
directory="${output.directory}"
delete-source-files="true"/>]]></programlisting>
</para>
<note>
The 'outbound-gateway' works well in cases where you want to first move a File and then send it
through a processing pipeline. In such cases, you may connect the file namespace's
'inbound-channel-adapter' element to the 'outbound-gateway' and then connect that gateway's
reply-channel to the beginning of the pipeline.
</note>
<para>
If you have more elaborate requirements or need to support additional payload types as input
to be converted to file content you could extend the FileWritingMessageHandler, but a much
better option is to rely on a <classname>Transformer</classname>.
</para>
</section>
<section id="file-transforming">
<title>File Transformers</title>
<para>
To transform data read from the file system to objects and the other way around you need
to do some work. Contrary to <classname>FileReadingMessageSource</classname> and to a
lesser extent <classname>FileWritingMessageHandler</classname>, it is very likely that you
will need your own mechanism to get the job done. For this you can implement the
<interfacename>Transformer</interfacename> interface. Or extend the
<classname>AbstractFilePayloadTransformer</classname> for inbound messages. Some obvious
implementations have been provided.
</para>
<para>
<classname>FileToByteArrayTransformer</classname> transforms Files into byte[]s using
Spring's <classname>FileCopyUtils</classname>. It is often better to use a sequence of
transformers than to put all transformations in a single class. In that case the File to
byte[] conversion might be a logical first step.
</para>
<para>
<classname>FileToStringTransformer</classname> will convert Files to Strings as the name
suggests. If nothing else, this can be useful for debugging (consider using with a Wire Tap).
</para>
<para>
To configure File specific transformers you can use the appropriate elements from the file namespace.
<programlisting language="xml"><![CDATA[ <file-to-bytes-transformer input-channel="input" output-channel="output"
delete-files="true"/>
<file:file-to-string-transformer input-channel="input" output-channel="output
delete-files="true" charset="UTF-8"/>]]></programlisting>
The <emphasis>delete-files</emphasis> option signals to the transformer that it should delete
the inbound File after the transformation is complete. This is in no way a replacement for using the
<classname>AcceptOnceFileListFilter</classname> when the FileReadingMessageSource is being used in a
multi-threaded environment (e.g. Spring Integration in general).
</para>
</section>
</chapter>

86
spring-integration-reference/src/filter.xml
View File

@@ -1,86 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="filter">
<title>Filter</title>
<section id="filter-introduction">
<title>Introduction</title>
<para>
Message Filters are used to decide whether a Message should be passed along or dropped based on some criteria
such as a Message Header value or even content within the Message itself. Therefore, a Message Filter is similar
to a router, except that for each Message received from the filter's input channel, that same Message may or may
not be sent to the filter's output channel. Unlike the router, it makes no decision regarding
<emphasis>which</emphasis> Message Channel to send to but only decides <emphasis>whether</emphasis> to send.
<note>
As you will see momentarily, the Filter does also support a discard channel, so in certain cases it
<emphasis>can</emphasis> play the role of a very simple router (or "switch") based on a boolean condition.
</note>
</para>
<para>
In Spring Integration, a Message Filter may be configured as a Message Endpoint that delegates to some
implementation of the <interfacename>MessageSelector</interfacename> interface. That interface is itself quite
simple: <programlisting language="java"><![CDATA[ public interface MessageSelector {
boolean accept(Message<?> message);
}]]></programlisting>
The <classname>MessageFilter</classname> constructor accepts a selector instance:
<programlisting language="java"><![CDATA[ MessageFilter filter = new MessageFilter(someSelector);]]></programlisting>
</para>
</section>
<section id="filter-namespace">
<title>The &lt;filter&gt; Element</title>
<para>
The &lt;filter&gt; element is used to create a Message-selecting endpoint. In addition to "input-channel"
and "output-channel" attributes, it requires a "ref". The "ref" may point to a MessageSelector implementation:
<programlisting language="xml"><![CDATA[ <filter input-channel="input" ref="selector" output-channel="output"/>
<bean id="selector" class="example.MessageSelectorImpl"/>]]></programlisting>
</para>
<para>
Alternatively, the "method" attribute can be added at which point the "ref" may refer to any object.
The referenced method may expect either the <interfacename>Message</interfacename> type or the payload type of
inbound Messages. The return value of the method must be a boolean value. Any time the method returns 'true',
the Message <emphasis>will</emphasis> be passed along to the output-channel.
<programlisting language="xml"><![CDATA[ <filter input-channel="input" output-channel="output"
ref="exampleObject" method="someBooleanReturningMethod"/>
<bean id="exampleObject" class="example.SomeObject"/>]]></programlisting>
</para>
<para>
If the selector or adapted POJO method returns <code>false</code>, there are a few settings that control the
fate of the rejected Message. By default (if configured like the example above), the rejected Messages will
be silently dropped. If rejection should instead indicate an error condition, then set the
'throw-exception-on-rejection' flag to <code>true</code>:
<programlisting language="xml"><![CDATA[ <filter input-channel="input" ref="selector"
output-channel="output" throw-exception-on-rejection="true"/> ]]></programlisting>
If you want the rejected messages to go to a specific channel, provide that reference as the 'discard-channel':
<programlisting language="xml"><![CDATA[ <filter input-channel="input" ref="selector"
output-channel="output" discard-channel="rejectedMessages"/> ]]></programlisting>
</para>
<note>
A common usage for Message Filters is in conjunction with a Publish Subscribe Channel. Many filter endpoints may
be subscribed to the same channel, and they decide whether or not to pass the Message for the next endpoint which
could be any of the supported types (e.g. Service Activator). This provides a <emphasis>reactive</emphasis>
alternative to the more <emphasis>proactive</emphasis> approach of using a Message Router with a single
Point-to-Point input channel and multiple output channels.
</note>
<para>
Using a "ref" attribute is generally recommended if the custom filter implementation can be reused in other
<code>&lt;filter&gt;</code> definitions. However if the custom filter implementation should be scoped to a
single <code>&lt;filter&gt;</code> element, provide an inner bean definition:
<programlisting language="xml"><![CDATA[<filter method="someMethod" input-channel="inChannel" output-channel="outChannel">
<beans:bean class="org.foo.MyCustomFilter"/>
</filter>]]></programlisting>
</para>
<note>
<para>
Using both the "ref" attribute and an inner handler definition in the same <code>&lt;filter&gt;</code> configuration
is not allowed, as it creates an ambiguous condition, and it will therefore result in an Exception being thrown.
</para>
</note>
</section>
</chapter>

103
spring-integration-reference/src/gateway.xml
View File

@@ -1,103 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="gateway">
<title>Inbound Messaging Gateways</title>
<section id="gateway-simple">
<title>SimpleMessagingGateway</title>
<para>
Even though the <classname>MessageChannelTemplate</classname> is fairly straightforward, it does not hide the
details of messaging from your application code. To support working with plain Objects instead of messages,
Spring Integration provides <classname>SimpleMessagingGateway</classname> with the following methods:
<programlisting language="java"><![CDATA[ public void send(Object object) { ... }
public Object receive() { ... }
public Object sendAndReceive(Object object) { ... }
Message<?> sendAndReceiveMessage(Object object);]]></programlisting>
It enables configuration of a request and/or reply channel and delegates to instances of the
<interfacename>InboundMessageMapper</interfacename> and <interfacename>OutboundMessageMapper</interfacename>
strategy interfaces.
<programlisting language="java"> SimpleMessagingGateway gateway = new SimpleMessagingGateway(inboundMapper, outboundMapper);
gateway.setRequestChannel(requestChannel);
gateway.setReplyChannel(replyChannel);
Object result = gateway.sendAndReceive("test");</programlisting>
</para>
</section>
<section id="gateway-proxy">
<title>GatewayProxyFactoryBean</title>
<para>
Working with Objects instead of Messages is an improvement. However, it would be even better to have no
dependency on the Spring Integration API at all - including the gateway class. For that reason, Spring
Integration also provides a <classname>GatewayProxyFactoryBean</classname> that generates a proxy for
any interface and internally invokes the gateway methods shown above. Namespace support is also
provided as demonstrated by the following example.
<programlisting language="xml"><![CDATA[<gateway id="fooService"
service-interface="org.example.FooService"
default-request-channel="requestChannel"
default-reply-channel="replyChannel"/>]]></programlisting>
Then, the "fooService" can be injected into other beans, and the code that invokes the methods on that
proxied instance of the FooService interface has no awareness of the Spring Integration API. The general
approach is similar to that of Spring Remoting (RMI, HttpInvoker, etc.). See the "Samples" Appendix for
an example that uses this "gateway" element (in the Cafe demo).
</para>
<para>
The reason that the attributes on the 'gateway' element are named 'default-request-channel' and
'default-reply-channel' is that you may also provide per-method channel references by using the
@Gateway annotation.
<programlisting language="java"><![CDATA[ public interface Cafe {
@Gateway(requestChannel="orders")
void placeOrder(Order order);
}]]></programlisting>
</para>
<para>
It is also possible to pass values to be interpreted as Message headers on the Message
that is created and sent to the request channel by using the @Header annotation:
<programlisting language="java"><![CDATA[ public interface FileWriter {
@Gateway(requestChannel="filesOut")
void write(byte[] content, @Header(FileHeaders.FILENAME) String filename);
}]]></programlisting>
</para>
<para>
If you prefer XML way of configuring Gateway methods, you can provide <emphasis>method</emphasis> sub-elements
to the gateway configuration (see below)
<programlisting language="xml"><![CDATA[<si:gateway id="myGateway" service-interface="org.foo.bar.TestGateway"
default-request-channel="inputC">
<si:method name="echo" request-channel="inputA" reply-timeout="2" request-timeout="200"/>
<si:method name="echoUpperCase" request-channel="inputB"/>
<si:method name="echoViaDefault"/>
</si:gateway>]]></programlisting>
</para>
<para>
You can also provide individual headers per method invocation via XML.
This could be very useful if headers you want to set are static in nature and you don't want
to embed them in the gateway's method signature via <classname>@Header</classname> annotation.
For example; in the Loan Broker example we want to influence how aggregation of the Loan quotes
will be done based on what type of request was initiated (single quote or all quotes). Determining the
type of the request by evaluating what gateway's method was invoked, although possible would
violate the separation of concerns paradigm (method is a java artifact),  but expressing your
intention (meta information) via Message headers is natural to Messaging architecture.
<programlisting language="xml"><![CDATA[<int:gateway id="loanBrokerGateway"
service-interface="org.springframework.integration.loanbroker.LoanBrokerGateway">
<int:method name="getLoanQuote" request-channel="loanBrokerPreProcessingChannel">
<int:header name="RESPONSE_TYPE" value="BEST"/>
</int:method>
<int:method name="getAllLoanQuotes" request-channel="loanBrokerPreProcessingChannel">
<int:header name="RESPONSE_TYPE" value="ALL"/>
</int:method>
</int:gateway>]]></programlisting>
In the above case you can clearly see how a different header value will be set for the 'RESPONSE_TYPE'
header based on the gateway's method.
</para>
</section>
</chapter>

128
spring-integration-reference/src/http.xml
View File

@@ -1,128 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="http">
<title>HTTP Support</title>
<section id="http-intro">
<title>Introduction</title>
<para>
The HTTP support allows for the making of HTTP requests and the processing of inbound Http requests. Because interaction over HTTP is always synchronous, even if all that is returned is a 200 status code the Http support consists of two gateway implementations
<classname>HttpInboundEndpoint</classname> and <classname>HttpOutboundEndpoint</classname>.
</para>
</section>
<section id="http-inbound">
<title>Http Inbound Gateway</title>
<para>
To receive messages over http you need to use an <classname>HttpInboundEndpoint</classname>. In common with the HttpInvoker
support the Http Inbound Gateway needs to be deployed within a servlet container. The easiest way to do this is to provide a servlet
definition in <emphasis>web.xml</emphasis>, see
<xref linkend="httpinvoker-inbound"/> for further details. Below is an example bean definition for a simple <classname>HttpInboundEndpoint</classname>
<programlisting language="xml"><![CDATA[<bean id="httpInbound" class="org.springframework.integration.http.HttpInboundEndpoint">
<property name="requestChannel" ref="httpRequestChannel" />
<property name="replyChannel" ref="httpReplyChannel" />
</bean>]]></programlisting>
The <classname>HttpInboundEndpoint</classname> accepts an instance of <interfacename>InboundRequestMapper</interfacename> which allows
customisation of the mapping from <interfacename>HttpServletRequest</interfacename> to <interfacename>Message</interfacename>. If none is
provided an instance of <classname>DefaultInboundRequestMapper</classname> will be used. This encapsulates a simple strategy, which for
example will create a String message for a <emphasis>POST</emphasis> request where the content type starts with "text", see the Javadoc for
full details.
</para>
<para>Starting with this release MultiPart File support was implemented. If the request has been wrapped as a
<emphasis>MultipartHttpServletRequest</emphasis>, then the 'content type' can be checked. If it is known, and
begins with "text", then the <emphasis>MultipartFile</emphasis> will be copied to a String in the parameter
map. If the content type does not begin with "text", then the <emphasis>MultipartFile</emphasis> will be copied
to a byte array within the parameter map instead.
<note>
The HttpInboundEndpoint will locate a MultipartResolver in the context if one exists with the bean name
"multipartResolver" (the same name expected by Spring's DispatcherServlet). If it does in fact locate that
bean, then the support for MultipartFiles will be enabled on the inbound request mapper. Otherwise, it will
fail when trying to map a multipart-file request to a Spring Integration Message. For more on Spring's
support for MultipartResolvers, refer to the <ulink url="http://static.springsource.org/spring/docs/2.5.x/reference/mvc.html#mvc-multipart">Spring Reference Manual</ulink>.
</note>
</para>
<para>
In sending a response to the client there are a number of ways to customise the behaviour of the gateway. By default the gateway will
simply acknowledge that the request was received by sending a 200 status code back. It is possible to customise this response by providing an
implementation of the Spring MVC <interfacename>View</interfacename> which will be invoked with the created <interfacename>Message</interfacename>.
In the case that the gateway should expect a reply to the <interfacename>Message</interfacename> then setting the <property>expectReply</property> flag will cause
the gateway to wait for a response <interfacename>Message</interfacename> before creating an Http response. Below is an example of a gateway
configured to use a custom view and to wait for a response. It also shows how to customise the Http methods accepted by the gateway, which
are <emphasis>POST</emphasis> and <emphasis>GET</emphasis> by default.
<programlisting language="xml"><![CDATA[<bean id="httpInbound" class="org.springframework.integration.http.HttpInboundEndpoint">
<property name="requestChannel" ref="httpRequestChannel" />
<property name="replyChannel" ref="httpReplyChannel" />
<property name="view" ref="jsonView" />
<property name="supportedMethods" >
<list>
<value>GET</value>
<value>DELETE</value>
</list>
</property>
<property name="expectReply" value="true" />
<property name="requestMapper" ref="customRequestMapper" />
</bean>]]></programlisting>
The message created from the request will be available in the Model map. The key that is used
for that map entry by default is 'requestMessage', but this can be overridden by setting the
'requestKey' property on the endpoint's configuration.
</para>
</section>
<section id="http-outbound">
<title>Http Outbound Gateway</title>
<para>
To configure the <classname>HttpOutboundEndpoint</classname> write a bean definition like this:
<programlisting language="xml"><![CDATA[<bean id="httpOutbound" class="org.springframework.integration.http.HttpOutboundEndpoint" >
<property name="outputChannel" ref="responseChannel" />
</bean>]]></programlisting>
This bean definition will execute Http requests by first converting the message to the Http request using an instance of
<classname>DefaultOutboundRequestMapper</classname>. This will expect to find the request URL in the message header under
the key <emphasis>HttpHeaders.REQUEST_URL</emphasis>. It is also possible to set a default target URL as a constructor argument
along with other options as shown below.
<programlisting language="xml"><![CDATA[<bean id="httpOutbound" class="org.springframework.integration.http.HttpOutboundEndpoint" >
<constructor-arg value="http://localhost:8080/example" />
<property name="outputChannel" ref="responseChannel" />
<property name="sendTimeout" value="5000" />
<property name="requestMapper" ref="customRequestMapper" />
</bean>]]></programlisting>
By default the Http request will be made using an instance of <classname>SimpleHttpRequestExecutor</classname> which uses the JDK
<classname>HttpURLConnection</classname>. Use of the Apache Commons Http Client is also supported through the provided
<classname>CommonsHttpRequestExecutor</classname> which can be injected into the outbound gateway.
</para>
</section>
<section id="http-namespace">
<title>Http Namespace Support</title>
<para>
Spring Integration provides an "http" namespace and schema definition. To include it in your
configuration, simply provide the following URI within a namespace declaration:
'http://www.springframework.org/schema/integration/http'. The schema location should then map to
'http://www.springframework.org/schema/integration/http/spring-integration-http-1.0.xsd'.
</para>
<para>
To configure an inbound http channel adapter which is an instance of <classname>HttpInboundEndpoint</classname> configured
not to expect a response.
<programlisting language="xml"><![CDATA[ <http:inbound-channel-adapter id="httpChannelAdapter" channel="requests" supported-methods="PUT, DELETE"/>]]></programlisting>
</para>
<para>
To configure an inbound http gateway which expects a response.
<programlisting language="xml"><![CDATA[ <http:inbound-gateway id="inboundGateway" request-channel="requests" reply-channel="responses"/>]]></programlisting>
</para>
<para>
To configure the outbound gateway you can use the namespace support as well. The following code snippet shows the different configuration options for an outbound Http gateway.
<programlisting language="xml"><![CDATA[<http:outbound-gateway id="fullConfigWithoutMapper"
request-channel="requests"
default-url="http://localhost/test"
extract-request-payload="false"
charset="UTF-8"
request-executor="executor"
request-timeout="1234"
reply-channel="replies"/>]]></programlisting>
If you want to provide a custom OutboundRequestMapper, then a reference may be supplied to the
'request-mapper' attribute. In that case however you will not be allowed to set the default URL,
charset, and 'extract-request-payload' properties since those are all properties of the default
mapper (see the JavaDoc for DefaultOutboundRequestMapper for more information).
</para>
</section>
</chapter>

101
spring-integration-reference/src/httpinvoker.xml
View File

@@ -1,101 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="httpinvoker">
<title>HttpInvoker Support</title>
<section id="httpinvoker-intro">
<title>Introduction</title>
<para>
HttpInvoker is a Spring-specific remoting option that essentially enables Remote Procedure Calls (RPC) over HTTP.
In order to accomplish this, an outbound representation of a method invocation is serialized using standard Java
serialization and then passed within an HTTP POST request. After being invoked on the target system, the method's
return value is then serialized and written to the HTTP response. There are two main requirements. First, you
must be using Spring on both sides since the marshalling to and from HTTP requests and responses is handled by
the client-side invoker and server-side exporter. Second, the Objects that you are passing must implement
<interfacename>Serializable</interfacename> and be available on both the client and server.
</para>
<para>
While traditional RPC provides <emphasis>physical</emphasis> decoupling, it does not offer nearly the same degree
of <emphasis>logical</emphasis> decoupling as a messaging-based system. In other words, both participants in an
RPC-based invocation must be aware of a specific interface and specific argument types. Interestingly, in Spring
Integration, the "parameter" being sent is a Spring Integration Message, and the interface is an internal detail
of Spring Integration's implementation. Therefore, the RPC mechanism is being used as a
<emphasis>transport</emphasis> so that from the end user's perspective, it is not necessary to consider the
interface and argument types. It's just another adapter to enable messaging between two systems.
</para>
</section>
<section id="httpinvoker-inbound">
<title>HttpInvoker Inbound Gateway</title>
<para>
To receive messages over http you can use an <classname>HttpInvokerInboundGateway</classname>. Here is an
example bean definition:
<programlisting language="xml"><![CDATA[<bean id="inboundGateway"
class="org.springframework.integration.httpinvoker.HttpInvokerInboundGateway">
<property name="requestChannel" ref="requestChannel"/>
<property name="replyChannel" ref="replyChannel"/>
<property name="requestTimeout" value="30000"/>
<property name="replyTimeout" value="10000"/>
</bean>]]></programlisting>
Because the inbound gateway must be able to receive HTTP requests, it must be configured within a Servlet
container. The easiest way to do this is to provide a servlet definition in <emphasis>web.xml</emphasis>:
<programlisting language="xml"><![CDATA[<servlet>
<servlet-name>inboundGateway</servlet-name>
<servlet-class>org.springframework.web.context.support.HttpRequestHandlerServlet</servlet-class>
</servlet>]]></programlisting>
Notice that the servlet name matches the bean name.
<note>
If you are running within a Spring MVC application and using the BeanNameHandlerMapping, then the servlet
definition is not necessary. In that case, the bean name for your gateway can be matched against the URL
path just like a Spring MVC Controller bean.
</note>
</para>
</section>
<section id="httpinvoker-outbound">
<title>HttpInvoker Outbound Gateway</title>
<para>
</para>
<para>
To configure the <classname>HttpInvokerOutboundGateway</classname> write a bean definition like this:
<programlisting language="xml"><![CDATA[<bean id="outboundGateway"
class="org.springframework.integration.httpinvoker.HttpInvokerOutboundGateway">
<property name="replyChannel" ref="replyChannel"/>
</bean>]]></programlisting>
The outbound gateway is a <interfacename>MessageHandler</interfacename> and can therefore be registered with
either a <classname>PollingConsumer</classname> or <classname>EventDrivenConsumer</classname>.
The URL must match that defined by an inbound HttpInvoker Gateway as described in the previous section.
</para>
</section>
<section id="httpinvoker-namespace">
<title>HttpInvoker Namespace Support</title>
<para>
Spring Integration provides an "httpinvoker" namespace and schema definition. To include it in your
configuration, simply provide the following URI within a namespace declaration:
'http://www.springframework.org/schema/integration/httpinvoker'. The schema location should then map to
'http://www.springframework.org/schema/integration/httpinvoker/spring-integration-httpinvoker-1.0.xsd'.
</para>
<para>
To configure the inbound gateway you can choose to use the namespace support for it. The following code snippet shows the different configuration options that are supported.
<programlisting language="xml"><![CDATA[<httpinvoker:inbound-gateway id="inboundGateway"
request-channel="requestChannel"
request-timeout="10000"
expect-reply="false"
reply-timeout="30000"/>]]></programlisting>
<note>
A 'reply-channel' may also be provided, but it is recommended to rely on the temporary anonymous channel
that will be created automatically for handling replies.
</note>
</para>
<para>
To configure the outbound gateway you can use the namespace support as well. The following code snippet shows the different configuration for an outbound HttpInvoker gateway. Only the 'url' and 'request-channel' are required.
<programlisting language="xml"><![CDATA[<httpinvoker:outbound-gateway id="outboundGateway"
url="http://localhost:8080/example"
request-channel="requestChannel"
request-timeout="5000"
reply-channel="replyChannel"
reply-timeout="10000"/>]]></programlisting>
</para>
</section>
</chapter>

758
spring-integration-reference/src/ip.xml
View File

@@ -1,758 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="ip">
<title>TCP and UDP Support</title>
<para>
Spring Integration provides Channel Adapters for receiving and sending messages over internet protocols. Both UDP
(User Datagram Protocol)
and TCP (Transmission Control Protocol) adapters are provided. Each adapter provides for one-way communication
over the underlying protocol.
In addition, a simple inbound tcp gateway is provided.
</para>
<section id="ip-intro">
<title>Introduction</title>
<para>
Two flavors each of UDP inbound and outbound adapters are provided <classname>UnicastSendingMessageHandler</classname>
sends a datagram packet to a single destination. <classname>UnicastReceivingChannelAdapter</classname> receives
incoming datagram packets. <classname>MulticastSendingMessageHandler</classname> sends (broadcasts) datagram packets to
a multicast address. <classname>MulticastReceivingChannelAdapter</classname> receives incoming datagram packets
by joining to a multicast address.
</para>
<para>
Two flavors each of TCP inbound and outbound adapters are provided <classname>TcpNetSendingMessageHandler</classname>
and <classname>TcpNioSendingMessageHandler</classname> send messages over TCP. They are functionally equivalent,
but use different underlying technology for socket communication. Similarly, <classname>TcpNetReceivingChannelAdapter</classname>
and <classname>TcpNioReceivingChannelAdapter</classname> are the equivalent inbound channel adapters.
The choice of which to use in what circumstances is described below.
</para>
<para>
A simple inbound TCP gateway is provided; this allows for simple request/response processing. While
the gateway can support any number of connections, each connection can only process serially. The thread
that reads from the socket waits for, and sends, the response before reading again.
</para>
</section>
<section id="udp-adapters">
<title>UDP Adapters</title>
<para>
<programlisting language="xml"><![CDATA[ <ip:outbound-channel-adapter id="udpOut"
protocol="udp"
host="somehost"
port="11111"
multicast="false"
channel="exampleChannel" />]]></programlisting>
A simple UDP outbound channel adapter.
<tip>
When setting multicast to true, provide the multicast address in the host
attribute.
</tip>
</para>
<para>
UDP is an efficient, but unreliable protocol. Two attributes are added to improve reliability. When check-length is
set to true, the adapter precedes the message data with a length field (4 bytes in network byte order). This enables
the receiving side to verify the length of the packet received. If a receiving system uses a buffer that is too
short the contain the packet, the packet can be truncated. The length header provides a mechanism to detect this.
</para>
<para>
<programlisting language="xml"><![CDATA[ <ip:outbound-channel-adapter id="udpOut"
protocol="udp"
host="somehost"
port="11111"
multicast="false"
check-length="true"
channel="exampleChannel" />]]></programlisting>
An outbound channel adapter that adds length checking to the datagram packets.
<tip>
The recipient of the packet must also be configured to expect a length to precede the
actual data. For a Spring Integration UDP inbound channel adapter, set its
<classname>check-length</classname> attribute.
</tip>
</para>
<para>
The second reliability improvement allows an application-level acknowledgment protocol to be used. The receiver
must send an acknowledgment to the sender within a specified time.
</para>
<para>
<programlisting language="xml"><![CDATA[ <ip:outbound-channel-adapter id="udpOut"
protocol="udp"
host="somehost"
port="11111"
multicast="false"
check-length="true"
acknowledge="true"
ack-host="thishost"
ack-port="22222"
ack-timeout="10000"
channel="exampleChannel" />]]></programlisting>
An outbound channel adapter that adds length checking to the datagram packets and waits for an acknowledgment.
<tip>
Setting acknowledge to true implies the recipient of the packet can interpret the header added to the packet
containing acknowledgment data (host and port). Most likely, the recipient will be a Spring Integration inbound
channel adapter.
</tip>
<tip>
When multicast is true, an additional attribute min-acks-for-success specifies
how many acknowledgments must be received within the ack-timeout.
</tip>
</para>
<para>
For even more reliable networking, TCP can be used.
</para>
<para>
<programlisting language="xml"><![CDATA[ <ip:inbound-channel-adapter id="udpReceiver"
channel="udpOutChannel"
protocol="udp"
port="11111"
receive-buffer-size="500"
multicast="false"
check-length="true" />]]></programlisting>
A basic unicast inbound udp channel adapter.
</para>
<para>
<programlisting language="xml"><![CDATA[ <ip:inbound-channel-adapter id="udpReceiver"
channel="udpOutChannel"
protocol="udp"
port="11111"
receive-buffer-size="500"
multicast="true"
multicast-address="225.6.7.8"
check-length="true" />]]></programlisting>
A basic multicast inbound udp channel adapter.
</para>
</section>
<section id="tcp-adapters">
<title>TCP Adapters</title>
<para>
Two versions of TCP inbound and outbound channel adapters are provided; these adapters
use either java.net.Socket IO, or java.nio.channels.SocketChannel IO. The choice of which
to use depends on the application. The TcpNet* adapters use java.net.Socket and the TcpNio*
adapters use java.nio.channels.ChannelSocket. It is not anticipated that much difference in
performance, if any, would exist between these technologies on the outbound side. This is
because each outbound adapter sends data over only one socket. On the receiving side
however, consideration should be given to the number of connections. For the
<classname>TcpNetReceivingChannelAdapter</classname> a thread is dedicated to receiving
data on each connected socket; the pool size must therefore be set large enough to handle
the expected number of connections. For the <classname>TcpNioReceivingChannelAdapter</classname>
threads are used on an as-needed basis and it is likely that many fewer threads would be
needed. If a small number of connections is expected, we expect that the the TcpNetReceivingChannelAdapter
will give the best performance. For large number of connections, the TcpNioReceivingChannelAdapter will
likely give the best performance. In addition, the TcpNioReceivingChannelAdapter provides an
attribute <classname>using-direct-buffers</classname> which attempts to use direct buffers. See
<classname>java.nio.ByteBuffer</classname> for more information about direct buffers.
<tip>
It is not expected that direct buffers will offer much, if any, performance difference. You
should experiment with the use of TcpNxx* adapters, and direct buffers when using TcpNio*
adapters to determine the best performance in your environment.
</tip>
</para>
<para>
TCP is a streaming protocol; this means that some structure has to be provided to data
transported over TCP, so the receiver can demarcate the data into discrete messages.
Three standard message formats are provided for this purpose; you can also provide code
for your own custom format. The first of the three standard formats is length-header, in which case a 4 byte
length header precedes the data; this is the default. The second is stx-etx in which the message
data is preceded by an STX (0x02) character and terminated with an ETX (0x03) character.
The third is crlf in which the message is terminated with a carriage return and line feed
(\r\n). The first format (the default) is likely to be the most performant. This is because
we can determine exactly how many bytes to read to obtain the complete message. The other
two formats require examining each byte to determine if the end of the message has been
received. The length-header format can also handle binary data. The other two formats can only handle
text data (specifcally, data that does not contain characters 0x02 and 0x03 for stx-etx and
0x0d and 0x0a for crlf). This limitation can be avoided by appropriate character escaping techniques
in the application layer. No such escaping is provided by the adapters; therefore it is not recommened
that these formats be used without some transformation if the data may contain these characters.
</para>
<para>
<programlisting language="xml"><![CDATA[ <ip:outbound-channel-adapter id="tcpOut"
channel="inChannel"
protocol="tcp"
host="somehost"
port="11111"
message-format="length-header"
using-nio="true"
using-direct-buffers="false"
so-keep-alive="true"
so-timeout="10000"
/>]]></programlisting>
A basic outbound tcp channel adapter. This adapter uses java.nio.channels.SocketChannel.
To use a java.net.Socket, set <classname>using-nio</classname> to false and
<classname>using-direct-buffers</classname> is not relevant.
</para>
<para>
<programlisting language="xml"><![CDATA[ <ip:inbound-channel-adapter id="tcp1"
channel="channel"
protocol="tcp"
port="11111"
message-format="length-header"
using-nio="true"
using-direct-buffers="false"
pool-size="2"
so-keep-alive="true"
so-timeout="10000"
/>]]></programlisting>
A basic inbound tcp channel adapter. This adapter uses java.nio.channels.SocketChannel.
To use a java.net.Socket, set <classname>using-nio</classname> to false and
<classname>using-direct-buffers</classname> is not relevant.
</para>
</section>
<section id="tcp-gateways">
<title>TCP Gateways</title>
<para>
The simple inbound TCP gateway <classname>SimpleTcpNetInboundGateway</classname>
and simple oubound TCP gateway <classname>SimpleTcpNetOutboundGateway</classname>
use <classname>java.net.Socket</classname> for communications. Each connection
can process a single request/response at a time.
</para>
<para>
The inbound gateway delegates to a subclass of the <classname>TcpNetReceivingChannelAdapter</classname>
described above, so please read that section for more information. After
constructing a message with the incoming payload and sending
it to the requestChannel, it waits for a response and sends the payload
from the response message by writing it to the socket, using the same
message format configured for the incoming message.
</para>
<para>
The outbound gateway delegates to a <classname>TcpNetSendingMessageHandler</classname>
described above, so please read that section for more information. After
sending a message over the socket, the thread waits for a response and
constructs a response message with a byte[] payload The incoming
response is decoded using the same
message format configured for the outgoing message. Communications over
the socket are single-threaded. Users should be aware that only one
message can be handled at a time and if another thread attempts to send
a message before the current response has been received, it will block. Only
when the inprocess message receives a response (or times out based on the
socket timeout option) will it proceed.
</para>
<para>
<programlisting language="xml"><![CDATA[ <ip:inbound-gateway id="gatewayCrLf"
port="1234"
request-channel="someChannel"
message-format="crlf"
/>]]></programlisting>
A simple inbound TCP gateway; it uses '/r/n' delimited data and can be
used by a simple client such as telnet.
</para>
<para>
<programlisting language="xml"><![CDATA[ <ip:outbound-gateway id="simpleOutGateway"
request-channel="tcpChannel"
message-format="crlf"
host="localhost"
port="1234"
/>]]></programlisting>
A simple oubound TCP gateway; it uses '/r/n' delimited data.
</para>
</section>
<section id="ip-endpoint-reference">
<title>IP Endpoint Attributes</title>
<para>
<table id="ip-ob-adapter-attributes">
<title>IP Outbound Channel Adapter Attributes</title>
<tgroup cols="5">
<colspec align="left" />
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="0.3*" align="center"/>
<colspec colnum="3" colname="col3" colwidth="0.3*" align="center"/>
<colspec colnum="4" colname="col4" colwidth="1*"/>
<colspec colnum="5" colname="col5" colwidth="2*"/>
<thead>
<row>
<entry align="center">Attribute Name</entry>
<entry align="center">TCP?</entry>
<entry align="center">UDP?</entry>
<entry align="center">Allowed Values</entry>
<entry align="center">Attribute Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>protocol</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry>tcp, udp</entry>
<entry>Determines whether the adapter uses TCP or UDP, over IP.</entry>
</row>
<row>
<entry>host</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>The host name or ip address of the destination. For multicast udp
adapters, the multicast address.</entry>
</row>
<row>
<entry>port</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>The port on the destination.</entry>
</row>
<row>
<entry>multicast</entry>
<entry>N</entry>
<entry>Y</entry>
<entry>true, false</entry>
<entry>Whether or not the udp adapter uses multicast.</entry>
</row>
<row>
<entry>acknowledge</entry>
<entry>N</entry>
<entry>Y</entry>
<entry>true, false</entry>
<entry>Whether or not a udp adapter requires an acknowledgment from the destination.
when enabled, requires setting the following 4 attributes.</entry>
</row>
<row>
<entry>ack-host</entry>
<entry>N</entry>
<entry>Y</entry>
<entry></entry>
<entry>When acknowledge is true, indicates the host or ip address to which the
acknowledgment should be sent. Usually the current host, but may be
different, for example when Network Address Transation (NAT) is
being used.</entry>
</row>
<row>
<entry>ack-port</entry>
<entry>N</entry>
<entry>Y</entry>
<entry></entry>
<entry>When acknowledge is true, indicates the port to which the
acknowledgment should be sent. The adapter listens on this port for
acknowledgments.</entry>
</row>
<row>
<entry>ack-timeout</entry>
<entry>N</entry>
<entry>Y</entry>
<entry></entry>
<entry>When acknowledge is true, indicates the time in milliseconds that the
adapter will wait for an acknowlegment. If an acknowlegment is not
received in time, the adapter will throw an exception.</entry>
</row>
<row>
<entry>min-acks-for- success</entry>
<entry>N</entry>
<entry>Y</entry>
<entry></entry>
<entry>Defaults to 1. For multicast adapters, you can set this to a larger
value, requiring acknowlegments from multiple destinations.</entry>
</row>
<row>
<entry>check-length</entry>
<entry>N</entry>
<entry>Y</entry>
<entry>true, false</entry>
<entry>Whether or not a udp adapter includes a data length field in the
packet sent to the destination.</entry>
</row>
<row>
<entry>time-to-live</entry>
<entry>N</entry>
<entry>Y</entry>
<entry></entry>
<entry>For multicast adapters, specifies the time to live attribute for
the <classname>MulticastSocket</classname>; controls the scope
of the multicasts. Refer to the Java API
documentation for more information.</entry>
</row>
<row>
<entry>using-nio</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>true, false</entry>
<entry>Whether or not the tcp adapter is using NIO. Refer to the java.nio
package for more information.</entry>
</row>
<row>
<entry>using-direct-buffers</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>true, false</entry>
<entry>When using NIO, whether or not the tcp adapter uses direct buffers.
Refer to <classname>java.nio.ByteBuffer</classname> documentation for
more information.</entry>
</row>
<row>
<entry>message-format</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>length-header, stx-etx, crlf, custom</entry>
<entry>The formatting that the tcp adapter uses so the receiver can demarcate
messages. Defaults to length-header.
See the discussion above for details about each format.</entry>
</row>
<row>
<entry>custom-socket- writer-class-name</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>Subclass of TcpNetSocket- Writer or TcpNioSocket- Writer</entry>
<entry>When message-format is 'custom' the name of the class that
implements the custom format. Must be a subclass of the TcpNxxSocketWriter,
depending on whether using-nio is false or true.</entry>
</row>
<row>
<entry>so-timeout</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname> and <classname>java.net.DatagramSocket</classname>
setSoTimeout() methods for more information.</entry>
</row>
<row>
<entry>so-send-buffer-size</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname> and <classname>java.net.DatagramSocket</classname>
setSendBufferSize() methods for more information.</entry>
</row>
<row>
<entry>so-receive-buffer- size</entry>
<entry>N</entry>
<entry>Y</entry>
<entry></entry>
<entry>Used for udp acknowlegment packets. See <classname>java.net.DatagramSocket</classname>
setReceiveBufferSize() methods for more information.</entry>
</row>
<row>
<entry>so-keep-alive</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>true, false</entry>
<entry>See <classname>java.net.Socket. setKeepAlive()</classname>.</entry>
</row>
<row>
<entry>so-linger</entry>
<entry>Y</entry>
<entry>N</entry>
<entry></entry>
<entry>Sets linger to true with supplied value.
See <classname>java.net.Socket. setSoLinger()</classname>.</entry>
</row>
<row>
<entry>so-tcp-no-delay</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>true, false</entry>
<entry>See <classname>java.net.Socket. setTcpNoDelay()</classname>.</entry>
</row>
<row>
<entry>so-traffic-class</entry>
<entry>Y</entry>
<entry>N</entry>
<entry></entry>
<entry>See <classname>java.net.Socket. setTrafficClass()</classname>.</entry>
</row>
</tbody>
</tgroup>
</table>
<table id="ip-ib-adapter-attributes">
<title>IP Inbound Channel Adapter Attributes</title>
<tgroup cols="5">
<colspec align="left" />
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="0.3*" align="center"/>
<colspec colnum="3" colname="col3" colwidth="0.3*" align="center"/>
<colspec colnum="4" colname="col4" colwidth="1*"/>
<colspec colnum="5" colname="col5" colwidth="2*"/>
<thead>
<row>
<entry align="center">Attribute Name</entry>
<entry align="center">TCP?</entry>
<entry align="center">UDP?</entry>
<entry align="center">Allowed Values</entry>
<entry align="center">Attribute Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>protocol</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry>tcp, udp</entry>
<entry>Determines whether the adapter uses TCP or UDP, over IP.</entry>
</row>
<row>
<entry>port</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>The port on which the adapter listens.</entry>
</row>
<row>
<entry>multicast</entry>
<entry>N</entry>
<entry>Y</entry>
<entry>true, false</entry>
<entry>Whether or not the udp adapter uses multicast.</entry>
</row>
<row>
<entry>multicast-address</entry>
<entry>N</entry>
<entry>Y</entry>
<entry></entry>
<entry>When multicast is true, the multicast address to which the adapter
joins.</entry>
</row>
<row>
<entry>pool-size</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>Specifies the concurrency. For udp, specifies how many packets can
be handled concurrently. For tcp, not using nio, specifies the
number of concurrent connections supported by the adapter. For tcp,
using nio, specifies the number of tcp fragments that are concurrently
reassembled into complete messages.</entry>
</row>
<row>
<entry>receive-buffer-size</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>For udp, the size of the buffer used to receive DatagramPackets.
Usually set to the MTU size. If a smaller buffer is used than the
size of the sent packet, truncation can occur. This can be detected
by means of the check-length attribute.For tcp, the size of the
buffer used to reassemble incoming messages. Effectively the maximum
message size that can be received.</entry>
</row>
<row>
<entry>check-length</entry>
<entry>N</entry>
<entry>Y</entry>
<entry>true, false</entry>
<entry>Whether or not a udp adapter expects a data length field in the
packet received. Used to detect packet truncation.</entry>
</row>
<row>
<entry>using-nio</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>true, false</entry>
<entry>Whether or not the tcp adapter is using NIO. Refer to the java.nio
package for more information.</entry>
</row>
<row>
<entry>using-direct-buffers</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>true, false</entry>
<entry>When using NIO, whether or not the tcp adapter uses direct buffers.
Refer to java.nio.ByteBuffer documentation for more information.</entry>
</row>
<row>
<entry>message-format</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>length-header, stx-etx, crlf, custom</entry>
<entry>The formatting that the tcp adapter uses so the adapter can demarcate
messages. Defaults to length-header.
See the discussion above for details about each format.</entry>
</row>
<row>
<entry>custom-socket- reader-class-name</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>Subclass of TcpNetSocket- Reader or TcpNioSocket- Reader</entry>
<entry>When message-format is 'custom' the name of the class that
implements the custom format. Must be a subclass of the TcpNxxSocketReader,
depending on whether using-nio is false or true.</entry>
</row>
<row>
<entry>so-timeout</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname> and <classname>java.net.DatagramSocket</classname>
setSoTimeout() methods for more information.</entry>
</row>
<row>
<entry>so-send-buffer-size</entry>
<entry>N</entry>
<entry>Y</entry>
<entry></entry>
<entry>Used for udp acknowlegment packets. See <classname>java.net.DatagramSocket</classname>
setSendBufferSize() methods for more information.</entry>
</row>
<row>
<entry>so-receive-buffer- size</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname> and <classname>java.net.DatagramSocket</classname>
setReceiveBufferSize() for more information.</entry>
</row>
<row>
<entry>so-keep-alive</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>true, false</entry>
<entry>See <classname>java.net.Socket. setKeepAlive()</classname>.</entry>
</row>
</tbody>
</tgroup>
</table>
<table id="tcp-ib-gateway-attributes">
<title>TCP Inbound Gateway Attributes</title>
<tgroup cols="3">
<colspec align="left" />
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col4" colwidth="1*"/>
<colspec colnum="3" colname="col5" colwidth="3*"/>
<thead>
<row>
<entry align="center">Attribute Name</entry>
<entry align="left">Allowed Values</entry>
<entry align="center">Attribute Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>port</entry>
<entry></entry>
<entry>The port on which the gateway listens.</entry>
</row>
<row>
<entry>pool-size</entry>
<entry></entry>
<entry>Specifies the number of concurrent connections supported
by the gateway.</entry>
</row>
<row>
<entry>receive-buffer-size</entry>
<entry></entry>
<entry>The size of the
buffer used to reassemble incoming messages. Effectively the maximum
message size that can be received.</entry>
</row>
<row>
<entry>message-format</entry>
<entry>length-header, stx-etx, crlf, custom</entry>
<entry>The formatting that the tcp gateway uses for demarcating
incoming requests and formatting responses. Defaults to length-header.
See the discussion above for details about each format.</entry>
</row>
<row>
<entry>custom-socket- reader-class-name</entry>
<entry>Subclass of TcpNetSocket- Reader</entry>
<entry>When message-format is 'custom' the name of the class that
implements the custom format. Must be a subclass of the
TcpNetSocketReader.</entry>
</row>
<row>
<entry>custom-socket- writer-class-name</entry>
<entry>Subclass of TcpNetSocket- Writer</entry>
<entry>When message-format is 'custom' the name of the class that
implements the custom format. Must be a subclass of the
TcpNetSocketWriter.</entry>
</row>
<row>
<entry>so-timeout</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname>
setSoTimeout() for more information.</entry>
</row>
<row>
<entry>so-send-buffer-size</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname>
setSendBufferSize() methods for more information.</entry>
</row>
<row>
<entry>so-receive-buffer- size</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname>
setReceiveBufferSize() for more information.</entry>
</row>
<row>
<entry>so-keep-alive</entry>
<entry>true, false</entry>
<entry>See <classname>java.net.Socket. setKeepAlive()</classname>.</entry>
</row>
</tbody>
</tgroup>
</table>
<table id="tcp-ob-gateway-attributes">
<title>TCP Outbound Gateway Attributes</title>
<tgroup cols="3">
<colspec align="left" />
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col4" colwidth="1*"/>
<colspec colnum="3" colname="col5" colwidth="3*"/>
<thead>
<row>
<entry align="center">Attribute Name</entry>
<entry align="left">Allowed Values</entry>
<entry align="center">Attribute Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>host</entry>
<entry></entry>
<entry>The host name or ip address of the destination.</entry>
</row>
<row>
<entry>port</entry>
<entry></entry>
<entry>The port to which the gateway connects.</entry>
</row>
<row>
<entry>receive-buffer-size</entry>
<entry></entry>
<entry>The size of the
buffer used to reassemble incoming messages. Effectively the maximum
message size that can be received.</entry>
</row>
<row>
<entry>message-format</entry>
<entry>length-header, stx-etx, crlf, custom</entry>
<entry>The formatting that the tcp gateway uses for formating
requests and demarcating
incoming responses. Defaults to length-header.
See the discussion above for details about each format.</entry>
</row>
<row>
<entry>custom-socket- reader-class-name</entry>
<entry>Subclass of TcpNetSocket- Reader</entry>
<entry>When message-format is 'custom' the name of the class that
implements the custom format. Must be a subclass of the
TcpNetSocketReader.</entry>
</row>
<row>
<entry>custom-socket- writer-class-name</entry>
<entry>Subclass of TcpNetSocket- Writer</entry>
<entry>When message-format is 'custom' the name of the class that
implements the custom format. Must be a subclass of the
TcpNetSocketWriter.</entry>
</row>
<row>
<entry>so-timeout</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname>
setSoTimeout() for more information.</entry>
</row>
<row>
<entry>so-send-buffer-size</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname>
setSendBufferSize() methods for more information.</entry>
</row>
<row>
<entry>so-receive-buffer- size</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname>
setReceiveBufferSize() for more information.</entry>
</row>
<row>
<entry>so-keep-alive</entry>
<entry>true, false</entry>
<entry>See <classname>java.net.Socket. setKeepAlive()</classname>.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
</chapter>

261
spring-integration-reference/src/jms.xml
View File

@@ -1,261 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="jms">
<title>JMS Support</title>
<para>
Spring Integration provides Channel Adapters for receiving and sending JMS messages. There are actually two
JMS-based inbound Channel Adapters. The first uses Spring's <classname>JmsTemplate</classname> to receive based on
a polling period. The second is "message-driven" and relies upon a Spring MessageListener container. There is also
an outbound Channel Adapter which uses the <classname>JmsTemplate</classname> to convert and send a JMS Message on
demand.
</para>
<para>
Whereas the JMS Channel Adapters are intended for unidirectional Messaging (send-only or receive-only), Spring
Integration also provides inbound and outbound JMS Gateways for request/reply operations. The inbound gateway
relies on one of Spring's MessageListener container implementations for Message-driven reception that is also
capable of sending a return value to the "reply-to" Destination as provided by the received Message. The outbound
Gateway sends a JMS Message to a "request-destination" and then receives a reply Message. The "reply-destination"
reference (or "reply-destination-name") can be configured explicitly or else the outbound gateway will use a
JMS TemporaryQueue.
</para>
<section id="jms-inbound-channel-adapter">
<title>Inbound Channel Adapter</title>
<para>
The inbound Channel Adapter requires a reference to either a single <classname>JmsTemplate</classname>
instance or both <interfacename>ConnectionFactory</interfacename> and <interfacename>Destination</interfacename>
(a 'destinationName' can be provided in place of the 'destination' reference). The following example defines an
inbound Channel Adapter with a <classname>Destination</classname> reference.
<programlisting language="xml"><![CDATA[ <jms:inbound-channel-adapter id="jmsIn" destination="inQueue" channel="exampleChannel">
<integration:poller>
<integration:interval-trigger interval="30" time-unit="SECONDS"/>
</integration:poller>
</jms:inbound-channel-adapter>]]></programlisting>
<tip>
Notice from the configuration that the inbound-channel-adapter is a Polling Consumer. That means that
it invokes receive() when triggered. This should only be used in situations where polling is done relatively
infrequently and timeliness is not important. For all other situations (a vast majority of JMS-based use-cases),
the <emphasis>message-driven-channel-adapter</emphasis> described below is a better option.
</tip>
<note>
All of the JMS adapters that require a reference to the ConnectionFactory will automatically look for
a bean named "connectionFactory" by default. That is why you don't see a "connection-factory" attribute
in many of the examples. However, if your JMS ConnectionFactory has a different bean name, then you will
need to provide that attribute.
</note>
</para>
<para>
If 'extract-payload' is set to true (which is the default), the received JMS Message will be passed through
the MessageConverter. When relying on the default SimpleMessageConverter, this means that the resulting Spring
Integration Message will have the JMS Message's body as its payload. A JMS TextMessage will produce a
String-based payload, a JMS BytesMessage will produce a byte array payload, and a JMS ObjectMessage's
Serializable instance will become the Spring Integration Message's payload. If instead you prefer to have
the raw JMS Message as the Spring Integration Message's payload, then set 'extract-payload' to false.
<programlisting language="xml"><![CDATA[ <jms:inbound-channel-adapter id="jmsIn"
destination="inQueue"
channel="exampleChannel"
extract-payload="false"/>
<integration:poller>
<integration:interval-trigger interval="30" time-unit="SECONDS"/>
</integration:poller>
</jms:inbound-channel-adapter>]]></programlisting>
</para>
</section>
<section id="jms-message-driven-channel-adapter">
<title>Message-Driven Channel Adapter</title>
<para>
The "message-driven-channel-adapter" requires a reference to either an instance of a Spring MessageListener
container (any subclass of <classname>AbstractMessageListenerContainer</classname>) or both
<interfacename>ConnectionFactory</interfacename> and <interfacename>Destination</interfacename>
(a 'destinationName' can be provided in place of the 'destination' reference). The following example defines a
message-driven Channel Adapter with a <classname>Destination</classname> reference.
<programlisting language="xml"><![CDATA[ <jms:message-driven-channel-adapter id="jmsIn" destination="inQueue" channel="exampleChannel"/>]]></programlisting>
<note>
The Message-Driven adapter also accepts several properties that pertain to the MessageListener container.
These values are only considered if you do not provide an actual 'container' reference. In that case,
an instance of DefaultMessageListenerContainer will be created and configured based on these properties.
For example, you can specify the "transaction-manager" reference, the "concurrent-consumers" value, and
several other property references and values. Refer to the JavaDoc and Spring Integration's JMS Schema
(spring-integration-jms-1.0.xsd) for more detail.
</note>
</para>
<para>
The 'extract-payload' property has the same effect as described above, and once again its default value
is 'true'. The poller sub-element is not applicable for a message-driven
Channel Adapter, as it will be actively invoked. For most usage scenarios, the message-driven approach is better since the Messages will
be passed along to the <interfacename>MessageChannel</interfacename> as soon as they are received from the underlying
JMS consumer.
</para>
</section>
<section id="jms-outbound-channel-adapter">
<title>Outbound Channel Adapter</title>
<para>
The <classname>JmsSendingMessageHandler</classname> implements the <interfacename>MessageHandler</interfacename>
interface and is capable of converting Spring Integration <interfacename>Messages</interfacename> to JMS messages
and then sending to a JMS destination. It requires either a 'jmsTemplate' reference or both 'connectionFactory' and
'destination' references (again, the 'destinationName' may be provided in place of the 'destination'). As with the
inbound Channel Adapter, the easiest way to configure this adapter is with the namespace support. The following
configuration will produce an adapter that receives Spring Integration Messages from the "exampleChannel" and then
converts those into JMS Messages and sends them to the JMS Destination reference whose bean name is "outQueue".
<programlisting language="xml"><![CDATA[<jms:outbound-channel-adapter id="jmsOut" destination="outQueue" channel="exampleChannel"/>]]></programlisting>
</para>
<para>
As with the inbound Channel Adapters, there is an 'extract-payload' property. However, the meaning is reversed
for the outbound adapter. Rather than applying to the JMS Message, the boolean property applies to the Spring
Integration Message payload. In other words, the decision is whether to pass the Spring Integration Message
<emphasis>itself</emphasis> as the JMS Message body or whether to pass the Spring Integration Message's
payload as the JMS Message body. The default value is once again 'true'. Therefore, if you pass a Spring
Integration Message whose payload is a String, a JMS TextMessage will be created. If on the other hand you
want to send the actual Spring Integration Message to another system via JMS, then simply set this to 'false'.
<note>
Regardless of the boolean value for payload extraction, the Spring Integration MessageHeaders will map to
JMS properties as long as you are relying on the default converter or provide a reference to another
instance of HeaderMappingMessageConverter (the same holds true for 'inbound' adapters except that in
those cases, it's the JMS properties mapping <emphasis>to</emphasis> Spring Integration MessageHeaders).
</note>
</para>
</section>
<section id="jms-inbound-gateway">
<title>Inbound Gateway</title>
<para>
Spring Integration's message-driven JMS inbound-gateway delegates to a
<interfacename>MessageListener</interfacename> container, supports dynamically adjusting concurrent consumers,
and can also handle replies. The inbound gateway requires references to a
<interfacename>ConnectionFactory</interfacename>, and a request <interfacename>Destination</interfacename> (or
'requestDestinationName'). The following example defines a JMS "inbound-gateway" that receives from the JMS
queue referenced by the bean id "inQueue" and sends to the Spring Integration channel named "exampleChannel".
<programlisting language="xml"><![CDATA[ <jms:inbound-gateway id="jmsInGateway"
request-destination="inQueue"
request-channel="exampleChannel"/>]]></programlisting>
</para>
<para>
Since the gateways provide request/reply behavior instead of unidirectional send <emphasis>or</emphasis>
receive, they also have two distinct properties for the "payload extraction" (as discussed above for the
Channel Adapters' 'extract-payload' setting). For an inbound-gateway, the 'extract-request-payload' property
determines whether the received JMS Message body will be extracted. If 'false', the JMS Message itself will
become the Spring Integration Message payload. The default is 'true'.
</para>
<para>
Similarly, for an inbound-gateway the 'extract-reply-payload' property applies to the Spring Integration Message
that is going to be converted into a reply JMS Message. If you want to pass the whole Spring Integration Message
(as the body of a JMS ObjectMessage) then set this to 'false'. By default, it is also 'true' such that the Spring
Integration Message <emphasis>payload</emphasis> will be converted into a JMS Message (e.g. String payload
becomes a JMS TextMessage).
</para>
</section>
<section id="jms-outbound-gateway">
<title>Outbound Gateway</title>
<para>
The outbound Gateway creates JMS Messages from Spring Integration Messages and then sends to a
'request-destination'. It will then handle the JMS reply Message either by using a selector to
receive from the 'reply-destination' that you configure, or if no 'reply-destination' is provided,
it will create JMS TemporaryQueues. Notice that the "reply-channel" is also provided.
<programlisting language="xml"><![CDATA[ <jms:outbound-gateway id="jmsOutGateway"
request-destination="outQueue"
request-channel="outboundJmsRequests"
reply-channel="jmsReplies"/>]]></programlisting>
</para>
<para>
The 'outbound-gateway' payload extraction properties are inversely related to those of the
'inbound-gateway' (see the discussion above). That means that the 'extract-request-payload' property value
applies to the Spring Integration Message that is being converted into a JMS Message to be
<emphasis>sent as a request</emphasis>, and the 'extract-reply-payload' property value applies to the
JMS Message that is <emphasis>received as a reply</emphasis> and then converted into a Spring Integration
Message to be subsequently sent to the 'reply-channel' as shown in the example configuration above.
<note>
For all of these JMS adapters, you can also specify your own "message-converter" reference. Simply provide the
bean name of an instance of <interfacename>MessageConverter</interfacename> that is available within the same
ApplicationContext. Note, however, that when you provide your own MessageConverter instance, it will still
be wrapped within the HeaderMappingMessageConverter. This means that the 'extract-request-payload'
and 'extract-reply-payload' properties may effect what actual objects are passed to your converter. The
HeaderMappingMessageConverter itself simply delegates to a target MessageConverter while also mapping the
Spring Integration MessageHeaders to JMS Message properties and vice-versa.
</note>
</para>
</section>
<section id="jms-channel">
<title>JMS Backed Message Channels</title>
<para>
The Channel Adapters and Gateways featured above are all intended for applications that are integrating
with other external systems. The inbound options assume that some other system is sending JMS Messages
to the JMS Destination and the outbound options assume that some other system is receiving from the
Destination. The other system may or may not be a Spring Integration application. Of course, when sending
the Spring Integration Message instance as the body of the JMS Message itself (with the 'extract-payload'
value set to false), it is assumed that the other system is based on Spring Integration. However,
that is by no means a requirement. That flexibility is one of the benefits of using a Message-based
integration option with the abstraction of "channels" or Destinations in the case of JMS.
</para>
<para>
There are cases where both the producer and consumer for a given JMS Destination are intended to be
part of the same application, running within the same process. This could be accomplished by using a
pair of inbound and outbound Channel Adapters. The problem with that approach is that two adapters are
required even though conceptually the goal is to have a single Message Channel. A better option is
supported as of Spring Integration version 2.0. Now it is possible to define a single "channel" when
using the JMS namespace.
<programlisting language="xml"><![CDATA[ <jms:channel id="jmsChannel" queue="exampleQueue"/>]]></programlisting>
</para>
<para>
The channel in the above example will behave much like a normal &lt;channel/&gt; element from the main
Spring Integration namespace. It can be referenced by both "input-channel" and "output-channel" attributes
of any endpoint. The difference is that this channel is backed by a JMS Queue instance named "exampleQueue".
This means that asynchronous messaging is possible between the producing and consuming endpoints, but
unlike the simpler asynchronous Message Channels created by adding a &lt;queue/&gt; sub-element within a
non-JMS &lt;channel/&gt; element, the Messages are not just stored in an in-memory queue. Instead those
Messages are passed within a JMS Message body, and the full power of the underlying JMS provider is then
available for that channel. Probably the most common rationale for using this alternative would be to
take advantage of the persistence made available by the <emphasis>store and forward</emphasis> approach
of JMS messaging. If configured properly, the JMS-backed Message Channel also supports transactions.
In other words, a producer would not actually write to a transactional JMS-backed channel if its send
operation is part of a transaction that rolls back. Likewise, a consumer would not physically remove a
JMS Message from the channel if the reception of that Message is part of a transaction that rolls back.
Note that the producer and consumer transactions are separate in such a scenario. This is significantly
different than the propagation of a transactional context across the simple, synchronous &lt;channel/&gt;
element that has no &lt;queue/&gt; sub-element.
</para>
<para>
Since the example above is referencing a JMS Queue instance, it will act as a point-to-point channel. If
on the other hand, publish/subscribe behavior is needed, then a separate element can be used, and a JMS
Topic can be referenced instead.
<programlisting language="xml"><![CDATA[ <jms:publish-subscribe-channel id="jmsChannel" topic="exampleTopic"/>]]></programlisting>
</para>
<para>
For either type of JMS-backed channel, the name of the destination may be provided instead of a reference.
<programlisting language="xml"><![CDATA[ <jms:channel id="jmsQueueChannel" queue-name="exampleQueueName"/>
<jms:publish-subscribe-channel id="jmsTopicChannel" topic-name="exampleTopicName"/>]]></programlisting>
</para>
<para>
In the examples above, the Destination names would be resolved by Spring's default
<classname>DynamicDestinationResolver</classname> implementation, but any implementation of the
<interfacename>DestinationResolver</interfacename> interface could be provided. Also, the JMS
<interfacename>ConnectionFactory</interfacename> is a required property of the channel, but by default
the expected bean name would be "connectionFactory". The example below provides both a custom instance
for resolution of the JMS Destination names and a different name for the ConnectionFactory.
<programlisting language="xml"><![CDATA[ <jms:channel id="jmsChannel" queue-name="exampleQueueName"
destination-resolver="customDestinationResolver"
connection-factory="customConnectionFactory"/>]]></programlisting>
</para>
</section>
<section id="jms-samples">
<title>JMS Samples</title>
<para>
To experiment with these JMS adapters, check out the samples available within the "samples/jms" directory in
the distribution. There are two samples included. One provides inbound and outbound Channel Adapters, and the
other provides inbound and outbound Gateways. They are configured to run with an embedded ActiveMQ process, but
the "common.xml" file can easily be modified to support either a different JMS provider or a standalone
ActiveMQ process. In other words, you can split the configuration so that the inbound and outbound adapters are
running in separate JVMs. If you have ActiveMQ installed, simply modify the "brokerURL" property within the
configuration to use "tcp://localhost:61616" for example (instead of "vm://localhost"). Both of the samples
accept input via stdin and then echo back to stdout. Look at the configuration to see how these messages are
routed over JMS.
</para>
</section>
</chapter>

175
spring-integration-reference/src/jmx.xml
View File

@@ -1,175 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="jmx">
<title>JMX Support</title>
<para>
Spring Integration provides Channel Adapters for receiving and publishing JMX Notifications.
There is also an inbound Channel Adapter for polling JMX MBean attribute values, and an
outbound Channel Adapter for invoking JMX MBean operations.
</para>
<section id="jmx-notification-listening-channel-adapter">
<title>Notification Listening Channel Adapter</title>
<para>
The Notification-listening Channel Adapter requires a JMX ObjectName for the MBean that publishes
Notifications to which this listener should be registered. A very simple configuration might look like this:
<programlisting language="xml"><![CDATA[ <jmx:notification-listening-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"/>
]]></programlisting>
<tip>
The notification-listening-channel-adapter registers with an MBeanServer at startup, and
the default bean name is "mbeanServer" which happens to be the same bean name generated
when using Spring's &lt;context:mbean-server/&gt; element. If you need to use a different
name be sure to include the "mbean-server" attribute.
</tip>
The adapter can also accept a reference to a NotificationFilter and a "handback" Object
to provide some context that is passed back with each Notification. Both of those attributes
are optional. Extending the above example to include those attributes as well as an explicit
MBeanServer bean name would produce the following:
<programlisting language="xml"><![CDATA[ <jmx:notification-listening-channel-adapter id="adapter"
channel="channel"
mbean-server="someServer"
object-name="example.domain:name=somePublisher"
notification-fliter="notificationFilter"
handback="myHandback"/>
]]></programlisting>
Since the notification-listening adapter is registered with the MBeanServer directly, it is
event-driven and does not require any poller configuration.
</para>
</section>
<section id="jmx-notification-publishing-channel-adapter">
<title>Notification Publishing Channel Adapter</title>
<para>
The Notification-publishing Channel Adapter is relatively simple. It only requires a
JMX ObjectName in its configuration as shown below.
<programlisting language="xml"><![CDATA[ <context:mbean:export/>
<jmx:notification-publishing-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"/>
]]></programlisting>
It does also require that an MBeanExporter be present in the context. That is why the
&lt;context:mbean-export/&gt; element is shown above as well.
</para>
<para>
When Messages are sent to the channel for this adapter, the Notification
is created from the Message content. If the payload is a String it will be
passed as the "message" text for the Notification. Any other payload type
will be passed as the "userData" of the Notification.
</para>
<para>
JMX Notifications also have a "type", and it should be a dot-delimited String.
There are two ways to provide the type. Precedence will always be given to a
Message header value associated with the JmxHeaders.NOTIFICATION_TYPE key.
On the other hand, you can rely on a fallback "default-notification-type"
attribute provided in the configuration.
<programlisting language="xml"><![CDATA[ <context:mbean:export/>
<jmx:notification-publishing-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=publisher"
default-notification-type="some.default.type"/>
]]></programlisting>
</para>
</section>
<section id="jmx-attribute-polling-channel-adapter">
<title>Attribute Polling Channel Adapter</title>
<para>
The attribute polling adapter is useful when you have a requirement to periodically
check on some value that is available through an MBean as a managed attribute. The
poller can be configured in the same way as any other polling adapter in Spring
Integration (or it's possible to rely on the default poller). The "object-name"
and "attribute-name" are required. An MBeanServer reference is also required, but
it will automatically check for a bean named "mbeanServer" by default just like
the notification-listening-channel-adapter described above.
<programlisting language="xml"><![CDATA[ <jmx:attribute-polling-channel-adapter id="adapter"
channel="channel"
object-name="example.domain:name=someService"
attribute-name="InvocationCount">
<si:poller max-messages-per-poll="1">
<si:interval-trigger interval="5000"/>
</si:poller>
</jmx:attribute-polling-channel-adapter>
]]></programlisting>
</para>
</section>
<section id="jmx-operation-invoking-channel-adapter">
<title>Operation Invoking Channel Adapter</title>
<para>
The operation-invoking-channel-adapter enables Message-driven invocation of
any managed operation exposed by an MBean. Each invocation requires the
operation name to be invoked and the ObjectName of the target MBean. In each
case, the adapter will first check for header values on the Message itself.
The keys for these headers are defined as JmxHeaders.OPERATION_NAME and
JmxHeaders.OBJECT_NAME, respectively. If relying on those Message headers,
the configuration is trivial.
<programlisting language="xml"><![CDATA[ <jmx:operation-invoking-channel-adapter id="adapter"/>
]]></programlisting>
That adapter only needs to be able to discover the "mbeanServer" bean. If
a different bean name is required, then provide the "mbean-server" attribute
with a reference.
</para>
<para>
The payload of the Message will be mapped to the parameters of the operation, if any.
A Map-typed payload with String keys is treated as name/value pairs whereas a List or
array would be passed as a simple argument list (with no explicit parameter names).
If the operation requires a single parameter value, then the payload can represent
that single value, and if the operation requires no parameters, then the payload
would be ignored.
</para>
<para>
Similar to the behavior described above for the Notification type resoltion,
the operation-invoking-channel-adapter will also fallback to default values if
provided:
<programlisting language="xml"><![CDATA[ <jmx:operation-invoking-channel-adapter id="adapter"
default-object-name="example.domain:name=TestBean"
default-operation-name="ping"/>
]]></programlisting>
If you want to expose a channel for a single common operation to be invoked
by Messages that need not contain headers, then that option works well.
</para>
</section>
<section id="jmx-control-bus">
<title>Control Bus</title>
<para>
Spring Integration components themselves may be exposed as MBeans when the Control Bus
is configured. As described in (<ulink url="http://www.eaipatterns.com/ControlBus.html">EIP</ulink>),
the idea behind the Control Bus is that the same messaging system can be used for monitoring
and managing the components within the framework as is used for "application-level" messaging.
In Spring Integration we build upon the adapters described above so that it's possible to
send Messages as a means of invoking exposed operations. Internally, the Control Bus uses
a Spring MBeanExporter instance to expose the various endpoints and channels. To create
an instance of the Control Bus, define a bean and provide a reference to an MBeanServer
and a domain name (we will be providing namespace support). The domain can be left out
in which case the default domain is "org.springframework.integration".
<programlisting language="xml"><![CDATA[ <bean id="controlBus" class="org.springframework.integration.control.ControlBus">
<constructor-arg ref="mbeanServer"/>
<constructor-arg value="example.domain"/>
</bean>
<bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean">
<property name="locateExistingServerIfPossible" value="true"/>
</bean>
]]></programlisting>
</para>
<para>
The Control Bus has an "operationChannel" that can be accessed for invoking operations
on the MBeans that it has exported. This will also be covered by namespace support soon
to make it easier to configure references to that channel for other producers. We will
likely add some other channels for notifications and attribute polling as well.
</para>
<para>
The Control Bus functionality is a work in progress. At this time, one can perform some
basic monitoring of Message Channels and/or invoke Lifecycle operations (start/stop) on
Message Endpoints. Now that the foundation is available, however, we will be able to extend
the attributes and operations that are being exposed.
</para>
</section>
</chapter>

121
spring-integration-reference/src/mail.xml
View File

@@ -1,121 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="mail">
<title>Mail Support</title>
<section id="mail-outbound">
<title>Mail-Sending Channel Adapter</title>
<para>
Spring Integration provides support for outbound email with the
<classname>MailSendingMessageHandler</classname>. It delegates to a configured instance of Spring's
<interfacename>JavaMailSender</interfacename>:
<programlisting language="java"> JavaMailSender mailSender = (JavaMailSender) context.getBean("mailSender");
MailSendingMessageHandler mailSendingHandler = new MailSendingMessageHandler(mailSender);</programlisting>
<classname>MailSendingMessageHandler</classname> has various mapping strategies that use Spring's
<interfacename>MailMessage</interfacename> abstraction. If the received Message's payload is already
a <classname>MailMessage</classname> instance, it will be sent directly.
Therefore, it is generally recommended to precede this
consumer with a Transformer for non-trivial MailMessage construction requirements. However, a few simple
Message mapping strategies are supported out-of-the-box. For example, if the message payload is a byte array,
then that will be mapped to an attachment. For simple text-based emails, you can provide a String-based
Message payload. In that case, a MailMessage will be created with that String as the text content. If you
are working with a Message payload type whose toString() method returns appropriate mail text content, then
consider adding Spring Integration's <emphasis>ObjectToStringTransformer</emphasis> prior to the outbound
Mail adapter (see the example within <xref linkend="transformer-namespace"/> for more detail).
</para>
<para>
The outbound MailMessage may also be configured with certain values from the
<classname>MessageHeaders</classname>. If available, values will be mapped to the outbound mail's
properties, such as the recipients (TO, CC, and BCC), the from/reply-to, and the subject. The header names are
defined by the following constants:
<programlisting language="java"> MailHeaders.SUBJECT
MailHeaders.TO
MailHeaders.CC
MailHeaders.BCC
MailHeaders.FROM
MailHeaders.REPLY_TO</programlisting>
</para>
<note>
<classname>MailHeaders</classname> also allows you to override corresponding <classname>MailMessage</classname> values.
For example: If <classname>MailMessage.to</classname> is set to 'foo@bar.com' and <classname>MailHeaders.TO</classname>
Message header is provided it will take precedence and override the corresponding value in <classname>MailMessage</classname>
</note>
</section>
<section id="mail-inbound">
<title>Mail-Receiving Channel Adapter</title>
<para>
Spring Integration also provides support for inbound email with the
<classname>MailReceivingMessageSource</classname>. It delegates to a configured instance of Spring
Integration's own <interfacename>MailReceiver</interfacename> interface, and there are two implementations:
<classname>Pop3MailReceiver</classname> and <classname>ImapMailReceiver</classname>. The easiest way to
instantiate either of these is by passing the 'uri' for a Mail store to the receiver's constructor. For example:
<programlisting language="java"><![CDATA[ MailReceiver receiver = new Pop3MailReceiver("pop3://usr:pwd@localhost/INBOX");
]]></programlisting>
</para>
<para>
Another option for receiving mail is the IMAP "idle" command (if supported by the mail server you are using).
Spring Integration provides the <classname>ImapIdleChannelAdapter</classname> which is itself a Message-producing
endpoint. It delegates to an instance of the <classname>ImapMailReceiver</classname> but enables asynchronous
reception of Mail Messages. There are examples in the next section of configuring both types of inbound Channel
Adapter with Spring Integration's namespace support in the 'mail' schema.
</para>
</section>
<section id="mail-namespace">
<title>Mail Namespace Support</title>
<para>
Spring Integration provides a namespace for mail-related configuration. To use it, configure the following schema
locations.<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:mail="http://www.springframework.org/schema/integration/mail"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/integration/mail
http://www.springframework.org/schema/integration/mail/spring-integration-mail-1.0.xsd">]]></programlisting>
</para>
<para>
To configure an outbound Channel Adapter, provide the channel to receive from, and the MailSender:
<programlisting language="xml"><![CDATA[<mail:outbound-channel-adapter channel="outboundMail"
mail-sender="mailSender"/>]]></programlisting>
Alternatively, provide the host, username, and password:
<programlisting language="xml"><![CDATA[<mail:outbound-channel-adapter channel="outboundMail"
host="somehost" username="someuser" password="somepassword"/>]]></programlisting>
<note>
Keep in mind, as with any outbound Channel Adapter, if the referenced channel is a PollableChannel, a
&lt;poller&gt; sub-element should be provided with either an interval-trigger or cron-trigger.
</note>
</para>
<para>
To configure an inbound Channel Adapter, you have the choice between polling or event-driven (assuming your
mail server supports IMAP IDLE - if not, then polling is the only option). A polling Channel Adapter simply
requires the store URI and the channel to send inbound Messages to. The URI may begin with "pop3" or "imap":
<programlisting language="xml"><![CDATA[ <mail:inbound-channel-adapter channel="mailIn"
store-uri="imap://usr:pwd@imap.example.com/INBOX">
<poller max-messages-per-poll="3">
<interval-trigger interval="30" time-unit="SECONDS"/>
</poller>
</mail:inbound-channel-adapter>]]></programlisting>
If you do have IMAP idle support, then you may want to configure the "imap-idle-channel-adapter" element instead.
Since the "idle" command enables event-driven notifications, no poller is necessary for this adapter. It will
send a Message to the specified channel as soon as it receives the notification that new mail is available:
<programlisting language="xml"><![CDATA[ <mail:imap-idle-channel-adapter channel="mailIn"
store-uri="imaps://usr:pwd@imap.example.com:993/INBOX"/>]]></programlisting>
</para>
<para>
When using the namespace support, a <emphasis>header-enricher</emphasis> Message Transformer is also available.
This simplifies the application of the headers mentioned above to any Message prior to sending to the
Mail-sending Channel Adapter.
<programlisting language="xml"><![CDATA[<mail:header-enricher subject="Example Mail"
to="to@example.org"
cc="cc@example.org"
bcc="bcc@example.org"
from="from@example.org"
reply-to="replyTo@example.org"
overwrite="false"/>]]></programlisting>
</para>
</section>
</chapter>

151
spring-integration-reference/src/message-publishing.xml
View File

@@ -1,151 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="message-publishing">
<title>Message Publishing</title>
<para>
Message Publishing feature will allow you to send a message as a result of method invocation. For example; Imagine you
have a component and every time the state of this components changes you would like to get notified. The easiest
way to send notification would be to send a message to a dedicated channel, but how would you connect the method invocation that
changes the state of the object to a message sending process and what should be the structure of the
message? Message Publishing feature will allow you to do just that.
</para>
<section id="message-publishing-config">
<title>Message Publishing Configuration</title>
<para>
Spring Integration provides two approaches - XML and Annotation.
</para>
<section id="publisher-annotation">
<title>Annotation-based approach via @Publisher annotation</title>
<para>
Annotation bassed approach allows you to annotate any method with <interfacename>@Publisher</interfacename> annotation and
provide configuration attributes which will dictate the structure of a <emphasis>Message</emphasis>. Invocation of such
method will be proxied through <classname>PublisherAnnotationAdvisor</classname> which will
construct a <emphasis>Message</emphasis> and send it to a <emphasis>channel</emphasis>.
</para>
<para>
Internally <classname>PublisherAnnotationAdvisor</classname> uses Spring 3.0 Expression Language support giving you
the flexibility and control over the structure of a <emphasis>Message</emphasis> it will build.
</para>
<para>
<classname>PublisherAnnotationAdvisor</classname> defines and binds the following variables:
<itemizedlist>
<listitem>
<para><emphasis>#return</emphasis> - will bind to a return value allowing you to reference it or its
attributes (e.g., <emphasis>#return.foo</emphasis> where 'foo' is an attribute of the object bound to
<emphasis>#return</emphasis>)</para>
</listitem>
<listitem>
<para><emphasis>#exception</emphasis> - will bind to an exception if one is thrown.</para>
</listitem>
<listitem>
<para><emphasis>#[parameName]</emphasis> - will be dynamically constructed pointing to the method parameter
names (e.g., <emphasis>#fname</emphasis> as in the above method)</para>
</listitem>
</itemizedlist>
</para>
<para>
<programlisting language="java">@Publisher(value="#return", channel="testChannel", headers="bar='123',fname=#fname")
public String setName(String fname, String lname){
return fname + " " + lname;
}</programlisting>
</para>
<para>
In the above example the Message will be constructed and its structure will be as follows:
<itemizedlist>
<listitem>
<para>Message payload - will be of type String and contain the value returned by the method.</para>
</listitem>
<listitem>
<para>Message headers will be 'bar' with value of "123" and 'fname' with value of 'fname' parameter of the method.</para>
</listitem>
</itemizedlist>
</para>
<para>
As with any other annotation you will need to register <classname>PublisherAnnotationBeanPostProcessor</classname>
<programlisting language="xml">&lt;bean class="org.springframework.integration.aop.PublisherAnnotationBeanPostProcessor"/&gt;</programlisting>
</para>
</section>
<section id="aop-based-interceptor">
<title>XML-based approach via &lt;publisher&gt; element</title>
<para>
XML-based approach allows you to configure Message Publishing via AOP-based configuration and
simple namespace-based configuration of <classname>MessagePublishingInterceptor</classname>.
It certainly has certain benefits over annotation based approach since it
allows you to use AOP pointcut expressions, thus possibly intercepting multiple methods at once or
intercepting and publishing methods to which you don't have a source code.
</para>
<para>
To configure Message Publishing via XML all you need is the following two things:
<itemizedlist>
<listitem>
<para>Provide configuration for <classname>MessagePublishingInterceptor</classname>
via <code>&lt;publisher&gt;</code> XML element</para>
</listitem>
<listitem>
<para>Provide AOP configuration to apply <classname>MessagePublishingInterceptor</classname></para>
</listitem>
</itemizedlist>
</para>
<para>
<programlisting language="xml">
&lt;beans:bean id="testBean" class="org.foo.bar.TestBean" /&gt;
&lt;aop:config&gt;
&lt;aop:advisor advice-ref="interceptor" pointcut="bean(testBean)" /&gt;
&lt;/aop:config&gt;
&lt;publisher id="interceptor" default-channel="defaultChannel"&gt;
&lt;method pattern="echo" payload="'Echoing: ' + #return" headers="foo='bar'" channel="echoChannel"/&gt;
&lt;method pattern="echoDef*" payload="#return"/&gt;
&lt;method pattern="foo*"/&gt;
&lt;/publisher&gt;
</programlisting>
</para>
<para>
As you can see <code>&lt;publisher&gt;</code> uses the same variables as
<classname>PublisherAnnotationAdvisor</classname> to utilize the power of Spring 3.0 Expression Langage.
</para>
<para>
In the above example the execution of <code>echo</code> method of a <code>testBean</code> will
rander the <emphasis>Message</emphasis> with the following structure:
<itemizedlist>
<listitem>
<para>Message payload - will be of type String and value of "Echoing: [value]" where <code>value</code> is the value
returned by an executed method.</para>
</listitem>
<listitem>
<para>Message headers will be 'foo' with value of "bar".</para>
</listitem>
<listitem>
<para>Message will be sent to <code>echoChannel</code>.</para>
</listitem>
</itemizedlist>
</para>
<para>
In the second method mapping the execution of any method that begins with <code>echoDef</code> of <code>testBean</code> will result in the
Message with the following structure.
<itemizedlist>
<listitem>
<para>Message payload - will be the value
returned by an executed method.</para>
</listitem>
<listitem>
<para>Since <code>channel</code> attriute is not provided, the Message will be sent to the
<code>defaultChannel</code> defined by the <emphasis>publisher</emphasis>.</para>
</listitem>
</itemizedlist>
</para>
<para>
The third mapping is almost identical to the previous (with the exceptipon of method pattern),
since the return value will be mapped to the Message paylad by default if nothing else is specifued.
</para>
<para>
For a simple maping rules you can rely on <emphasis>publisher</emphasis> defaults. For example:
<programlisting language="xml">
&lt;publisher id="anotherInterceptor"/&gt;
</programlisting>
This will map the return value of every method that matches the pointcut expression to a payload and will be sent to a <emphasis>default-channel</emphasis>.
If the <emphasis>defaultChannel</emphasis>is not specified (as above) the messages will be sent to <emphasis>nullChannel</emphasis>
</para>
</section>
</section>
</chapter>

222
spring-integration-reference/src/message.xml
View File

@@ -1,222 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="message">
<title>Message Construction</title>
<para>
The Spring Integration <interfacename>Message</interfacename> is a generic container for data. Any object can
be provided as the payload, and each <interfacename>Message</interfacename> also includes headers containing
user-extensible properties as key-value pairs.
</para>
<section id="message-interface">
<title>The Message Interface</title>
<para>Here is the definition of the <interfacename>Message</interfacename> interface:
<programlisting language="java">public interface Message&lt;T&gt; {
T getPayload();
MessageHeaders getHeaders();
}</programlisting>
</para>
<para>
The <interfacename>Message</interfacename> is obviously a very important part of the API. By encapsulating the
data in a generic wrapper, the messaging system can pass it around without any knowledge of the data's type. As
an application evolves to support new types, or when the types themselves are modified and/or extended, the
messaging system will not be affected by such changes. On the other hand, when some component in the messaging
system <emphasis>does</emphasis> require access to information about the <interfacename>Message</interfacename>,
such metadata can typically be stored to and retrieved from the metadata in the Message Headers.
</para>
</section>
<section id="message-headers">
<title>Message Headers</title>
<para>
Just as Spring Integration allows any Object to be used as the payload of a Message, it also supports any Object
types as header values. In fact, the <classname>MessageHeaders</classname> class implements the
<emphasis>java.util.Map</emphasis> interface:
<programlisting language="java">public final class MessageHeaders implements Map&lt;String, Object&gt;, Serializable {
...
}</programlisting>
<note>
Even though the MessageHeaders implements Map, it is effectively a read-only implementation. Any attempt to
<emphasis>put</emphasis> a value in the Map will result in an <classname>UnsupportedOperationException</classname>.
The same applies for <emphasis>remove</emphasis> and <emphasis>clear</emphasis>. Since Messages may be passed to
multiple consumers, the structure of the Map cannot be modified. Likewise, the Message's payload Object can not
be <emphasis>set</emphasis> after the initial creation. However, the mutability of the header values themselves
(or the payload Object) is intentionally left as a decision for the framework user.
</note>
</para>
<para>
As an implementation of Map, the headers can obviously be retrieved by calling <methodname>get(..)</methodname>
with the name of the header. Alternatively, you can provide the expected <emphasis>Class</emphasis> as an
additional parameter. Even better, when retrieving one of the pre-defined values, convenient getters are
available. Here is an example of each of these three options:
<programlisting language="java"> Object someValue = message.getHeaders().get("someKey");
CustomerId customerId = message.getHeaders().get("customerId", CustomerId.class);
Long timestamp = message.getHeaders().getTimestamp();
</programlisting>
</para>
<para>
The following Message headers are pre-defined:
<table id="message-headers-table">
<title>Pre-defined Message Headers</title>
<tgroup cols="2">
<colspec align="left" />
<thead>
<row>
<entry align="center">Header Name</entry>
<entry align="center">Header Type</entry>
</row>
</thead>
<tbody>
<row>
<entry>ID</entry>
<entry>java.util.UUID</entry>
</row>
<row>
<entry>TIMESTAMP</entry>
<entry>java.lang.Long</entry>
</row>
<row>
<entry>EXPIRATION_DATE</entry>
<entry>java.lang.Long</entry>
</row>
<row>
<entry>CORRELATION_ID</entry>
<entry>java.lang.Object</entry>
</row>
<row>
<entry>REPLY_CHANNEL</entry>
<entry>java.lang.Object (can be a String or MessageChannel)</entry>
</row>
<row>
<entry>ERROR_CHANNEL</entry>
<entry>java.lang.Object (can be a String or MessageChannel)</entry>
</row>
<row>
<entry>SEQUENCE_NUMBER</entry>
<entry>java.lang.Integer</entry>
</row>
<row>
<entry>SEQUENCE_SIZE</entry>
<entry>java.lang.Integer</entry>
</row>
<row>
<entry>PRIORITY</entry>
<entry>MessagePriority (an <emphasis>enum</emphasis>)</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
Many inbound and outbound adapter implementations will also provide and/or expect certain headers, and additional
user-defined headers can also be configured.
</para>
</section>
<section id="message-implementations">
<title>Message Implementations</title>
<para>
The base implementation of the <interfacename>Message</interfacename> interface is
<classname>GenericMessage&lt;T&gt;</classname>, and it provides two constructors:
<programlisting language="java">new GenericMessage&lt;T&gt;(T payload);
new GenericMessage&lt;T&gt;(T payload, Map&lt;String, Object&gt; headers)</programlisting>
When a Message is created, a random unique id will be generated. The constructor that accepts a Map of headers
will copy the provided headers to the newly created Message.
</para>
<para>
There are also two convenient subclasses available: <classname>StringMessage</classname> and
<classname>ErrorMessage</classname>. The former accepts a String as its payload:
<programlisting language="java">StringMessage message = new StringMessage("hello world");
String s = message.getPayload();</programlisting>
And, the latter accepts any <classname>Throwable</classname> object as its payload:
<programlisting language="java">ErrorMessage message = new ErrorMessage(someThrowable);
Throwable t = message.getPayload();</programlisting>
Notice that these implementations take advantage of the fact that the <classname>GenericMessage</classname>
base class is parameterized. Therefore, as shown in both examples, no casting is necessary when retrieving
the Message payload Object.
</para>
</section>
<section id="message-builder">
<title>The MessageBuilder Helper Class</title>
<para>
You may notice that the Message interface defines retrieval methods for its payload and headers but no setters.
The reason for this is that a Message cannot be modified after its initial creation. Therefore, when a Message
instance is sent to multiple consumers (e.g. through a Publish Subscribe Channel), if one of those consumers
needs to send a reply with a different payload type, it will need to create a new Message. As a result, the
other consumers are not affected by those changes. Keep in mind, that multiple consumers may access the same
payload instance or header value, and whether such an instance is itself immutable is a decision left to the
developer. In other words, the contract for Messages is similar to that of an
<emphasis>unmodifiable Collection</emphasis>, and the MessageHeaders' map further exemplifies that; even though
the MessageHeaders class implements <interfacename>java.util.Map</interfacename>, any attempt to invoke a
<emphasis>put</emphasis> operation (or 'remove' or 'clear') on the MessageHeaders will result in an
<classname>UnsupportedOperationException</classname>.
</para>
<para>
Rather than requiring the creation and population of a Map to pass into the GenericMessage constructor, Spring
Integration does provide a far more convenient way to construct Messages: <classname>MessageBuilder</classname>.
The MessageBuilder provides two factory methods for creating Messages from either an existing Message or with a
payload Object. When building from an existing Message, the headers <emphasis>and payload</emphasis> of that
Message will be copied to the new Message:
<programlisting language="java">Message&lt;String&gt; message1 = MessageBuilder.withPayload("test")
.setHeader("foo", "bar")
.build();
Message&lt;String&gt; message2 = MessageBuilder.fromMessage(message1).build();
assertEquals("test", message2.getPayload());
assertEquals("bar", message2.getHeaders().get("foo"));</programlisting>
</para>
<para>
If you need to create a Message with a new payload but still want to copy the
headers from an existing Message, you can use one of the 'copy' methods.
<programlisting language="java">Message&lt;String&gt; message3 = MessageBuilder.withPayload("test3")
.copyHeaders(message1.getHeaders())
.build();
Message&lt;String&gt; message4 = MessageBuilder.withPayload("test4")
.setHeader("foo", 123)
.copyHeadersIfAbsent(message1.getHeaders())
.build();
assertEquals("bar", message3.getHeaders().get("foo"));
assertEquals(123, message4.getHeaders().get("foo"));</programlisting>
Notice that the <methodname>copyHeadersIfAbsent</methodname> does not overwrite existing values. Also, in the
second example above, you can see how to set any user-defined header with <methodname>setHeader</methodname>.
Finally, there are set methods available for the predefined headers as well as a non-destructive method for
setting any header (MessageHeaders also defines constants for the pre-defined header names).
<programlisting language="java">Message&lt;Integer&gt; importantMessage = MessageBuilder.withPayload(99)
.setPriority(MessagePriority.HIGHEST)
.build();
assertEquals(MessagePriority.HIGHEST, importantMessage.getHeaders().getPriority());
Message&lt;Integer&gt; anotherMessage = MessageBuilder.fromMessage(importantMessage)
.setHeaderIfAbsent(MessageHeaders.PRIORITY, MessagePriority.LOW)
.build();
assertEquals(MessagePriority.HIGHEST, anotherMessage.getHeaders().getPriority());
</programlisting>
</para>
<para>
The <classname>MessagePriority</classname> is only considered when using a <classname>PriorityChannel</classname>
(as described in the next chapter). It is defined as an <emphasis>enum</emphasis> with five possible values:
<programlisting language="java">public enum MessagePriority {
HIGHEST,
HIGH,
NORMAL,
LOW,
LOWEST
}</programlisting>
</para>
</section>
</chapter>

303
spring-integration-reference/src/overview.xml
View File

@@ -1,303 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="overview">
<title>Spring Integration Overview</title>
<section id="overview-background">
<title>Background</title>
<para>
One of the key themes of the Spring Framework is <emphasis>inversion of control</emphasis>. In its broadest
sense, this means that the framework handles responsibilities on behalf of the components that are managed within
its context. The components themselves are simplified since they are relieved of those responsibilities. For
example, <emphasis>dependency injection</emphasis> relieves the components of the responsibility of locating or
creating their dependencies. Likewise, <emphasis>aspect-oriented programming</emphasis> relieves business
components of generic cross-cutting concerns by modularizing them into reusable aspects. In each case, the end
result is a system that is easier to test, understand, maintain, and extend.
</para>
<para>
Furthermore, the Spring framework and portfolio provide a comprehensive programming model for building
enterprise applications. Developers benefit from the consistency of this model and especially the fact that it is
based upon well-established best practices such as programming to interfaces and favoring composition over
inheritance. Spring's simplified abstractions and powerful support libraries boost developer productivity while
simultaneously increasing the level of testability and portability.
</para>
<para>
Spring Integration is a new member of the Spring portfolio motivated by these same goals and principles. It
extends the Spring programming model into the messaging domain and builds upon Spring's existing enterprise
integration support to provide an even higher level of abstraction. It supports message-driven architectures
where inversion of control applies to runtime concerns, such as <emphasis>when</emphasis> certain business logic
should execute and <emphasis>where</emphasis> the response should be sent. It supports routing and transformation
of messages so that different transports and different data formats can be integrated without impacting
testability. In other words, the messaging and integration concerns are handled by the framework, so business
components are further isolated from the infrastructure and developers are relieved of complex integration
responsibilities.
</para>
<para>
As an extension of the Spring programming model, Spring Integration provides a wide variety of configuration
options including annotations, XML with namespace support, XML with generic "bean" elements, and of course direct
usage of the underlying API. That API is based upon well-defined strategy interfaces and non-invasive, delegating
adapters. Spring Integration's design is inspired by the recognition of a strong affinity between common patterns
within Spring and the well-known <ulink url="http://www.eaipatterns.com">Enterprise Integration Patterns</ulink>
as described in the book of the same name by Gregor Hohpe and Bobby Woolf (Addison Wesley, 2004). Developers who
have read that book should be immediately comfortable with the Spring Integration concepts and terminology.
</para>
</section>
<section id="overview-goalsandprinciples">
<title>Goals and Principles</title>
<para>Spring Integration is motivated by the following goals:
<itemizedlist>
<listitem>
<para>Provide a simple model for implementing complex enterprise integration solutions.</para>
</listitem>
<listitem>
<para>Facilitate asynchronous, message-driven behavior within a Spring-based application.</para>
</listitem>
<listitem>
<para>Promote intuitive, incremental adoption for existing Spring users.</para>
</listitem>
</itemizedlist>
</para>
<para>Spring Integration is guided by the following principles:
<itemizedlist>
<listitem>
<para>Components should be <emphasis>loosely coupled</emphasis> for modularity and testability.</para>
</listitem>
<listitem>
<para>The framework should enforce <emphasis>separation of concerns</emphasis> between business logic and
integration logic.</para>
</listitem>
<listitem>
<para>Extension points should be abstract in nature but within well-defined boundaries to promote
<emphasis>reuse</emphasis> and <emphasis>portability</emphasis>.</para>
</listitem>
</itemizedlist>
</para>
</section>
<section id="overview-components">
<title>Main Components</title>
<para>
From the <emphasis>vertical</emphasis> perspective, a layered architecture facilitates separation of concerns,
and interface-based contracts between layers promote loose coupling. Spring-based applications are typically
designed this way, and the Spring framework and portfolio provide a strong foundation for following this best
practice for the full-stack of an enterprise application. Message-driven architectures add a
<emphasis>horizontal</emphasis> perspective, yet these same goals are still relevant. Just as "layered
architecture" is an extremely generic and abstract paradigm, messaging systems typically follow the similarly
abstract "pipes-and-filters" model. The "filters" represent any component that is capable of producing and/or
consuming messages, and the "pipes" transport the messages between filters so that the components themselves
remain loosely-coupled. It is important to note that these two high-level paradigms are not mutually exclusive.
The underlying messaging infrastructure that supports the "pipes" should still be encapsulated in a layer whose
contracts are defined as interfaces. Likewise, the "filters" themselves would typically be managed within a layer
that is logically above the application's service layer, interacting with those services through interfaces much
in the same way that a web-tier would.
</para>
<section id="overview-components-message">
<title>Message</title>
<para>
In Spring Integration, a Message is a generic wrapper for any Java object combined with metadata used by the
framework while handling that object. It consists of a payload and headers. The payload can be of any type and
the headers hold commonly required information such as id, timestamp, expiration, and return address. Headers
are also used for passing values to and from connected transports. For example, when creating a Message from a
received File, the file name may be stored in a header to be accessed by downstream components. Likewise, if a
Message's content is ultimately going to be sent by an outbound Mail adapter, the various properties (to, from,
cc, subject, etc.) may be configured as Message header values by an upstream component. Developers can also
store any arbitrary key-value pairs in the headers.
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/message.png" format="PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="overview-components-channel">
<title>Message Channel</title>
<para>
A Message Channel represents the "pipe" of a pipes-and-filters architecture. Producers send Messages to
a channel, and consumers receive Messages from a channel. The Message Channel therefore decouples the
messaging components, and also provides a convenient point for interception and monitoring of Messages.
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/channel.png" format="PNG"/>
</imageobject>
</mediaobject>
A Message Channel may follow either Point-to-Point or Publish/Subscribe semantics. With a Point-to-Point
channel, at most one consumer can receive each Message sent to the channel. Publish/Subscribe channels, on the
other hand, will attempt to broadcast each Message to all of its subscribers. Spring Integration supports
both of these.
</para>
<para>
Whereas "Point-to-Point" and "Publish/Subscribe" define the two options for <emphasis>how many</emphasis>
consumers will ultimately receive each Message, there is another important consideration: should the channel
buffer messages? In Spring Integration, <emphasis>Pollable Channels</emphasis> are capable of buffering
Messages within a queue. The advantage of buffering is that it allows for throttling the inbound Messages and
thereby prevents overloading a consumer. However, as the name suggests, this also adds some complexity, since a
consumer can only receive the Messages from such a channel if a <emphasis>poller</emphasis> is configured. On
the other hand, a consumer connected to a <emphasis>Subscribable Channel</emphasis> is simply Message-driven.
The variety of channel implementations available in Spring Integration will be discussed in detail in
<xref linkend="channel-implementations"/>.
</para>
</section>
<section id="overview-components-endpoint">
<title>Message Endpoint</title>
<para>
One of the primary goals of Spring Integration is to simplify the development of enterprise integration
solutions through <emphasis>inversion of control</emphasis>. This means that you should not have to implement
consumers and producers directly, and you should not even have to build Messages and invoke send or receive
operations on a Message Channel. Instead, you should be able to focus on your specific domain model with an
implementation based on plain Objects. Then, by providing declarative configuration, you can "connect"
your domain-specific code to the messaging infrastructure provided by Spring Integration. The components
responsible for these connections are Message Endpoints. This does not mean that you will necessarily connect
your existing application code directly. Any real-world enterprise integration solution will require some
amount of code focused upon integration concerns such as <emphasis>routing</emphasis> and
<emphasis>transformation</emphasis>. The important thing is to achieve separation of concerns between such
integration logic and business logic. In other words, as with the Model-View-Controller paradigm for web
applications, the goal should be to provide a thin but dedicated layer that translates inbound requests into
service layer invocations, and then translates service layer return values into outbound replies. The next
section will provide an overview of the Message Endpoint types that handle these responsibilities, and in
upcoming chapters, you will see how Spring Integration's declarative configuration options provide a
non-invasive way to use each of these.
</para>
</section>
</section>
<section id="overview-endpoints">
<title>Message Endpoints</title>
<para>
A Message Endpoint represents the "filter" of a pipes-and-filters architecture. As mentioned above, the
endpoint's primary role is to connect application code to the messaging framework and to do so in a non-invasive
manner. In other words, the application code should ideally have no awareness of the Message objects or the
Message Channels. This is similar to the role of a Controller in the MVC paradigm. Just as a Controller handles
HTTP requests, the Message Endpoint handles Messages. Just as Controllers are mapped to URL patterns, Message
Endpoints are mapped to Message Channels. The goal is the same in both cases: isolate application code from the
infrastructure. These concepts are discussed at length along with all of the patterns that follow in the
<ulink url="http://www.eaipatterns.com">Enterprise Integration Patterns</ulink> book. Here, we provide only a
high-level description of the main endpoint types supported by Spring Integration and their roles. The chapters
that follow will elaborate and provide sample code as well as configuration examples.
</para>
<section id="overview-endpoints-transformer">
<title>Transformer</title>
<para>
A Message Transformer is responsible for converting a Message's content or structure and returning the modified
Message. Probably the most common type of transformer is one that converts the payload of the Message from one
format to another (e.g. from XML Document to java.lang.String). Similarly, a transformer may be used to add,
remove, or modify the Message's header values.
</para>
</section>
<section id="overview-endpoints-filter">
<title>Filter</title>
<para>
A Message Filter determines whether a Message should be passed to an output channel at all. This simply
requires a boolean test method that may check for a particular payload content type, a property value, the
presence of a header, etc. If the Message is accepted, it is sent to the output channel, but if not it will be
dropped (or for a more severe implementation, an Exception could be thrown). Message Filters are often used in
conjunction with a Publish Subscribe channel, where multiple consumers may receive the same Message and use the
filter to narrow down the set of Messages to be processed based on some criteria.
<note>
Be careful not to confuse the generic use of "filter" within the Pipes-and-Filters architectural pattern with
this specific endpoint type that selectively narrows down the Messages flowing between two channels. The
Pipes-and-Filters concept of "filter" matches more closely with Spring Integration's Message Endpoint: any
component that can be connected to Message Channel(s) in order to send and/or receive Messages.
</note>
</para>
</section>
<section id="overview-endpoints-router">
<title>Router</title>
<para>
A Message Router is responsible for deciding what channel or channels should receive the Message next (if any).
Typically the decision is based upon the Message's content and/or metadata available in the Message Headers.
A Message Router is often used as a dynamic alternative to a statically configured output channel on
a Service Activator or other endpoint capable of sending reply Messages. Likewise, a Message Router provides a
proactive alternative to the reactive Message Filters used by multiple subscribers as described above.
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/router.png" format="PNG"/>
</imageobject>
</mediaobject>
</para>
</section>
<section id="overview-endpoints-splitter">
<title>Splitter</title>
<para>
A Splitter is another type of Message Endpoint whose responsibility is to accept a Message from its input
channel, split that Message into multiple Messages, and then send each of those to its output channel. This
is typically used for dividing a "composite" payload object into a group of Messages containing the
sub-divided payloads.
</para>
</section>
<section id="overview-endpoints-aggregator">
<title>Aggregator</title>
<para>
Basically a mirror-image of the Splitter, the Aggregator is a type of Message Endpoint that receives multiple
Messages and combines them into a single Message. In fact, Aggregators are often downstream consumers in a
pipeline that includes a Splitter. Technically, the Aggregator is more complex than a Splitter, because it
is required to maintain state (the Messages to-be-aggregated), to decide when the complete group of Messages
is available, and to timeout if necessary. Furthermore, in case of a timeout, the Aggregator needs to know
whether to send the partial results or to discard them to a separate channel. Spring Integration provides
a <interfacename>CompletionStrategy</interfacename> as well as configurable settings for timeout, whether
to send partial results upon timeout, and the discard channel.
</para>
</section>
<section id="overview-endpoints-service-activator">
<title>Service Activator</title>
<para>
A Service Activator is a generic endpoint for connecting a service instance to the messaging system. The
input Message Channel must be configured, and if the service method to be invoked is capable of returning a
value, an output Message Channel may also be provided.
<note>
The output channel is optional, since each Message may also provide its own 'Return Address' header. This
same rule applies for all consumer endpoints.
</note>
The Service Activator invokes an operation on some service object to process the request Message, extracting
the request Message's payload and converting if necessary (if the method does not expect a Message-typed
parameter). Whenever the service object's method returns a value, that return value will likewise be converted
to a reply Message if necessary (if it's not already a Message). That reply Message is sent to the output
channel. If no output channel has been configured, then the reply will be sent to the channel specified in the
Message's "return address" if available.
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/handler-endpoint.png" format="PNG"/>
</imageobject>
<caption>
A request-reply "Service Activator" endpoint connects a target object's method to input and output
Message Channels.
</caption>
</mediaobject>
</para>
</section>
<section id="overview-endpoints-channeladapter">
<title>Channel Adapter</title>
<para>
A Channel Adapter is an endpoint that connects a Message Channel to some other system or transport. Channel
Adapters may be either inbound or outbound. Typically, the Channel Adapter will do some mapping between the
Message and whatever object or resource is received-from or sent-to the other system (File, HTTP Request, JMS
Message, etc). Depending on the transport, the Channel Adapter may also populate or extract Message header
values. Spring Integration provides a number of Channel Adapters, and they will be described in upcoming
chapters.
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/source-endpoint.png" format="PNG"/>
</imageobject>
<caption>An inbound "Channel Adapter" endpoint connects a source system to a MessageChannel.</caption>
</mediaobject>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/target-endpoint.png" format="PNG"/>
</imageobject>
<caption>An outbound "Channel Adapter" endpoint connects a MessageChannel to a target system.</caption>
</mediaobject>
</para>
</section>
</section>
</chapter>

109
spring-integration-reference/src/resequencer.xml
View File

@@ -1,109 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="resequencer">
<title>Resequencer</title>
<section>
<title>Introduction</title>
<para>Related to the Aggregator, albeit different from a functional
standpoint, is the Resequencer. </para>
</section>
<section id="resequencer-functionality">
<title>Functionality</title>
<para>The Resequencer works in a similar way to the Aggregator, in the
sense that it uses the CORRELATION_ID to store messages in groups, the
difference being that the Resequencer does not process the messages in
any way. It simply releases them in the order of their SEQUENCE_NUMBER
header values.</para>
<para>With respect to that, the user might opt to release all messages at
once (after the whole sequence, according to the SEQUENCE_SIZE, has been
released), or as soon as a valid sequence is available.</para>
</section>
<section>
<title>Configuring a Resequencer with XML</title>
<para>Configuring a resequencer requires only including the appropriate
element in XML.</para>
<para>A sample resequencer configuration is shown below.</para>
<programlisting language="xml">&lt;channel id="inputChannel"/&gt;
&lt;channel id="outputChannel"/&gt;
&lt;resequencer id="completelyDefinedResequencer" <co id="resxml1-co" linkends="resxml1" />
input-channel="inputChannel" <co id="resxml2-co" linkends="resxml2"/>
output-channel="outputChannel" <co id="resxml3-co" linkends="resxml3"/>
discard-channel="discardChannel" <co id="resxml4-co" linkends="resxml4"/>
release-partial-sequences="true" <co id="resxml5-co" linkends="resxml5"/>
message-store="messageStore" <co id="resxml5-co" linkends="resxml6"/>
send-partial-result-on-expiry="true" <co id="resxml7-co" linkends="resxml7"/>
send-timeout="86420000" <co id="resxml10-co" linkends="resxml10"/> /&gt; </programlisting>
<para><calloutlist>
<callout arearefs="resxml1-co" id="resxml1">
<para>The id of the resequencer is
<emphasis>optional</emphasis>.</para>
</callout>
<callout arearefs="resxml2-co" id="resxml2">
<para>The input channel of the resequencer.
<emphasis>Required</emphasis>.</para>
</callout>
<callout arearefs="resxml3-co" id="resxml3">
<para>The channel where the resequencer will send the reordered
messages. <emphasis>Optional</emphasis>.</para>
</callout>
<callout arearefs="resxml4-co" id="resxml4">
<para>The channel where the resequencer will send the messages that
timed out (if <code>send-partial-result-on-timeout</code> is
<emphasis>false)</emphasis>. <emphasis>Optional</emphasis>.</para>
</callout>
<callout arearefs="resxml5-co" id="resxml5">
<para>Whether to send out ordered sequences as soon as they are
available, or only after the whole message group arrives.
<emphasis>Optional (false by default)</emphasis>.</para> If this
flag is not specified (so a complete sequence is defined by the sequence
headers) then it can make sense to provide a custom <code>Comparator</code>
to be used to order the messages when sending
(use the XML attribute <literal>comparator</literal> to point to a bean
definition). If <literal>release-partial-sequences</literal> is true then
there is no way with a custom comparator to define a partial sequence. To
do that you would have to provide a <literal>release-strategy</literal> (also
a reference to another bean definition, either a POJO or a <code>ReleaseStrategy</code>).
</callout>
<callout arearefs="resxml6-co" id="resxml6">
<para>A reference to a <code>MessageGroupStore</code> that
can be used to store groups of messages under their
correlation key until they are
complete. <emphasis>Optional</emphasis> with default a
volatile in-memory store.</para>
</callout>
<callout arearefs="resxml7-co" id="resxml7">
<para>Whether, upon the expiration of the group, the ordered group
should be sent out (even if some of the messages are missing).
<emphasis>Optional (false by default)</emphasis>.</para>
</callout>
<callout arearefs="resxml10-co" id="resxml10">
<para>The timeout for sending out messages.
<emphasis>Optional</emphasis>.</para>
</callout>
</calloutlist></para>
<note>
Since there is no custom behavior to be implemented in Java classes for resequencers, there is no annotation support for it.
</note>
</section>
</chapter>

17
spring-integration-reference/src/resources.xml
View File

@@ -1,17 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<appendix id="resources">
<title>Additional Resources</title>
<section id="resources-home">
<title>Spring Integration Home</title>
<para>
The definitive source of information about Spring Integration is the
<ulink url="http://www.springsource.org/spring-integration">Spring Integration Home</ulink> at
<ulink url="http://www.springsource.org">http://www.springsource.org</ulink>. That site serves as a hub of
information and is the best place to find up-to-date announcements about the project as well as links to
articles, blogs, and new sample applications.
</para>
</section>
</appendix>

66
spring-integration-reference/src/rmi.xml
View File

@@ -1,66 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="rmi">
<title>RMI Support</title>
<section id="rmi-intro">
<title>Introduction</title>
<para>
This Chapter explains how to use RMI specific channel adapters to distribute a system over multiple JVMs. The first section will deal with sending messages over RMI. The second section shows how to receive messages over RMI. The last section shows how to define rmi channel adapters through the namespace support.
</para>
</section>
<section id="rmi-outbound">
<title>Outbound RMI</title>
<para>
To send messages from a channel over RMI, simply define an <classname>RmiOutboundGateway</classname>. This gateway will use Spring's RmiProxyFactoryBean internally to create a proxy for a remote gateway. Note that to invoke a remote interface that doesn't use Spring Integration you should use a service activator in combination with Spring's RmiProxyFactoryBean.
</para>
<para>
To configure the outbound gateway write a bean definition like this:
<programlisting language="xml"><![CDATA[ <bean id="rmiOutGateway" class=org.spf.integration.rmi.RmiOutboundGateway>
<constructor-arg value="rmi://host"/>
<property name="replyChannel" value="replies"/>
</bean>]]>
</programlisting>
</para>
</section>
<section id="rmi-inbound">
<title>Inbound RMI</title>
<para>
To receive messages over RMI you need to use a <classname>RmiInboundGateway</classname>. This gateway can be configured like this
<programlisting language="xml"><![CDATA[ <bean id="rmiOutGateway" class=org.spf.integration.rmi.RmiInboundGateway>
<property name="requestChannel" value="requests"/>
</bean>]]>
</programlisting>
</para>
</section>
<section id="rmi-namespace">
<title>RMI namespace support</title>
<para>
To configure the inbound gateway you can choose to use the namespace support for it. The following code snippet shows the different configuration options that are supported.
<programlisting language="xml"><![CDATA[ <rmi:inbound-gateway id="gatewayWithDefaults" request-channel="testChannel"/>
<rmi:inbound-gateway id="gatewayWithCustomProperties" request-channel="testChannel"
expect-reply="false" request-timeout="123" reply-timeout="456"/>
<rmi:inbound-gateway id="gatewayWithHost" request-channel="testChannel"
registry-host="localhost"/>
<rmi:inbound-gateway id="gatewayWithPort" request-channel="testChannel"
registry-port="1234"/>
<rmi:inbound-gateway id="gatewayWithExecutorRef" request-channel="testChannel"
remote-invocation-executor="invocationExecutor"/>]]></programlisting>
</para>
<para>
To configure the outbound gateway you can use the namespace support as well. The following code snippet shows the different configuration for an outbound rmi gateway.
<programlisting language="xml"><![CDATA[ <rmi:outbound-gateway id="gateway"
request-channel="localChannel"
remote-channel="testChannel"
host="localhost"/>]]></programlisting>
</para>
</section>
</chapter>

205
spring-integration-reference/src/router.xml
View File

@@ -1,205 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="router">
<title>Router</title>
<section id="router-implementations">
<title>Router Implementations</title>
<para>
Since content-based routing often requires some domain-specific logic, most use-cases will require
Spring Integration's options for delegating to POJOs using the XML namespace support and/or Annotations.
Both of these are discussed below, but first we present a couple implementations that are available
out-of-the-box since they fulfill generic, but common, requirements.
</para>
<section id="router-implementations-payloadtyperouter">
<title>PayloadTypeRouter</title>
<para>
A <classname>PayloadTypeRouter</classname> will send Messages to the channel as defined by payload-type
mappings.
<programlisting language="xml"><![CDATA[<bean id="payloadTypeRouter" class="org.springframework.integration.router.PayloadTypeRouter">
<property name="payloadTypeChannelMap">
<map>
<entry key="java.lang.String" value-ref="stringChannel"/>
<entry key="java.lang.Integer" value-ref="integerChannel"/>
</map>
</property>
</bean>]]></programlisting>
</para>
<para>
Configuration of <classname>PayloadTypeRouter</classname> is also supported via the namespace provided by Spring Integration (see <xref linkend="configuration-namespace"/>),
which essentially simplifies configuration by combining <code>&lt;router/&gt;</code> configuration and its corresponding implementation defined using <code>&lt;bean/&gt;</code> element
into a single and more concise configuration element.
The example below demonstrates <classname>PayloadTypeRouter</classname> configuration which is equivalent to the one above using Spring Integration's namespace support:
</para>
<para>
<programlisting language="xml"><![CDATA[<payload-type-router input-channel="routingChannel">
<mapping type="java.lang.String" channel="stringChannel" />
<mapping type="java.lang.Integer" channel="integerChannel" />
</payload-type-router>]]></programlisting>
</para>
</section>
<section id="router-implementations-headervaluerouter">
<title>HeaderValueRouter</title>
<para>
A <classname>HeaderValueRouter</classname> will send Messages to the channel based on the individual header value mappings.
When <code>HeaderValueRouter</code> is created it is initialized with the <emphasis>name</emphasis> of the header to be evaluated, using <code>constructor-arg</code>.
The <emphasis>value</emphasis> of the header could be one of two things:</para>
<para>
1. Arbitrary value
</para>
<para>
2. Channel name
</para>
<para>
If arbitrary value, then a <code>channelResolver</code> should be provided to map <emphasis>header values</emphasis> to <emphasis>channel names</emphasis>.
The example below uses <code>MapBasedChannelResolver</code> to set up a map of header values to channel names.
<programlisting language="xml"><![CDATA[ <bean id="myHeaderValueRouter"
class="org.springframework.integration.router.HeaderValueRouter">
<constructor-arg value="someHeaderName" />
<property name="channelResolver">
<bean class="org.springframework.integration.channel.MapBasedChannelResolver">
<property name="channelMap">
<map>
<entry key="someHeaderValue" value-ref="channelA" />
<entry key="someOtherHeaderValue" value-ref="channelB" />
</map>
</property>
</bean>
</property>
</bean>
]]></programlisting>
If <code>channelResolver</code> is not specified, then the <emphasis>header value</emphasis> will be treated as a <emphasis>channel name</emphasis>
making configuration much simpler, where no <code>channelResolver</code> needs to be specified.
<programlisting language="xml"><![CDATA[
<bean id="myHeaderValueRouter"
class="org.springframework.integration.router.HeaderValueRouter">
<constructor-arg value="someHeaderName" />
</bean>
]]></programlisting>
</para>
<para>
Similar to the <classname>PayloadTypeRouter</classname>, configuration of <classname>HeaderValueRouter</classname> is also supported via namespace support provided by Spring Integration (see <xref linkend="configuration-namespace"/>).
The example below demonstrates two types of namespace-based configuration of <classname>HeaderValueRouter</classname> which are equivalent to the ones above using Spring Integration namespace support:
</para>
<para>1. Configuration where mapping of header values to channels is required</para>
<para>
<programlisting language="xml"><![CDATA[<header-value-router input-channel="routingChannel" header-name="testHeader">
<mapping value="someHeaderValue" channel="channelA" />
<mapping value="someOtherHeaderValue" channel="channelB" />
</header-value-router>]]></programlisting>
</para>
<para>2. Configuration where mapping of header values is not required if header values themselves represent the channel names</para>
<para>
<programlisting language="xml"><![CDATA[<header-value-router input-channel="routingChannel" header-name="testHeader"/>]]></programlisting>
</para>
<note>
The two router implementations shown above share some common properties, such as "defaultOutputChannel" and "resolutionRequired".
If "resolutionRequired" is set to "true", and the router is unable to determine a target channel (e.g. there is
no matching payload for a PayloadTypeRouter and no "defaultOutputChannel" has been specified), then an Exception
will be thrown.
</note>
</section>
<section id="router-implementations-recipientlistrouter">
<title>RecipientListRouter</title>
<para>
A <classname>RecipientListRouter</classname> will send each received Message to a statically-defined
list of Message Channels:
<programlisting language="xml"><![CDATA[<bean id="recipientListRouter" class="org.springframework.integration.router.RecipientListRouter">
<property name="channels">
<list>
<ref bean="channel1"/>
<ref bean="channel2"/>
<ref bean="channel3"/>
</list>
</property>
</bean>]]></programlisting>
</para>
</section>
<para>
Configuration for <classname>RecipientListRouter</classname> is also supported via namespace support provided by Spring Integration (see <xref linkend="configuration-namespace"/>).
The example below demonstrates namespace-based configuration of <classname>RecipientListRouter</classname> and all the supported attributes using Spring Integration namespace support:
</para>
<para>
<programlisting language="xml"><![CDATA[<recipient-list-router id="customRouter" input-channel="routingChannel"
timeout="1234"
ignore-send-failures="true"
apply-sequence="true">
<recipient channel="channel1"/>
<recipient channel="channel2"/>
</recipient-list-router>]]></programlisting>
</para>
<note>
The 'apply-sequence' flag here has the same affect as it does for a publish-subscribe-channel,
and like publish-subscribe-channel it is disabled by default on the recipient-list-router. Refer to
<xref linkend="channel-configuration-pubsubchannel"/> for more information.
</note>
</section>
<section id="router-namespace">
<title>The &lt;router&gt; element</title>
<para>
The "router" element provides a simple way to connect a router to an input channel, and also accepts the
optional default output channel. The "ref" may provide the bean name of a custom Router implementation
(extending AbstractMessageRouter):
<programlisting language="xml"><![CDATA[<router ref="payloadTypeRouter" input-channel="input1" default-output-channel="defaultOutput1"/>
<router ref="recipientListRouter" input-channel="input2" default-output-channel="defaultOutput2"/>
<router ref="customRouter" input-channel="input3" default-output-channel="defaultOutput3"/>
<beans:bean id="customRouterBean class="org.foo.MyCustomRouter"/>]]></programlisting>
Alternatively, the "ref" may point to a simple Object that contains the @Router annotation (see below), or the
"ref" may be combined with an explicit "method" name. When specifying a "method", the same behavior applies as
described in the @Router annotation section below.
<programlisting language="xml"><![CDATA[<router input-channel="input" ref="somePojo" method="someMethod"/>]]></programlisting>
Using a "ref" attribute is generally recommended if the custom router implementation can be reused in other
<code>&lt;router&gt;</code> definitions. However if the custom router implementation should be scoped to a
concrete definition of the <code>&lt;router&gt;</code>, you can provide an inner bean definition:
<programlisting language="xml"><![CDATA[<router method="someMethod" input-channel="input3" default-output-channel="defaultOutput3">
<beans:bean class="org.foo.MyCustomRouter"/>
</router>]]></programlisting>
</para>
<note>
<para>
Using both the "ref" attribute and an inner handler definition in the same <code>&lt;router&gt;</code> configuration
is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
</para>
</note>
</section>
<section id="router-annotation">
<title>The @Router Annotation</title>
<para>
When using the <interfacename>@Router</interfacename> annotation, the annotated method can return either the
<interfacename>MessageChannel</interfacename> or <classname>String</classname> type. In the case of the latter,
the endpoint will resolve the channel name as it does for the default output. Additionally, the method can return
either a single value or a collection. When a collection is returned, the reply message will be sent to multiple
channels. To summarize, the following method signatures are all valid.
<programlisting language="java">@Router
public MessageChannel route(Message message) {...}
@Router
public List&lt;MessageChannel&gt; route(Message message) {...}
@Router
public String route(Foo payload) {...}
@Router
public List&lt;String&gt; route(Foo payload) {...}</programlisting>
</para>
<para>
In addition to payload-based routing, a common requirement is to route based on metadata available within the
message header as either a property or attribute. Rather than requiring use of the
<interfacename>Message</interfacename> type as the method parameter, the <interfacename>@Router</interfacename>
annotation may also use the @Header parameter annotation that is documented in <xref linkend="annotations"/>.
<programlisting language="java">@Router
public List&lt;String&gt; route(@Header("orderStatus") OrderStatus status)</programlisting>
</para>
</section>
<note>
For routing of XML-based Messages, including XPath support, see <xref linkend="xml"/>.
</note>
</chapter>

447
spring-integration-reference/src/samples.xml
View File

@@ -1,447 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<appendix id="samples">
<title>Spring Integration Samples</title>
<note>
Starting with the current release of Spring Integration the <emphasis>samples</emphasis> are distributed as independent
Maven-based projects (<ulink url="http://maven.apache.org/">http://maven.apache.org/</ulink>) to minimize the setup time.
Since each project is also an Eclipse-based project, they can be imported as is using the Eclipse Import wizard.
If you prefer another IDE, configuration should be very trivial, since a special Maven profile was setup to download all
of the required dependencies for all samples. Detailed instructions on how to build and run the samples are provided in
the <code>README.txt</code> file located in the <emphasis>samples</emphasis> directory of the main distribution.
</note>
<section id="samples-cafe">
<title>The Cafe Sample</title>
<para>
In this section, we will review a sample application that is included in the Spring Integration
distribution. This sample is inspired by one of the samples featured in Gregor Hohpe's
<ulink url="http://www.eaipatterns.com/ramblings.html">Ramblings</ulink>.
</para>
<para>
The domain is that of a Cafe, and the basic flow is depicted in the following diagram:
</para>
<para>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="images/cafe-demo.png" format="PNG"/>
</imageobject>
</mediaobject>
</para>
<para>
The <classname>Order</classname> object may contain multiple <classname>OrderItems</classname>. Once the order
is placed, a <emphasis>Splitter</emphasis> will break the composite order message into a single message per
drink. Each of these is then processed by a <emphasis>Router</emphasis> that determines whether the drink is hot
or cold (checking the <classname>OrderItem</classname> object's 'isIced' property). The
<classname>Barista</classname> prepares each drink, but hot and cold drink preparation are handled by two
distinct methods: 'prepareHotDrink' and 'prepareColdDrink'. The prepared drinks are then sent to the Waiter where
they are aggregated into a <classname>Delivery</classname> object.
</para>
<para>
Here is the XML configuration:
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/integration"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xmlns:stream="http://www.springframework.org/schema/integration/stream"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration-1.0.xsd
http://www.springframework.org/schema/integration/stream
http://www.springframework.org/schema/integration/stream/spring-integration-stream-1.0.xsd">
<gateway id="cafe" service-interface="org.springframework.integration.samples.cafe.Cafe"/>
<channel id="orders"/>
<splitter input-channel="orders" ref="orderSplitter" method="split" output-channel="drinks"/>
<channel id="drinks"/>
<router input-channel="drinks" ref="drinkRouter" method="resolveOrderItemChannel"/>
<channel id="coldDrinks">
<queue capacity="10"/>
</channel>
<service-activator input-channel="coldDrinks" ref="barista"
method="prepareColdDrink" output-channel="preparedDrinks"/>
<channel id="hotDrinks">
<queue capacity="10"/>
</channel>
<service-activator input-channel="hotDrinks" ref="barista"
method="prepareHotDrink" output-channel="preparedDrinks"/>
<channel id="preparedDrinks"/>
<aggregator input-channel="preparedDrinks" ref="waiter"
method="prepareDelivery" output-channel="deliveries"/>
<stream:stdout-channel-adapter id="deliveries"/>
<beans:bean id="orderSplitter"
class="org.springframework.integration.samples.cafe.xml.OrderSplitter"/>
<beans:bean id="drinkRouter"
class="org.springframework.integration.samples.cafe.xml.DrinkRouter"/>
<beans:bean id="barista" class="org.springframework.integration.samples.cafe.xml.Barista"/>
<beans:bean id="waiter" class="org.springframework.integration.samples.cafe.xml.Waiter"/>
<poller id="poller" default="true">
<interval-trigger interval="1000"/>
</poller>
</beans:beans>]]></programlisting>
As you can see, each Message Endpoint is connected to input and/or output channels. Each endpoint will manage
its own Lifecycle (by default endpoints start automatically upon initialization - to prevent that add the
"auto-startup" attribute with a value of "false"). Most importantly, notice that the objects are simple POJOs
with strongly typed method arguments. For example, here is the Splitter:
<programlisting language="java"><![CDATA[public class OrderSplitter {
public List<OrderItem> split(Order order) {
return order.getItems();
}
}]]></programlisting>
In the case of the Router, the return value does not have to be a <interfacename>MessageChannel</interfacename>
instance (although it can be). As you see in this example, a String-value representing the channel name is
returned instead.
<programlisting language="java"><![CDATA[public class DrinkRouter {
public String resolveOrderItemChannel(OrderItem orderItem) {
return (orderItem.isIced()) ? "coldDrinks" : "hotDrinks";
}
}]]></programlisting>
</para>
<para>
Now turning back to the XML, you see that there are two &lt;service-activator&gt; elements. Each of these
is delegating to the same <classname>Barista</classname> instance but different methods: 'prepareHotDrink'
or 'prepareColdDrink' corresponding to the two channels where order items have been routed.
<programlisting language="java"><![CDATA[public class Barista {
private long hotDrinkDelay = 5000;
private long coldDrinkDelay = 1000;
private AtomicInteger hotDrinkCounter = new AtomicInteger();
private AtomicInteger coldDrinkCounter = new AtomicInteger();
public void setHotDrinkDelay(long hotDrinkDelay) {
this.hotDrinkDelay = hotDrinkDelay;
}
public void setColdDrinkDelay(long coldDrinkDelay) {
this.coldDrinkDelay = coldDrinkDelay;
}
public Drink prepareHotDrink(OrderItem orderItem) {
try {
Thread.sleep(this.hotDrinkDelay);
System.out.println(Thread.currentThread().getName()
+ " prepared hot drink #" + hotDrinkCounter.incrementAndGet()
+ " for order #" + orderItem.getOrder().getNumber() + ": " + orderItem);
return new Drink(orderItem.getOrder().getNumber(), orderItem.getDrinkType(),
orderItem.isIced(), orderItem.getShots());
}
catch (InterruptedException e) {
Thread.currentThread().interrupt();
return null;
}
}
public Drink prepareColdDrink(OrderItem orderItem) {
try {
Thread.sleep(this.coldDrinkDelay);
System.out.println(Thread.currentThread().getName()
+ " prepared cold drink #" + coldDrinkCounter.incrementAndGet()
+ " for order #" + orderItem.getOrder().getNumber() + ": " + orderItem);
return new Drink(orderItem.getOrder().getNumber(), orderItem.getDrinkType(),
orderItem.isIced(), orderItem.getShots());
}
catch (InterruptedException e) {
Thread.currentThread().interrupt();
return null;
}
}
}]]></programlisting>
</para>
<para>
As you can see from the code excerpt above, the barista methods have different delays (the hot drinks take 5
times as long to prepare). This simulates work being completed at different rates. When the
<classname>CafeDemo</classname> 'main' method runs, it will loop 100 times sending a single hot drink and a
single cold drink each time. It actually sends the messages by invoking the 'placeOrder' method on the Cafe
interface. Above, you will see that the &lt;gateway&gt; element is specified in the configuration file. This
triggers the creation of a proxy that implements the given 'service-interface' and connects it to a channel.
The channel name is provided on the @Gateway annotation of the <interfacename>Cafe</interfacename> interface.
<programlisting language="java">public interface Cafe {
@Gateway(requestChannel="orders")
void placeOrder(Order order);
}</programlisting>
Finally, have a look at the <methodname>main()</methodname> method of the <classname>CafeDemo</classname> itself.
<programlisting language="java"><![CDATA[public static void main(String[] args) {
AbstractApplicationContext context = null;
if (args.length > 0) {
context = new FileSystemXmlApplicationContext(args);
}
else {
context = new ClassPathXmlApplicationContext("cafeDemo.xml", CafeDemo.class);
}
Cafe cafe = (Cafe) context.getBean("cafe");
for (int i = 1; i <= 100; i++) {
Order order = new Order(i);
order.addItem(DrinkType.LATTE, 2, false);
order.addItem(DrinkType.MOCHA, 3, true);
cafe.placeOrder(order);
}
}]]></programlisting>
</para>
<tip>
To run this sample as well as 8 others, refer to the <code>README.txt</code> within the "samples" directory
of the main distribution as described at the beginning of this chapter.
</tip>
<para>
When you run cafeDemo, you will see that the cold drinks are initially prepared more quickly than the hot drinks.
Because there is an aggregator, the cold drinks are effectively limited by the rate of the hot drink preparation.
This is to be expected based on their respective delays of 1000 and 5000 milliseconds. However, by configuring a
poller with a concurrent task executor, you can dramatically change the results. For example, you could use a
thread pool executor with 5 workers for the hot drink barista while keeping the cold drink barista as it is:
<programlisting language="xml"><![CDATA[<service-activator input-channel="hotDrinks"
ref="barista"
method="prepareHotDrink"
output-channel="preparedDrinks"/>
<service-activator input-channel="hotDrinks"
ref="barista"
method="prepareHotDrink"
output-channel="preparedDrinks">
]]><emphasis><![CDATA[<poller task-executor="pool">
<interval-trigger interval="1000"/>
</poller>]]></emphasis><![CDATA[
</service-activator>
]]><emphasis><![CDATA[<task:executor id="pool" pool-size="5"/>]]></emphasis></programlisting>
</para>
<para>
Also, notice that the worker thread name is displayed with each invocation. You will see that the hot drinks are
prepared by the task-executor threads. If you provide a much shorter poller interval (such as 100 milliseconds),
then you will notice that occasionally it throttles the input by forcing the task-scheduler (the caller) to invoke
the operation.
</para>
<note>
In addition to experimenting with the poller's concurrency settings, you can also add the 'transactional'
sub-element and then refer to any PlatformTransactionManager instance within the context.
</note>
</section>
<section id="samples-xml-messaging">
<title>The XML Messaging Sample</title>
<para>
The xml messaging sample in the <package>org.springframework.integration.samples.xml</package> illustrates how to use
some of the provided components which deal with xml payloads. The sample uses the idea of processing an order for books
represented as xml.
</para>
<para>
First the order is split into a number of messages, each one representing a single order item using
the XPath splitter component.
<programlisting language="xml"><![CDATA[<si-xml:xpath-splitter id="orderItemSplitter" input-channel="ordersChannel"
output-channel="stockCheckerChannel" create-documents="true">
<si-xml:xpath-expression expression="/orderNs:order/orderNs:orderItem" namespace-map="orderNamespaceMap" />
</si-xml:xpath-splitter>
]]></programlisting>
</para>
<para>
A service activator is then used to pass the message into a stock checker POJO. The order item document is enriched with information
from the stock checker about order item stock level. This enriched order item message is then used to route the message. In the
case where the order item is in stock the message is routed to the warehouse. The XPath router makes use of a
<classname>MapBasedChannelResolver</classname> which maps the XPath evaluation result to a channel reference.
<programlisting language="xml"><![CDATA[<si-xml:xpath-router id="instockRouter" channel-resolver="mapChannelResolver"
input-channel="orderRoutingChannel" resolution-required="true">
<si-xml:xpath-expression expression="/orderNs:orderItem/@in-stock" namespace-map="orderNamespaceMap" />
</si-xml:xpath-router>
<bean id="mapChannelResolver"
class="org.springframework.integration.channel.MapBasedChannelResolver">
<property name="channelMap">
<map>
<entry key="true" value-ref="warehouseDispatchChannel" />
<entry key="false" value-ref="outOfStockChannel" />
</map>
</property>
</bean>
]]></programlisting>
</para>
<para>
Where the order item is not in stock the message is transformed using
xslt into a format suitable for sending to the supplier.
<programlisting language="xml"><![CDATA[<si-xml:xslt-transformer input-channel="outOfStockChannel" output-channel="resupplyOrderChannel"
xsl-resource="classpath:org/springframework/integration/samples/xml/bigBooksSupplierTransformer.xsl"/>
]]></programlisting>
</para>
</section>
<section id="samples-osgi">
<title>The OSGi Samples</title>
<para>
This release of Spring Integration includes several samples that are OSGi enabled as well as samples that were
specifically designed to show some of the other benefits of OSGi and Spring Integration when used together.
First lets look at the two familiar examples that are also configured to be valid OSGi bundles. These are
<emphasis>Hello World</emphasis> and <emphasis>Cafe</emphasis>. All you need to do to see these samples work in
an OSGi environment is deploy the generated JAR into such an environment.
</para>
<para>
Use Maven to generate the JAR by executing the 'mvn install' command on either of these projects. This will
generate the JAR file in the target directory. Now you can simply drop that JAR file into the deployment
directory of your OSGi platform. For example, if you are using
<ulink url="http://www.springsource.com/products/dmserver">SpringSource dm Server</ulink>,
drop the files into the 'pickup' directory within the dm Server home directory.
</para>
<note>
Prior to deploying and testing Spring Integration samples in the dm Server or any other OSGi server platform,
you must have the Spring Integration and Spring bundles installed on that platform. For example, to install
Spring Integration into SpringSource dm Server, copy all JAR files that are located in the 'dist' directory of
your Spring Integration distribution into the 'repository/bundles/usr' directory of your dm Server instance
(see the
<ulink url="http://static.springsource.com/projects/dm-server/1.0.x/user-guide/htmlsingle/user-guide.html">dm Server User Guide</ulink>
for more detail on how to install bundles).
</note>
<para>
The Spring Integration samples require a few other bundles to be installed. For the 1.0.3 release, the full
list including transitive dependencies is:
<itemizedlist>
<listitem>org.apache.commons.codec-1.3.0.jar</listitem>
<listitem>org.apache.commons.collections-3.2.0.jar</listitem>
<listitem>org.apache.commons.httpclient-3.1.0.jar</listitem>
<listitem>org.apache.ws.commons.schema-1.3.2.jar</listitem>
<listitem>org.springframework.oxm-1.5.5.A.jar</listitem>
<listitem>org.springframework.security-2.0.4.A.jar</listitem>
<listitem>org.springframework.ws-1.5.5.A.jar</listitem>
<listitem>org.springframework.xml-1.5.5.A.jar</listitem>
</itemizedlist>
These are all located within the 'lib' directory of the Spring Integration distribution. So, you can simply
copy those JARs into the dm Server 'repository/bundles/usr' directory as well.
<note>
The Spring Framework bundles (aop, beans, context, etc.) are also included in the 'lib' directory of the
Spring Integration distribution, but they do not need to be installed since they are already part of the
dm Server infrastructure. Also, note that the versions listed above are those included with the Spring
Integration 1.0.3 release. Newer versions of individual JARs may be used as long as they are within the
range specified in the MANIFEST.MF files of those bundles that depend upon them.
</note>
<tip>
The bundles listed above are appropriate for a SpringSource dm Server 1.0.x deployment environment
with a Spring Framework 2.5.x foundation. That is the version against which Spring Integration 1.0.3
has been developed and tested. However, as of the time of the Spring Integration 1.0.3 release, the
Spring Framework 3.0 release candidates are about to be available, and the dm Server 2.0.x milestones
are available. If you want to try running these samples in that environment, then you will need to
replace the Spring Security and Spring Web Services bundles with versions that support Spring 3.0.
The OXM functionality is moving into the Spring Framework itself for the 3.0 release. Otherwise,
Spring Integration 1.0.3 has been superficially tested against the Spring 3.0 snapshots available
at the time of its release. In fact, some internal changes were made in the 1.0.3 release
specifically to support Spring 3.0 (whereas 1.0.2 does not). Spring Integration 2.0 will be built
upon a Spring 3.0 foundation.
</tip>
</para>
<para>
To demonstrate some of the benefits of running Spring Integration projects in an OSGi environment (e.g.
modularity, OSGi service dynamics, etc.), we have included a couple new samples that are dedicated to
highlighting those benefits. In the 'samples' directory, you will find the following two projects:
<itemizedlist>
<listitem>osgi-inbound (producer bundle)</listitem>
<listitem>osgi-outbound (consumer bundle)</listitem>
</itemizedlist>
Unlike the other samples in the distribution, these are not Maven enabled. Instead, we have simply configured
them as valid dm Server Bundle projects. That means you can import these projects directly into an STS
workspace using the "Existing Projects into Workspace" option from the Eclipse Import wizard. Then, you can
take advantage of the STS dm Server tools to deploy them into a SpringSource dm Server instance.
<note>
A simple Ant 'build.xml' file has been included within each of these projects as well. The build
files contain a single 'jar' target. Therefore, after these projects have been built within
Eclipse/STS, you can generate the bundle (JAR) directly and deploy it manually.
</note>
</para>
<para>
The structure of these projects is very simple, yet the concepts they showcase are quite powerful. The
'osgi-inbound' module enables sending a Message to a Publish-Subscribe Channel using a Spring Integration
Gateway proxy. The interesting part, however, is that the Publish-Subscribe Channel is exported as an OSGi
service via the &lt;osgi:service/&gt; element. As a result, any other bundles can be developed, deployed, and
maintained independently yet still subscribe to that channel.
</para>
<para>
The 'osgi-outbound' module is an example of such a subscribing consumer bundle. It uses the corresponding
&lt;osgi:reference/&gt; element to locate the channel exported by the 'osgi-inbound' bundle. It also contains
configuration for a &lt;file:outbound-gateway/&gt; which is a subscriber to that channel and will write the
Message content to a file once it arrives. It then sends a response Message with the name of the file and its
location.
</para>
<para>
To make it easy to run, we've exposed a command-line interface where you can type in the command, the message,
and the file name to execute the demo. This is exposed through the OSGi console. Likewise, the response that
provides the name and location of the resulting file will also be visible within the OSGi console.
</para>
<para>
To run these samples, make sure your OSGi environment is properly configured to host Spring Integration bundles
(as described in the note above). Deploy the producer bundle (osgi-inbound) first, and then deploy the consumer
bundle (osgi-outbound). After you have deployed these bundles, open the OSGi console and type the following
command:
<programlisting><![CDATA[ osgi> help ]]></programlisting>
You will see the following amidst the output:
<programlisting><![CDATA[ ---Spring Integration CLI-based OSGi Demo---
siSend <message> <filename> - send text to be written to a file]]></programlisting>
As you can see, that describes the command that you will be able to use to send messages. If you are interested
in how it is implemented or want to customize message sending logic or even create a new command look at
<classname>InboundDemoBundleActivator.java</classname> in the consumer bundle.
<tip>
When using the SpringSource Tool Suite, you can open the OSGi console by first opening the dm Server
view and then choosing the 'Server Console' tab at the bottom (to open the dm Server view, navigate to
the dm Server instance listed in the 'Servers' view and either double-click or hit F3). Alternatively,
you can open the OSGi console by connecting to port 2401 via telnet (as long as that is enabled, and
for dm Server, it is enabled by default):
<programlisting> telnet localhost 2401</programlisting>
</tip>
</para>
<para>
Now send a message by typing: <programlisting><![CDATA[ osgi> siSend "Hello World" hello.txt]]></programlisting>
You will see something similar to the following in the OSGi console:
<programlisting><![CDATA[ Sending message: 'Hello World'
Message sent and its contents were written to:
/usr/local/dm-server/work/tmp/spring-integration-samples/output/hello.txt]]></programlisting>
<note>
It is not necessary to wrap the message in quotes if it does not contain spaces.
Go ahead and open up the file and verify that the message content was written to it.
</note>
</para>
<para>
Let's assume you wanted to change the directory to which the files are written or make any other change to the
consumer bundle (osgi-outboud). You only need to update the consumer bundle and not the producer bundle. So, go
ahead and change the directory in the 'osgi-outbound.xml' file located within 'src/META-INF/spring' and refresh
the consumer bundle.
<tip>
If using STS to deploy to dm Server, the refresh will happen automatically. If replacing bundles manually,
you can issue the command 'refresh n' in the OSGi console (where n would be the ID of the bundle as
displayed at any point after issuing the 'ss' command to see the short status output).
</tip>
You will see that the change takes affect immediately. Not only that, you could even start developing and
deploying new bundles that subscribe to the messages produced by the producer bundle the same way as the existing
consumer bundle (osgi-outbound) does. With a publish-subscribe-channel any newly deployed bundles would start
receiving each Message as well.
<note>
If you also want to modify and refresh the producer bundle, be sure to refresh the consumer bundle
afterwards as well. This is necessary because the consumer's subscription must be explicitly re-enabled
after the producer's channel disappears. You could alternatively deploy a relatively static bundle that
defines channels so that producers and consumers can be completely dynamic without affecting each other
at all. In Spring Integration 2.0, we plan to support automatic re-subscription and more through the use
of a <emphasis>Control Bus</emphasis>.
</note>
</para>
<para>
That pretty much wraps up this very simple example. Hopefully it has successfully demonstrated the benefits of
modularity and OSGi service dynamics while working with Spring Integration. Feel free to experiment by following
some of the suggestions mentioned above. For deeper coverage of the applicability of OSGi when used with Spring
Integration, read <ulink url="http://blog.springsource.com/2009/02/27/spring-integration-on-dm-server/">this blog</ulink>
by Spring Integration team member Iwein Fuld.
</para>
</section>
</appendix>

64
spring-integration-reference/src/security.xml
View File

@@ -1,64 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="security">
<title>Security in Spring Integration</title>
<section id="security-intro">
<title>Introduction</title>
<para>
Spring Integration provides integration with the
<ulink url="http://static.springframework.org/spring-security/site/">Spring Security project</ulink>
to allow role based security checks to be applied to channel send and receive invocations.
</para>
</section>
<section id="securing-channels">
<title>Securing channels</title>
<para>
Spring Integration provides the interceptor <classname>ChannelSecurityInterceptor</classname>, which extends
<classname>AbstractSecurityInterceptor</classname> and intercepts send and receive calls on the channel. Access decisions
are then made with reference to <classname>ChannelInvocationDefinitionSource</classname> which provides the definition of
the send and receive security constraints. The interceptor requires that a valid <interfacename>SecurityContext</interfacename>
has been established by authenticating with Spring Security, see the Spring Security reference documentation for details.
</para>
<para>
Namespace support is provided to allow easy configuration of security constraints. This consists of the secured channels tag which allows
definition of one or more channel name patterns in conjunction with a definition of the security configuration for send and receive. The pattern
is a <interfacename>java.util.regexp.Pattern</interfacename>.
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/integration"
xmlns:si-security="http://www.springframework.org/schema/integration/security"
xmlns:beans="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:security="http://www.springframework.org/schema/security"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
http://www.springframework.org/schema/security
http://www.springframework.org/schema/security/spring-security-2.0.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration-1.0.xsd
http://www.springframework.org/schema/integration/security
http://www.springframework.org/schema/integration/security/spring-integration-security-1.0.xsd">
<si-security:secured-channels>
<si-security:access-policy pattern="admin.*" send-access="ROLE_ADMIN"/>
<si-security:access-policy pattern="user.*" receive-access="ROLE_USER"/>
</si-security:secured-channels>]]>
</programlisting>
By default the secured-channels namespace element expects a bean named <emphasis>authenticationManager</emphasis> which implements
<interfacename>AuthenticationManager</interfacename> and a bean named <emphasis>accessDecisionManager</emphasis> which implements
<interfacename>AccessDecisionManager</interfacename>. Where this is not the case references to the appropriate beans can be configured
as attributes of the <emphasis>secured-channels</emphasis> element as below.
<programlisting language="xml"><![CDATA[<si-security:secured-channels access-decision-manager="customAccessDecisionManager"
authentication-manager="customAuthenticationManager">
<si-security:access-policy pattern="admin.*" send-access="ROLE_ADMIN"/>
<si-security:access-policy pattern="user.*" receive-access="ROLE_USER"/>
</si-security:secured-channels>]]>
</programlisting>
</para>
</section>
</chapter>

72
spring-integration-reference/src/service-activator.xml
View File

@@ -1,72 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="service-activator">
<title>Service Activator</title>
<section id="service-activator-introduction">
<title>Introduction</title>
<para>
The Service Activator is the endpoint type for connecting any Spring-managed Object to an input channel so that
it may play the role of a service. If the service produces output, it may also be connected to an output channel.
Alternatively, an output producing service may be located at the end of a processing pipeline or message flow in
which case, the inbound Message's "replyChannel" header can be used. This is the default behavior if no output
channel is defined, and as with most of the configuration options you'll see here, the same behavior actually
applies for most of the other components we have seen.
</para>
</section>
<section id="service-activator-namespace">
<title>The &lt;service-activator/&gt; Element</title>
<para>
To create a Service Activator, use the 'service-activator' element with the 'input-channel' and 'ref' attributes:
<programlisting language="xml">&lt;service-activator input-channel="exampleChannel" ref="exampleHandler"/&gt;</programlisting>
</para>
<para>
The configuration above assumes that "exampleHandler" either contains a single method annotated with the
@ServiceActivator annotation or that it contains only one public method at all. To delegate to an explicitly
defined method of any object, simply add the "method" attribute.
<programlisting language="xml">&lt;service-activator input-channel="exampleChannel" ref="somePojo" method="someMethod"/&gt;</programlisting>
</para>
<para>
In either case, when the service method returns a non-null value, the endpoint will attempt to send the reply
message to an appropriate reply channel. To determine the reply channel, it will first check if an
"output-channel" was provided in the endpoint configuration:
<programlisting language="xml">&lt;service-activator input-channel="exampleChannel" output-channel="replyChannel"
ref="somePojo" method="someMethod"/&gt;</programlisting>
If no "output-channel" is available, it will then check the Message's <literal>REPLY_CHANNEL</literal> header
value. If that value is available, it will then check its type. If it is a
<interfacename>MessageChannel</interfacename>, the reply message will be sent to that channel. If it is a
<classname>String</classname>, then the endpoint will attempt to resolve the channel name to a channel instance.
If the channel cannot be resolved, then a <classname>ChannelResolutionException</classname> will be thrown.
</para>
<para>
The argument in the service method could be either a Message or an arbitrary type. If the latter, then it will
be assumed that it is a Message payload, which will be extracted from the message and injected into such service
method. This is generally the recommended approach as it follows and promotes a POJO model when working with Spring
Integration. Arguments may also have @Header, @Headers or @MessageMapping annotations as described in <xref linkend="annotations"/>
</para>
<note>
Since v1.0.3 of Spring Integration, the service method is not required to have an argument at all, which means you
can now implement event-style Service Activators, where all you care about is an invocation of the service method,
not worrying about the contents of the message. Think of it as a NULL JMS message. An example use-case for such an
implementation could be a simple counter/monitor of messages deposited on the input channel.
</note>
<para>
Using a "ref" attribute is generally recommended if the custom Service Activator handler implementation can be reused
in other <code>&lt;service-activator&gt;</code> definitions. However if the custom Service Activator handler implementation
should be scoped to a single definition of the <code>&lt;service-activator&gt;</code>, you can use an inner bean definition:
<programlisting language="xml"><![CDATA[<service-activator id="exampleServiceActivator" input-channel="inChannel"
output-channel = "outChannel" method="foo">
<beans:bean class="org.foo.ExampleServiceActivator"/>
</service-activator>]]></programlisting>
</para>
<note>
<para>
Using both the "ref" attribute and an inner handler definition in the same <code>&lt;service-activator&gt;</code>
configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
</para>
</note>
</section>
</chapter>

158
spring-integration-reference/src/splitter.xml
View File

@@ -1,158 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="splitter">
<title>Splitter</title>
<section id="splitter-annotation">
<title>Introduction</title>
<para>The Splitter is a component whose role is to partition a message in
several parts, and send the resulting messages to be processed
independently. Very often, they are upstream producers in a pipeline that
includes an Aggregator.</para>
</section>
<section>
<title>Programming model</title>
<para>The API for performing splitting consists from one base class,
AbstractMessageSplitter, which is a MessageHandler implementation,
encapsulating features which are common to splitters, such as filling in
the appropriate message headers CORRELATION_ID, SEQUENCE_SIZE, and
SEQUENCE_NUMBER on the messages that are produced. This allows to track
down the messages and the results of their processing (in a typical
scenario, these headers would be copied over to the messages that are
produced by the various transforming endpoints), and use them, for
example, in a Composed Message Processor scenario.</para>
<para>An excerpt from AbstractMessageSplitter can be seen below:</para>
<programlisting lang="java">public abstract class AbstractMessageSplitter
extends AbstractReplyProducingMessageConsumer {
...
protected abstract Object splitMessage(Message&lt;?&gt; message);
}</programlisting>
<para>For implementing a specific Splitter in an application, a developer
can extend AbstractMessageSplitter and implement the splitMessage method,
thus defining the actual logic for splitting the messages. The return
value can be one of the following:</para>
<itemizedlist>
<listitem>
<para>a Collection (or subclass thereof) or an array of Message
objects - in this case the messages will be sent as such (after the
CORRELATION_ID, SEQUENCE_SIZE and SEQUENCE_NUMBER are populated).
Using this approach gives more control to the developer, for example
for populating custom message headers as part of the splitting
process.</para>
</listitem>
<listitem>
<para>a Collection (or subclass thereof) or an array of non-Message
objects - works like the prior case, except that each collection
element will be used as a Message payload. Using this approach allows
developers to focus on the domain objects without having to consider
the Messaging system and produces code that is easier to test.</para>
</listitem>
<listitem>
<para>a Message or non-Message object (but not a Collection or an
Array) - it works like the previous cases, except that there is a
single message to be sent out.</para>
</listitem>
</itemizedlist>
<para>In Spring Integration, any POJO can implement the splitting
algorithm, provided that it defines a method that accepts a single
argument and has a return value. In this case, the return value of the
method will be interpreted as described above. The input argument might
either be a Message or a simple POJO. In the latter case, the splitter
will receive the payload of the incoming message. Since this decouples
the code from the Spring Integration API and will typically be easier
to test, it is the recommended approach.</para>
</section>
<section>
<title>Configuring a Splitter using XML</title>
<para>A splitter can be configured through XML as follows:<programlisting>&lt;channel id="inputChannel"/&gt;
&lt;splitter id="splitter" <co id="split1" />
ref="splitterBean" <co id="split2" />
method="split" <co id="split3" />
input-channel="inputChannel" <co id="split4" />
output-channel="outputChannel" <co id="split5" />/&gt;
&lt;channel id="outputChannel"/&gt;
&lt;beans:bean id="splitterBean" class="sample.PojoSplitter"/&gt;</programlisting><calloutlist>
<callout arearefs="split1">
<para>The id of the splitter is
<emphasis>optional</emphasis>.</para>
</callout>
<callout arearefs="split2">
<para>A reference to a bean defined in the application context. The
bean must implement the splitting logic as described in the section
above. <emphasis>Optional</emphasis>.
If reference to a bean is not provided, then it is assumed that the <emphasis>payload</emphasis> of the Message that arrived on the <code>input-channel</code> is
an implementation of <emphasis>java.util.Collection</emphasis> and the default splitting logic will be applied on such Collection,
incorporating each individual element into a Message and depositing it on the <code>output-channel</code>.
</para>
</callout>
<callout arearefs="split3">
<para>The method (defined on the bean specified above) that
implements the splitting logic.
<emphasis>Optional</emphasis>.</para>
</callout>
<callout arearefs="split4">
<para>The input channel of the splitter.
<emphasis>Required</emphasis>.</para>
</callout>
<callout arearefs="split5">
<para>The channel where the splitter will send the results of
splitting the incoming message. <emphasis>Optional (because incoming
messages can specify a reply channel themselves)</emphasis>.</para>
</callout>
</calloutlist></para>
<para>
Using a "ref" attribute is generally recommended if the custom splitter handler implementation can be reused in other
<code>&lt;splitter&gt;</code> definitions. However if the custom splitter handler implementation should be scoped to a
single definition of the <code>&lt;splitter&gt;</code>, you can configure an inner bean definition:
<programlisting language="xml"><![CDATA[<splitter id="testSplitter" input-channel="inChannel" method="split"
output-channel="outChannel">
<beans:bean class="org.foo.TestSplitter"/>
</spliter>]]></programlisting>
</para>
<note>
<para>
Using both a "ref" attribute and an inner handler definition in the same <code>&lt;splitter&gt;</code>
configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
</para>
</note>
</section>
<section>
<title>Configuring a Splitter with Annotations</title>
<para>The <interfacename>@Splitter</interfacename> annotation is
applicable to methods that expect either the
<interfacename>Message</interfacename> type or the message payload type,
and the return values of the method should be a collection of any type. If
the returned values are not actual <interfacename>Message</interfacename>
objects, then each of them will be sent as the payload of a message. Those
messages will be sent to the output channel as designated for the endpoint
on which the <interfacename>@Splitter</interfacename> is defined.
<programlisting language="java">@Splitter
List&lt;LineItem&gt; extractItems(Order order) {
return order.getItems()
}</programlisting></para>
</section>
</chapter>

85
spring-integration-reference/src/spring-integration-reference.xml
View File

@@ -1,85 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo>
<title>Spring Integration Reference Manual</title>
<titleabbrev>Spring Integration 2.0.0 M4</titleabbrev>
<productname>Spring Integration</productname>
<releaseinfo>2.0.0 Milestone 4</releaseinfo>
<mediaobject>
<imageobject role="fo">
<imagedata align="center" fileref="images/logo.png" format="PNG"/>
</imageobject>
<imageobject role="html">
<imagedata align="right" fileref="images/logo.png" format="PNG"/>
</imageobject>
</mediaobject>
<authorgroup>
<author>
<firstname>Mark</firstname>
<surname>Fisher</surname>
</author>
<author>
<firstname>Marius</firstname>
<surname>Bogoevici</surname>
</author>
<author>
<firstname>Iwein</firstname>
<surname>Fuld</surname>
</author>
<author>
<firstname>Jonas</firstname>
<surname>Partner</surname>
</author>
<author>
<firstname>Oleg</firstname>
<surname>Zhurakousky</surname>
</author>
<author>
<firstname>Gary</firstname>
<surname>Russell</surname>
</author>
</authorgroup>
<legalnotice><para>&copy; SpringSource Inc., 2010</para></legalnotice>
</bookinfo>
<toc></toc>
<xi:include href="./overview.xml"/>
<xi:include href="./message.xml"/>
<xi:include href="./channel.xml"/>
<xi:include href="./endpoint.xml"/>
<xi:include href="./service-activator.xml"/>
<xi:include href="./channel-adapter.xml"/>
<xi:include href="./router.xml"/>
<xi:include href="./filter.xml"/>
<xi:include href="./transformer.xml"/>
<xi:include href="./splitter.xml"/>
<xi:include href="./aggregator.xml"/>
<xi:include href="./resequencer.xml"/>
<xi:include href="./delayer.xml"/>
<xi:include href="./chain.xml"/>
<xi:include href="./bridge.xml"/>
<xi:include href="./gateway.xml"/>
<xi:include href="./message-publishing.xml"/>
<xi:include href="./file.xml"/>
<xi:include href="./jms.xml"/>
<xi:include href="./ws.xml"/>
<xi:include href="./rmi.xml"/>
<xi:include href="./httpinvoker.xml"/>
<xi:include href="./http.xml"/>
<xi:include href="./ip.xml"/>
<xi:include href="./mail.xml"/>
<xi:include href="./jmx.xml"/>
<xi:include href="./stream.xml"/>
<xi:include href="./event.xml"/>
<xi:include href="./xml.xml"/>
<xi:include href="./security.xml"/>
<xi:include href="./samples.xml"/>
<xi:include href="./configuration.xml"/>
<xi:include href="./resources.xml"/>
</book>

91
spring-integration-reference/src/stream.xml
View File

@@ -1,91 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="stream">
<title>Stream Support</title>
<section id="stream-intro">
<title>Introduction</title>
<para>
In many cases application data is obtained from a stream. It is <emphasis>not</emphasis> recommended to send a reference to a Stream as a message payload to a consumer. Instead messages are created from data that is read from an input stream and message payloads are written to an output stream one by one.
</para>
</section>
<section id="stream-reading">
<title>Reading from streams</title>
<para>
Spring Integration provides two adapters for streams. Both <classname>ByteStreamReadingMessageSource</classname> and
<classname>CharacterStreamReadingMessageSource</classname> implement <interfacename>MessageSource</interfacename>.
By configuring one of these within a channel-adapter element, the polling period can be configured,
and the Message Bus can automatically detect and schedule them. The byte stream version requires an
<classname>InputStream</classname>, and the character stream version requires a <classname>Reader</classname> as
the single constructor argument. The <classname>ByteStreamReadingMessageSource</classname> also accepts the 'bytesPerMessage'
property to determine how many bytes it will attempt to read into each <interfacename>Message</interfacename>. The
default value is 1024
<programlisting language="xml"><![CDATA[<bean class="org.springframework.integration.stream.ByteStreamReadingMessageSource">
<constructor-arg ref="someInputStream"/>
<property name="bytesPerMessage" value="2048"/>
</bean>
<bean class="org.springframework.integration.stream.CharacterStreamReadingMessageSource">
<constructor-arg ref="someReader"/>
</bean>]]>
</programlisting>
</para>
</section>
<section id="stream-writing">
<title>Writing to streams</title>
<para>
For target streams, there are also two implementations: <classname>ByteStreamWritingMessageHandler</classname> and
<classname>CharacterStreamWritingMessageHandler</classname>. Each requires a single constructor argument -
<classname>OutputStream</classname> for byte streams or <classname>Writer</classname> for character streams,
and each provides a second constructor that adds the optional 'bufferSize'. Since both of these
ultimately implement the <interfacename>MessageHandler</interfacename> interface, they can be referenced from a
<emphasis>channel-adapter</emphasis> configuration as described in more detail in
<xref linkend="channel-adapter"/>.
<programlisting language="xml"><![CDATA[<bean class="org.springframework.integration.stream.ByteStreamWritingMessageHandler">
<constructor-arg ref="someOutputStream"/>
<constructor-arg value="1024"/>
</bean>
<bean class="org.springframework.integration.stream.CharacterStreamWritingMessageHandler">
<constructor-arg ref="someWriter"/>
</bean>]]>
</programlisting>
</para>
</section>
<section id="stream-namespace">
<title>Stream namespace support</title>
<para>
To reduce the configuration needed for stream related channel adapters there is a namespace defined. The following schema locations are needed to use it.
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns="http://www.springframework.org/schema/integration/stream"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/integration/stream
http://www.springframework.org/schema/integration/stream/spring-integration-stream-1.0.xsd">]]></programlisting>
</para>
<para>
To configure the inbound channel adapter the following code snippet shows the different configuration options that are supported.
<programlisting language="xml"><![CDATA[<stdin-channel-adapter id="adapterWithDefaultCharset"/>
<stdin-channel-adapter id="adapterWithProvidedCharset" charset="UTF-8"/>]]></programlisting>
</para>
<para>
To configure the outbound channel adapter you can use the namespace support as well. The following code snippet shows the different configuration for an outbound channel adapters.
<programlisting language="xml"><![CDATA[<stdout-channel-adapter id="stdoutAdapterWithDefaultCharset" channel="testChannel"/>
<stdout-channel-adapter id="stdoutAdapterWithProvidedCharset" charset="UTF-8" channel="testChannel"/>
<stderr-channel-adapter id="stderrAdapter" channel="testChannel"/>
<stdout-channel-adapter id="newlineAdapter" append-newline="true" channel="testChannel"/>
]]></programlisting>
</para>
</section>
</chapter>

122
spring-integration-reference/src/transformer.xml
View File

@@ -1,122 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="transformer">
<title>Transformer</title>
<section id="transformer-introduction">
<title>Introduction</title>
<para>
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.
</para>
<para>
For some systems, it may be best to provide a
<ulink url="http://www.eaipatterns.com/CanonicalDataModel.html">Canonical Data Model</ulink>, 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
<xref linkend="xml"/>.
</note>
</para>
</section>
<section id="transformer-namespace">
<title>The &lt;transformer&gt; Element</title>
<para>
The &lt;transformer&gt; 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.
<programlisting language="xml"><![CDATA[<transformer id="testTransformer" ref="testTransformerBean" input-channel="inChannel"
method="transform" output-channel="outChannel"/>
<beans:bean id="testTransformerBean" class="org.foo.TestTransformer" />]]></programlisting>
</para>
<para>
Using a "ref" attribute is generally recommended if the custom transformer handler implementation can be reused in
other <code>&lt;transformer&gt;</code> definitions. However if the custom transformer handler implementation should
be scoped to a single definition of the <code>&lt;transformer&gt;</code>, you can define an inner bean definition:
<programlisting language="xml"><![CDATA[<transformer id="testTransformer" input-channel="inChannel" method="transform"
output-channel="outChannel">
<beans:bean class="org.foo.TestTransformer"/>
</transformer>]]></programlisting>
</para>
<note>
<para>
Using both the "ref" attribute and an inner handler definition in the same <code>&lt;transformer&gt;</code>
configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
</para>
</note>
<para>
The method that is used for transformation may expect either the <interfacename>Message</interfacename> 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 <interfacename>Message</interfacename>, that will be passed along to
the transformer's output channel. If the return type is a Map, and the original Message payload was
<emphasis>not</emphasis> a Map, the entries in that Map will be added to the Message headers of the original
Message (the keys must be Strings). If the return value is <emphasis>null</emphasis>, then no reply Message will
be sent (effectively the same behavior as a Message Filter returning false). Otherwise, the return value will be
sent as the payload of an outbound reply Message.
</para>
<para>
There are a also a few Transformer implementations available out of the box. Because, it is fairly common
to use the <methodname>toString()</methodname> representation of an Object, Spring Integration provides an
<classname>ObjectToStringTransformer</classname> 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.
<programlisting language="xml"><![CDATA[ <object-to-string-transformer input-channel="in" output-channel="out"/>]]></programlisting>
A potential example for this would be sending some arbitrary object to the 'outbound-channel-adapter' in the
<emphasis>file</emphasis> namespace. Whereas that Channel Adapter only supports String, byte-array, or
<classname>java.io.File</classname> 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
<methodname>toString()</methodname> 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 <xref linkend="channel-wiretap"/> for more detail.
</tip>
</para>
<para>
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.
<programlisting language="xml"><![CDATA[ <payload-serializing-transformer input-channel="objectsIn" output-channel="bytesOut"/>
<payload-deserializing-transformer input-channel="bytesIn" output-channel="objectsOut"/>]]></programlisting>
</para>
<para>
If you only need to add headers to a Message, and they are not dynamically determined by Message content,
then referencing a custom implementation may be overkill. For that reason, Spring Integration provides the
'header-enricher' element. <programlisting language="xml"><![CDATA[ <header-enricher input-channel="in" output-channel="out">
<header name="foo" value="123"/>
<header name="bar" ref="someBean"/>
</header-enricher>]]></programlisting>
</para>
</section>
<section id="transformer-annotation">
<title>The @Transformer Annotation</title>
<para>
The <interfacename>@Transformer</interfacename> annotation can also be added to methods that expect either the
<interfacename>Message</interfacename> 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 &lt;transformer&gt; element.
<programlisting language="java">@Transformer
Order generateOrder(String productId) {
return new Order(productId);
}</programlisting>
</para>
<para>
Transformer methods may also accept the @Header and @Headers annotations that is documented in <xref linkend="annotations"/>
<programlisting language="java">@Transformer
Order generateOrder(String productId, @Header("customerName") String customer) {
return new Order(productId, customer);
}</programlisting>
</para>
</section>
</chapter>

134
spring-integration-reference/src/ws.xml
View File

@@ -1,134 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="ws">
<title>Web Services Support</title>
<section id="webservices-outbound">
<title>Outbound Web Service Gateways</title>
<para>
To invoke a Web Service upon sending a message to a channel, there are two options - both of which build
upon the <ulink url="http://static.springframework.org/spring-ws/sites/1.5/">Spring Web Services</ulink>
project: <classname>SimpleWebServiceOutboundGateway</classname> and
<classname>MarshallingWebServiceOutboundGateway</classname>. The former will accept either a
<classname>String</classname> or <interfacename>javax.xml.transform.Source</interfacename> as the message
payload. The latter provides support for any implementation of the <interfacename>Marshaller</interfacename>
and <interfacename>Unmarshaller</interfacename> interfaces. Both require a Spring Web Services
<interfacename>DestinationProvider</interfacename> for determining the URI of the Web Service to be
called.<programlisting language="java"> simpleGateway = new SimpleWebServiceOutboundGateway(destinationProvider);
marshallingGateway = new MarshallingWebServiceOutboundGateway(destinationProvider, marshaller);
</programlisting>
<note>
When using the namespace support described below, you will only need to set a URI. Internally, the parser
will configure a fixed URI DestinationProvider implementation. If you do need dynamic resolution of the
URI at runtime, however, then the DestinationProvider can provide such behavior as looking up the URI from
a registry. See the Spring Web Services
<ulink url="http://static.springsource.org/spring-ws/sites/1.5/apidocs/index.html">javadoc</ulink> for
more information about the DestinationProvider strategy.
</note>
</para>
<para>
For more detail on the inner workings, see the Spring Web Services reference guide's chapter covering
<ulink url="http://static.springframework.org/spring-ws/site/reference/html/client.html">client access</ulink>
as well as the chapter covering
<ulink url="http://static.springframework.org/spring-ws/site/reference/html/oxm.html">Object/XML mapping</ulink>.
</para>
</section>
<section id="webservices-inbound">
<title>Inbound Web Service Gateways</title>
<para>
To send a message to a channel upon receiving a Web Service invocation, there are two options again: <classname>SimpleWebServiceInboundGateway</classname> and
<classname>MarshallingWebServiceInboundGateway</classname>. The former will extract a <interfacename>javax.xml.transform.Source</interfacename>
from the <classname>WebServiceMessage</classname> and set it as the message
payload. The latter provides support for implementation of the <interfacename>Marshaller</interfacename>
and <interfacename>Unmarshaller</interfacename> interfaces.
If the incoming web service message is a SOAP message the SOAP Action header will be added to the headers of the
<classname>Message</classname> that is forwarded onto the request channel.
<programlisting language="java"> simpleGateway = new SimpleWebServiceInboundGateway();
simpleGateway.setRequestChannel(forwardOntoThisChannel);
simpleGateway.setReplyChannel(listenForResponseHere); //Optional
marshallingGateway = new MarshallingWebServiceInboundGateway(marshaller);
//set request and optionally reply channel
</programlisting>
Both gateways implement the Spring Web Services <interfacename>MessageEndpoint</interfacename>
interface, so they can be configured with a <classname>MessageDispatcherServlet</classname>
as per standard Spring Web Services configuration.
</para>
<para>
For more detail on how to use these components, see the Spring Web Services reference guide's chapter covering
<ulink url="http://static.springframework.org/spring-ws/sites/1.5/reference/html/server.html">creating a Web Service</ulink>.
The chapter covering
<ulink url="http://static.springframework.org/spring-ws/site/reference/html/oxm.html">Object/XML mapping</ulink> is also applicable again.
</para>
</section>
<section id="webservices-namespace">
<title>Web Service Namespace Support</title>
<para>
To configure an outbound Web Service Gateway, use the "outbound-gateway" element from the "ws" namespace:
<programlisting language="xml"><![CDATA[<ws:outbound-gateway id="simpleGateway"
request-channel="inputChannel"
uri="http://example.org"/>]]></programlisting>
<note>
Notice that this example does not provide a 'reply-channel'. If the Web Service were to
return a non-empty response, the Message containing that response would be sent to the
reply channel provided in the request Message's REPLY_CHANNEL header, and if that were
not available a channel resolution Exception would be thrown. If you want to send the
reply to another channel instead, then provide a 'reply-channel' attribute on the
'outbound-gateway' element.
</note>
<tip>
When invoking a Web Service that returns an empty response after using a String payload
for the request Message, <emphasis>no reply Message will be sent by default</emphasis>.
Therefore you don't need to set a 'reply-channel' or have a REPLY_CHANNEL header in the
request Message. If for any reason you actually <emphasis>do</emphasis> want to receive
the empty response as a Message, then provide the 'ignore-empty-responses' attribute with
a value of <emphasis>false</emphasis> (this only applies for Strings, because using a
Source or Document object simply leads to a NULL response and will therefore
<emphasis>never</emphasis> generate a reply Message).
</tip>
To set up an inbound Web Service Gateway, use the "inbound-gateway":
<programlisting language="xml"><![CDATA[<ws:inbound-gateway id="simpleGateway"
request-channel="inputChannel"/>]]></programlisting>
To use Spring OXM Marshallers and/or Unmarshallers, provide bean references. For outbound:
<programlisting language="xml"><![CDATA[<ws:outbound-gateway id="marshallingGateway"
request-channel="requestChannel"
uri="http://example.org"
marshaller="someMarshaller"
unmarshaller="someUnmarshaller"/>]]></programlisting>
And for inbound:
<programlisting language="xml"><![CDATA[<ws:inbound-gateway id="marshallingGateway"
request-channel="requestChannel"
marshaller="someMarshaller"
unmarshaller="someUnmarshaller"/>]]></programlisting>
<note>
Most <interfacename>Marshaller</interfacename> implementations also implement the
<interfacename>Unmarshaller</interfacename> interface. When using such a
<interfacename>Marshaller</interfacename>, only the "marshaller"
attribute is necessary. Even when using a <interfacename>Marshaller</interfacename>,
you may also provide a reference for the "request-callback" on the outbound gateways.
</note>
</para>
<para>
For either outbound gateway type, a "destination-provider" attribute can be specified instead of the "uri"
(exactly one of them is required). You can then reference any Spring Web Services DestinationProvider
implementation (e.g. to lookup the URI at runtime from a registry).
</para>
<para>
For either outbound gateway type, the "message-factory" attribute can also be configured with a reference to any
Spring Web Services <interfacename>WebServiceMessageFactory</interfacename> implementation.
</para>
<para>
For the simple inbound gateway type, the "extract-payload" attribute can be set to false to forward
the entire <interfacename>WebServiceMessage</interfacename> instead of just its payload as a
<interfacename>Message</interfacename> to the request channel. This might be useful, for example,
when a custom Transformer works against the <interfacename>WebServiceMessage</interfacename> directly.
</para>
</section>
</chapter>

391
spring-integration-reference/src/xml.xml
View File

@@ -1,391 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="xml">
<title>Dealing with XML Payloads</title>
<section id="xml-intro">
<title>Introduction</title>
<para>
Spring Integration's XML support extends the Spring Integration Core with
implementations of splitter, transformer, selector and router designed
to make working with xml messages in Spring Integration simple. The provided messaging
components are designed to work with xml represented in a range of formats including
instances of
<classname>java.lang.String</classname>, <interfacename>org.w3c.dom.Document</interfacename>
and <interfacename>javax.xml.transform.Source</interfacename>. It should be noted however that
where a DOM representation is required, for example in order to evaluate an XPath expression,
the <classname>String</classname> payload will be converted into the required type and then
converted back again to <classname>String</classname>. Components that require an instance of
<interfacename>DocumentBuilder</interfacename> will create a namespace aware instance if one is
not provided. Where greater control of the document being created is required an appropriately
configured instance of <interfacename>DocumentBuilder</interfacename> should be provided.
</para>
</section>
<section id="xml-transformation">
<title>Transforming xml payloads</title>
<para>
This section will explain the workings of
<classname>UnmarshallingTransformer</classname>,
<classname>MarshallingTransformer</classname>,
<classname>XsltPayloadTransformer</classname>
and how to configure them as
<emphasis>beans</emphasis>. All of the provided xml transformers extend
<classname>AbstractTransformer</classname> or <classname>AbstractPayloadTransformer</classname>
and therefore implement <interfacename>Transformer</interfacename>. When configuring xml
transformers as beans in Spring Integration you would normally configure the transformer
in conjunction with either a <classname>MessageTransformingChannelInterceptor</classname> or a
<classname>MessageTransformingHandler</classname>. This allows the transformer to be used as either an interceptor,
which transforms the message as it is sent or received to the channel, or as an endpoint. Finally the
namespace support will be discussed which allows for the simple configuration of the transformers as
elements in XML.
</para>
<para>
<classname>UnmarshallingTransformer</classname> allows an xml <interfacename>Source</interfacename>
to be unmarshalled using implementations of Spring OXM <interfacename>Unmarshaller</interfacename>.
Spring OXM provides several implementations supporting marshalling and unmarshalling using JAXB,
Castor and JiBX amongst others. Since the unmarshaller requires an instance of
<interfacename>Source</interfacename> where the message payload is not currently an instance of
<interfacename>Source</interfacename>, conversion will be attempted. Currently <classname>String</classname>
and <interfacename>org.w3c.dom.Document</interfacename> payloads are supported. Custom conversion to a
<interfacename>Source</interfacename> is also supported by injecting an implementation of
<interfacename>SourceFactory</interfacename>.
<programlisting language="xml"><![CDATA[<bean id="unmarshallingTransformer"
class="org.springframework.integration.xml.transformer.UnmarshallingTransformer">
<constructor-arg>
<bean class="org.springframework.oxm.jaxb.Jaxb1Marshaller">
<property name="contextPath" value="org.example" />
</bean>
</constructor-arg>
</bean>]]></programlisting>
</para>
<para>
The <classname>MarshallingTransformer</classname> allows an object graph to be converted
into xml using a Spring OXM <interfacename>Marshaller</interfacename>. By default the
<classname>MarshallingTransformer</classname> will return a <classname>DomResult</classname>.
However the type of result can be controlled by configuring an alternative <interfacename>ResultFactory</interfacename>
such as <classname>StringResultFactory</classname>. In many cases it will be more convenient to transform
the payload into an alternative xml format. To achieve this configure a
<interfacename>ResultTransformer</interfacename>. Two implementations are provided, one which converts to
<classname>String</classname> and another which converts to <interfacename>Document</interfacename>.
<programlisting language="xml"><![CDATA[<bean id="marshallingTransformer"
class="org.springframework.integration.xml.transformer.MarshallingTransformer">
<constructor-arg>
<bean class="org.springframework.oxm.jaxb.Jaxb1Marshaller">
<property name="contextPath" value="org.example" />
</bean>
</constructor-arg>
<constructor-arg>
<bean class="org.springframework.integration.xml.transformer.ResultToDocumentTransformer" />
</constructor-arg>
</bean>]]></programlisting>
</para>
<para>
By default, the <classname>MarshallingTransformer</classname> will pass the payload Object
to the <interfacename>Marshaller</interfacename>, but if its boolean "extractPayload" property
is set to "false", the entire <interfacename>Message</interfacename> instance will be passed
to the <interfacename>Marshaller</interfacename> instead. That may be useful for certain custom
implementations of the <interfacename>Marshaller</interfacename> interface, but typically the
payload is the appropriate source Object for marshalling when delegating to any of the various
out-of-the-box <interfacename>Marshaller</interfacename> implementations.
</para>
<para>
<classname>XsltPayloadTransformer</classname> transforms xml payloads using xsl.
The transformer requires an instance of either <interfacename>Resource</interfacename> or
<interfacename>Templates</interfacename>. Passing in a <interfacename>Templates</interfacename> instance
allows for greater configuration of the <interfacename>TransformerFactory</interfacename> used to create
the template instance. As in the case of <classname>XmlPayloadMarshallingTransformer</classname>
by default <classname>XsltPayloadTransformer</classname> will create a message with a
<interfacename>Result</interfacename> payload. This can be customised by providing a
<interfacename>ResultFactory</interfacename> and/or a <interfacename>ResultTransformer</interfacename>.
<programlisting language="xml"><![CDATA[<bean id="xsltPayloadTransformer"
class="org.springframework.integration.xml.transformer.XsltPayloadTransformer">
<constructor-arg value="classpath:org/example/xsl/transform.xsl" />
<constructor-arg>
<bean class="org.springframework.integration.xml.transformer.ResultToDocumentTransformer" />
</constructor-arg>
</bean>]]></programlisting>
</para>
</section>
<section id="xml-transformer-namespace">
<title>Namespace support for xml transformers</title>
<para>
Namespace support for all xml transformers is provided in the Spring Integration xml namespace,
a template for which can be seen below. The namespace support for transformers creates an instance of either
<classname>EventDrivenConsumer</classname> or <classname>PollingConsumer</classname>
according to the type of the provided input channel. The namespace support is designed
to reduce the amount of xml configuration by allowing the creation of an endpoint and transformer
using one element.
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:integration="http://www.springframework.org/schema/integration"
xmlns:si-xml="http://www.springframework.org/schema/integration/xml"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration-1.0.xsd
http://www.springframework.org/schema/integration/xml
http://www.springframework.org/schema/integration/xml/spring-integration-xml-1.0.xsd">
</beans>]]></programlisting>
The namespace support for <classname>UnmarshallingTransformer</classname> is shown below.
Since the namespace is now creating an endpoint instance rather than a transformer,
a poller can also be nested within the element to control the polling of the input channel.
<programlisting language="xml"><![CDATA[<si-xml:unmarshalling-transformer id="defaultUnmarshaller"
input-channel="input"
output-channel="output"
unmarshaller="unmarshaller"/>
<si-xml:unmarshalling-transformer id="unmarshallerWithPoller"
input-channel="input"
output-channel="output"
unmarshaller="unmarshaller">
<si:poller>
<si:interval-trigger interval="2000"/>
</si:poller>
<si-xml:unmarshalling-transformer/>
]]></programlisting>
</para>
<para>
The namespace support for the marshalling transformer requires an input channel, output channel and a
reference to a marshaller. The optional result-type attribute can be used to control the type of result created,
valid values are StringResult or DomResult (the default). Where the provided result types are not sufficient a
reference to a custom implementation of <interfacename>ResultFactory</interfacename> can be provided as an alternative
to setting the result-type attribute using the result-factory attribute. An optional result-transformer can also be
specified in order to convert the created <interfacename>Result</interfacename> after marshalling.
<programlisting language="xml"><![CDATA[<si-xml:marshalling-transformer
input-channel="marshallingTransformerStringResultFactory"
output-channel="output"
marshaller="marshaller"
result-type="StringResult" />
<si-xml:marshalling-transformer
input-channel="marshallingTransformerWithResultTransformer"
output-channel="output"
marshaller="marshaller"
result-transformer="resultTransformer" />
<bean id="resultTransformer"
class="org.springframework.integration.xml.transformer.ResultToStringTransformer"/>]]></programlisting>
</para>
<para>
Namespace support for the <classname>XsltPayloadTransformer</classname> allows either a resource to be passed in in order to create the
<interfacename>Templates</interfacename> instance or alternatively a precreated <interfacename>Templates</interfacename>
instance can be passed in as a reference. In common with the marshalling transformer the type of the result output can
be controlled by specifying either the result-factory or result-type attribute. A result-transfomer attribute can also
be used to reference an implementation of <interfacename>ResultTransfomer</interfacename> where conversion of the result
is required before sending.
<programlisting language="xml"><![CDATA[<si-xml:xslt-transformer id="xsltTransformerWithResource"
input-channel="withResourceIn"
output-channel="output"
xsl-resource="org/springframework/integration/xml/config/test.xsl"/>
<si-xml:xslt-transformer id="xsltTransformerWithTemplatesAndResultTransformer"
input-channel="withTemplatesAndResultTransformerIn"
output-channel="output"
xsl-templates="templates"
result-transformer="resultTransformer"/>]]></programlisting>
</para>
</section>
<section id="xpath-splitting">
<title>Splitting xml messages</title>
<para>
<classname>XPathMessageSplitter</classname> supports messages with either
<classname>String</classname> or <interfacename>Document</interfacename> payloads.
The splitter uses the provided XPath expression to split the payload into a number of
nodes. By default this will result in each <interfacename>Node</interfacename> instance
becoming the payload of a new message. Where it is preferred that each message be a Document
the <methodname>createDocuments</methodname> flag can be set. Where a <classname>String</classname> payload is passed
in the payload will be converted then split before being converted back to a number of String
messages. The XPath splitter implements <interfacename>MessageHandler</interfacename> and should
therefore be configured in conjunction with an appropriate endpoint (see the namespace support below
for a simpler configuration alternative).
<programlisting language="xml"><![CDATA[<bean id="splittingEndpoint"
class="org.springframework.integration.endpoint.EventDrivenConsumer">
<constructor-arg ref="orderChannel" />
<constructor-arg>
<bean class="org.springframework.integration.xml.splitter.XPathMessageSplitter">
<constructor-arg value="/order/items" />
<property name="documentBuilder" ref="customisedDocumentBuilder" />
<property name="outputChannel" ref="orderItemsChannel" />
</bean>
</constructor-arg>
</bean>]]></programlisting>
</para>
</section>
<section id="xpath-routing">
<title>Routing xml messages using XPath</title>
<para>
Two Router implementations based on XPath are provided <classname>XPathSingleChannelRouter</classname> and
<classname>XPathMultiChannelRouter</classname>. The implementations differ in respect to how many channels
any given message may be routed to, exactly one in the case of the single channel version
or zero or more in the case of the multichannel router. Both evaluate an XPath
expression against the xml payload of the message, supported payload types by default
are <interfacename>Node</interfacename>, <interfacename>Document</interfacename> and
<interfacename>String</interfacename>. For other payload types a custom implementation
of <interfacename>XmlPayloadConverter</interfacename> can be provided. The router
implementations use <interfacename>ChannelResolver</interfacename> to convert the
result(s) of the XPath expression to a channel name. By default a
<classname>BeanFactoryChannelResolver</classname> strategy will be used, this means that the string returned by the XPath
evaluation should correspond directly to the name of a channel. Where this is not the case
an alternative implementation of <interfacename>ChannelResolver</interfacename> can
be used. Where there is a simple mapping from Xpath result to channel name
the provided <classname>MapBasedChannelResolver</classname> can be used.
<programlisting language="xml"><![CDATA[<!-- Expects a channel for each value of order type to exist -->
<bean id="singleChannelRoutingEndpoint"
class="org.springframework.integration.endpoint.EventDrivenConsumer">
<constructor-arg ref="orderChannel" />
<constructor-arg>
<bean class="org.springframework.integration.xml.router.XPathSingleChannelRouter">
<constructor-arg value="/order/@type" />
</bean>
</constructor-arg>
</bean>
<!-- Multi channel router which uses a map channel resolver to resolve the channel name
based on the XPath evaluation result Since the router is multi channel it may deliver
message to one or both of the configured channels -->
<bean id="multiChannelRoutingEndpoint"
class="org.springframework.integration.endpoint.EventDrivenConsumer">
<constructor-arg ref="orderChannel" />
<constructor-arg>
<bean class="org.springframework.integration.xml.router.XPathMultiChannelRouter">
<constructor-arg value="/order/recipient" />
<property name="channelResolver">
<bean class="org.springframework.integration.channel.MapBasedChannelResolver">
<constructor-arg>
<map>
<entry key="accounts"
value-ref="accountConfirmationChannel" />
<entry key="humanResources"
value-ref="humanResourcesConfirmationChannel" />
</map>
</constructor-arg>
</bean>
</property>
</bean>
</constructor-arg>
</bean>]]></programlisting>
</para>
</section>
<section id="xpath-selector">
<title>Selecting xml messages using XPath</title>
<para>
Two <interfacename>MessageSelector</interfacename> implementations are provided,
<classname>BooleanTestXPathMessageSelector</classname> and <classname>StringValueTestXPathMessageSelector</classname>.
<classname>BooleanTestXPathMessageSelector</classname> requires an XPathExpression which evaluates to a boolean,
for example <emphasis>boolean(/one/two)</emphasis> which will only select messages which have an element named
two which is a child of a root element named one. <classname>StringValueTestXPathMessageSelector</classname>
evaluates any XPath expression as a <classname>String</classname> and compares the result with the provided value.
</para>
<programlisting language="xml"><![CDATA[<!-- Interceptor which rejects messages that do not have a root element order -->
<bean id="orderSelectingInterceptor"
class="org.springframework.integration.channel.interceptor.MessageSelectingInterceptor">
<constructor-arg>
<bean class="org.springframework.integration.xml.selector.BooleanTestXPathMessageSelector">
<constructor-arg value="boolean(/order)" />
</bean>
</constructor-arg>
</bean>
<!-- Interceptor which rejects messages that are not version one orders -->
<bean id="versionOneOrderSelectingInterceptor"
class="org.springframework.integration.channel.interceptor.MessageSelectingInterceptor">
<constructor-arg>
<bean class="org.springframework.integration.xml.selector.StringValueTestXPathMessageSelector">
<constructor-arg value="/order/@version" index="0"/>
<constructor-arg value="1" index="1"/>
</bean>
</constructor-arg>
</bean>]]></programlisting>
</section>
<section id="xpath-namespace-support">
<title>XPath components namespace support</title>
<para>All XPath based components have namespace support allowing them to be configured as
Message Endpoints with the exception of the XPath selectors which are not designed to act as
endpoints. Each component allows the XPath to either be referenced at the top level or configured via a nested
xpath-expression element. So the following configurations of an xpath-selector are all valid and represent the general
form of XPath namespace support. All forms of XPath expression result in the creation of an
<interfacename>XPathExpression</interfacename> using the Spring <classname>XPathExpressionFactory</classname>
<programlisting language="xml"><![CDATA[<si-xml:xpath-selector id="xpathRefSelector"
xpath-expression="refToXpathExpression"
evaluation-result-type="boolean" />
<si-xml:xpath-selector id="selectorWithNoNS" evaluation-result-type="boolean" >
<si-xml:xpath-expression expression="/name"/>
</si-xml:xpath-selector>
<si-xml:xpath-selector id="selectorWithOneNS" evaluation-result-type="boolean" >
<si-xml:xpath-expression expression="/ns1:name"
ns-prefix="ns1" ns-uri="www.example.org" />
</si-xml:xpath-selector>
<si-xml:xpath-selector id="selectorWithTwoNS" evaluation-result-type="boolean" >
<si-xml:xpath-expression expression="/ns1:name/ns2:type">
<map>
<entry key="ns1" value="www.example.org/one" />
<entry key="ns2" value="www.example.org/two" />
</map>
</si-xml:xpath-expression>
</si-xml:xpath-selector>
<si-xml:xpath-selector id="selectorWithNamespaceMapRef" evaluation-result-type="boolean" >
<si-xml:xpath-expression expression="/ns1:name/ns2:type"
namespace-map="defaultNamespaces"/>
</si-xml:xpath-selector>
<util:map id="defaultNamespaces">
<util:entry key="ns1" value="www.example.org/one" />
<util:entry key="ns2" value="www.example.org/two" />
</util:map>]]></programlisting>
</para>
<para>
XPath splitter namespace support allows the creation of a Message Endpoint with an input channel and output channel.
<programlisting language="xml"><![CDATA[<!-- Split the order into items creating a new message for each item node -->
<si-xml:xpath-splitter id="orderItemSplitter"
input-channel="orderChannel"
output-channel="orderItemsChannel">
<si-xml:xpath-expression expression="/order/items"/>
</si-xml:xpath-splitter>
<!-- Split the order into items creating a new document for each item-->
<si-xml:xpath-splitter id="orderItemDocumentSplitter"
input-channel="orderChannel"
output-channel="orderItemsChannel"
create-documents="true">
<si-xml:xpath-expression expression="/order/items"/>
<si:poller>
<si:interval-trigger interval="2000"/>
</si:poller>
</si-xml:xpath-splitter>]]></programlisting>
</para>
<para>
XPath router namespace support allows for the creation of a Message Endpoint with an input channel but no output channel
since the output channel is determined dynamically. The multi-channel attribute causes the creation of a multi channel router capable of
routing a single message to many channels when true and a single channel router when false.
<programlisting language="xml"><![CDATA[<!-- route the message according to exactly one order type channel -->
<si-xml:xpath-router id="orderTypeRouter" input-channel="orderChannel" multi-channel="false">
<si-xml:xpath-expression expression="/order/type"/>
</si-xml:xpath-router>
<!-- route the order to all responders-->
<si-xml:xpath-router id="responderRouter" input-channel="orderChannel" multi-channel="true">
<si-xml:xpath-expression expression="/request/responders"/>
<si:poller>
<si:interval-trigger interval="2000"/>
</si:poller>
</si-xml:xpath-router>]]></programlisting>
</para>
</section>
</chapter>

136
spring-integration-reference/styles/html/custom.xsl
View File

@@ -1,136 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:xslthl="http://xslthl.sf.net"
exclude-result-prefixes="xslthl"
version='1.0'>
<xsl:param name="chunk.section.depth">'5'</xsl:param>
<xsl:param name="use.id.as.filename" select="1"/>
<!-- Extensions -->
<xsl:param name="use.extensions">1</xsl:param>
<xsl:param name="tablecolumns.extension">0</xsl:param>
<xsl:param name="callout.extensions">1</xsl:param>
<!-- Activate Graphics -->
<xsl:param name="admon.graphics" select="1"/>
<xsl:param name="admon.graphics.path">images/</xsl:param>
<xsl:param name="admon.graphics.extension">.gif</xsl:param>
<xsl:param name="callout.graphics" select="1" />
<xsl:param name="callout.defaultcolumn">120</xsl:param>
<xsl:param name="callout.graphics.path">images/callouts/</xsl:param>
<xsl:param name="callout.graphics.extension">.gif</xsl:param>
<xsl:param name="table.borders.with.css" select="1"/>
<xsl:param name="html.stylesheet">css/stylesheet.css</xsl:param>
<xsl:param name="html.stylesheet.type">text/css</xsl:param>
<xsl:param name="generate.toc">book toc,title</xsl:param>
<xsl:param name="admonition.title.properties">text-align: left</xsl:param>
<!-- Label Chapters and Sections (numbering) -->
<xsl:param name="chapter.autolabel" select="1"/>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.autolabel.max.depth" select="3"/>
<xsl:param name="section.label.includes.component.label" select="1"/>
<xsl:param name="table.footnote.number.format" select="'1'"/>
<!-- Show only Sections up to level 3 in the TOCs -->
<xsl:param name="toc.section.depth">3</xsl:param>
<!-- Remove "Chapter" from the Chapter titles... -->
<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
<l:l10n language="en">
<l:context name="title-numbered">
<l:template name="chapter" text="%n.&#160;%t"/>
<l:template name="section" text="%n&#160;%t"/>
</l:context>
</l:l10n>
</l:i18n>
<!-- Use code syntax highlighting -->
<xsl:param name="highlight.source" select="1"/>
<xsl:template match='xslthl:keyword'>
<span class="hl-keyword"><xsl:value-of select='.'/></span>
</xsl:template>
<xsl:template match='xslthl:comment'>
<span class="hl-comment"><xsl:value-of select='.'/></span>
</xsl:template>
<xsl:template match='xslthl:oneline-comment'>
<span class="hl-comment"><xsl:value-of select='.'/></span>
</xsl:template>
<xsl:template match='xslthl:multiline-comment'>
<span class="hl-multiline-comment"><xsl:value-of select='.'/></span>
</xsl:template>
<xsl:template match='xslthl:tag'>
<span class="hl-tag"><xsl:value-of select='.'/></span>
</xsl:template>
<xsl:template match='xslthl:attribute'>
<span class="hl-attribute"><xsl:value-of select='.'/></span>
</xsl:template>
<xsl:template match='xslthl:value'>
<span class="hl-value"><xsl:value-of select='.'/></span>
</xsl:template>
<xsl:template match='xslthl:string'>
<span class="hl-string"><xsl:value-of select='.'/></span>
</xsl:template>
<!-- Google Analytics -->
<xsl:template name="user.head.content">
<xsl:comment>Begin Google Analytics code</xsl:comment>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
var pageTracker = _gat._getTracker("UA-2728886-3");
pageTracker._setDomainName("none");
pageTracker._setAllowLinker(true);
pageTracker._trackPageview();
</script>
<xsl:comment>End Google Analytics code</xsl:comment>
</xsl:template>
<!-- Loopfuse -->
<xsl:template name="user.footer.content">
<xsl:comment>Begin LoopFuse code</xsl:comment>
<script src="http://loopfuse.net/webrecorder/js/listen.js" type="text/javascript">
</script>
<script type="text/javascript">
_lf_cid = "LF_48be82fa";
_lf_remora();
</script>
<xsl:comment>End LoopFuse code</xsl:comment>
</xsl:template>
</xsl:stylesheet>

61
spring-integration-reference/styles/html/titlepage.xml
View File

@@ -1,61 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<!-- ==================================================================== -->
<t:titlepage t:element="book" t:wrapper="div" class="titlepage">
<t:titlepage-content t:side="recto">
<productname/>
<title/>
<subtitle/>
<!-- <corpauthor/>
<authorgroup/>
<author/>
<mediaobject/> -->
<othercredit/>
<releaseinfo/>
<copyright/>
<legalnotice/>
<pubdate/>
<revision/>
<revhistory/>
<abstract/>
</t:titlepage-content>
<t:titlepage-content t:side="verso">
</t:titlepage-content>
<t:titlepage-separator>
<hr/>
</t:titlepage-separator>
<t:titlepage-before t:side="recto">
</t:titlepage-before>
<t:titlepage-before t:side="verso">
</t:titlepage-before>
</t:titlepage>
</t:templates>

518
spring-integration-reference/styles/pdf/custom.xsl
View File

@@ -1,518 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:xslthl="http://xslthl.sf.net"
exclude-result-prefixes="xslthl"
version='1.0'>
<!-- Use nice graphics for admonitions -->
<xsl:param name="admon.graphics">'1'</xsl:param>
<xsl:param name="admon.graphics.path">@file.prefix@@dbf.xsl@/images/</xsl:param>
<xsl:param name="draft.watermark.image" select="'@file.prefix@@dbf.xsl@/images/draft.png'"/>
<xsl:param name="paper.type" select="'@paper.type@'"/>
<xsl:param name="page.margin.top" select="'1cm'"/>
<xsl:param name="region.before.extent" select="'1cm'"/>
<xsl:param name="body.margin.top" select="'1.5cm'"/>
<xsl:param name="body.margin.bottom" select="'1.5cm'"/>
<xsl:param name="region.after.extent" select="'1cm'"/>
<xsl:param name="page.margin.bottom" select="'1cm'"/>
<xsl:param name="title.margin.left" select="'0cm'"/>
<!--###################################################
Header
################################################### -->
<!-- More space in the center header for long text -->
<xsl:attribute-set name="header.content.properties">
<xsl:attribute name="font-family">
<xsl:value-of select="$body.font.family"/>
</xsl:attribute>
<xsl:attribute name="margin-left">-5em</xsl:attribute>
<xsl:attribute name="margin-right">-5em</xsl:attribute>
</xsl:attribute-set>
<!--###################################################
Table of Contents
################################################### -->
<xsl:param name="generate.toc">
book toc,title
</xsl:param>
<!--###################################################
Custom Header
################################################### -->
<xsl:template name="header.content">
<xsl:param name="pageclass" select="''"/>
<xsl:param name="sequence" select="''"/>
<xsl:param name="position" select="''"/>
<xsl:param name="gentext-key" select="''"/>
<xsl:variable name="Version">
<xsl:choose>
<xsl:when test="//productname">
<xsl:value-of select="//productname"/><xsl:text> </xsl:text>
</xsl:when>
<xsl:otherwise>
<xsl:text>please define productname in your docbook file!</xsl:text>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:choose>
<xsl:when test="$sequence='blank'">
<xsl:choose>
<xsl:when test="$position='center'">
<xsl:value-of select="$Version"/>
</xsl:when>
<xsl:otherwise>
<!-- nop -->
</xsl:otherwise>
</xsl:choose>
</xsl:when>
<xsl:when test="$pageclass='titlepage'">
<!-- nop: other titlepage sequences have no header -->
</xsl:when>
<xsl:when test="$position='center'">
<xsl:value-of select="$Version"/>
</xsl:when>
<xsl:otherwise>
<!-- nop -->
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!--###################################################
Custom Footer
################################################### -->
<xsl:template name="footer.content">
<xsl:param name="pageclass" select="''"/>
<xsl:param name="sequence" select="''"/>
<xsl:param name="position" select="''"/>
<xsl:param name="gentext-key" select="''"/>
<xsl:variable name="Version">
<xsl:choose>
<xsl:when test="//releaseinfo">
<xsl:value-of select="//releaseinfo"/>
</xsl:when>
<xsl:otherwise>
<!-- nop -->
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:variable name="Title">
<xsl:value-of select="//title"/>
</xsl:variable>
<xsl:choose>
<xsl:when test="$sequence='blank'">
<xsl:choose>
<xsl:when test="$double.sided != 0 and $position = 'left'">
<xsl:value-of select="$Version"/>
</xsl:when>
<xsl:when test="$double.sided = 0 and $position = 'center'">
<!-- nop -->
</xsl:when>
<xsl:otherwise>
<fo:page-number/>
</xsl:otherwise>
</xsl:choose>
</xsl:when>
<xsl:when test="$pageclass='titlepage'">
<!-- nop: other titlepage sequences have no footer -->
</xsl:when>
<xsl:when test="$double.sided != 0 and $sequence = 'even' and $position='left'">
<fo:page-number/>
</xsl:when>
<xsl:when test="$double.sided != 0 and $sequence = 'odd' and $position='right'">
<fo:page-number/>
</xsl:when>
<xsl:when test="$double.sided = 0 and $position='right'">
<fo:page-number/>
</xsl:when>
<xsl:when test="$double.sided != 0 and $sequence = 'odd' and $position='left'">
<xsl:value-of select="$Version"/>
</xsl:when>
<xsl:when test="$double.sided != 0 and $sequence = 'even' and $position='right'">
<xsl:value-of select="$Version"/>
</xsl:when>
<xsl:when test="$double.sided = 0 and $position='left'">
<xsl:value-of select="$Version"/>
</xsl:when>
<xsl:when test="$position='center'">
<xsl:value-of select="$Title"/>
</xsl:when>
<xsl:otherwise>
<!-- nop -->
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<xsl:template match="processing-instruction('hard-pagebreak')">
<fo:block break-before='page'/>
</xsl:template>
<!--###################################################
Extensions
################################################### -->
<!-- These extensions are required for table printing and other stuff -->
<xsl:param name="use.extensions">1</xsl:param>
<xsl:param name="tablecolumns.extension">0</xsl:param>
<xsl:param name="callout.extensions">1</xsl:param>
<xsl:param name="fop.extensions">1</xsl:param>
<!--###################################################
Paper & Page Size
################################################### -->
<!-- Paper type, no headers on blank pages, no double sided printing -->
<xsl:param name="double.sided">0</xsl:param>
<xsl:param name="headers.on.blank.pages">0</xsl:param>
<xsl:param name="footers.on.blank.pages">0</xsl:param>
<!--###################################################
Fonts & Styles
################################################### -->
<xsl:param name="hyphenate">false</xsl:param>
<!-- Default Font size -->
<xsl:param name="body.font.master">11</xsl:param>
<xsl:param name="body.font.small">8</xsl:param>
<!-- Line height in body text -->
<xsl:param name="line-height">1.4</xsl:param>
<!-- Chapter title size -->
<xsl:attribute-set name="chapter.titlepage.recto.style">
<xsl:attribute name="text-align">left</xsl:attribute>
<xsl:attribute name="font-weight">bold</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master * 1.8"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
</xsl:attribute-set>
<!-- Why is the font-size for chapters hardcoded in the XSL FO templates?
Let's remove it, so this sucker can use our attribute-set only... -->
<xsl:template match="title" mode="chapter.titlepage.recto.auto.mode">
<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
xsl:use-attribute-sets="chapter.titlepage.recto.style">
<xsl:call-template name="component.title">
<xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/>
</xsl:call-template>
</fo:block>
</xsl:template>
<!-- Sections 1, 2 and 3 titles have a small bump factor and padding -->
<xsl:attribute-set name="section.title.level1.properties">
<xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master * 1.5"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="section.title.level2.properties">
<xsl:attribute name="space-before.optimum">0.6em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.6em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.6em</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master * 1.25"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="section.title.level3.properties">
<xsl:attribute name="space-before.optimum">0.4em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.4em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.4em</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master * 1.0"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="section.title.level4.properties">
<xsl:attribute name="space-before.optimum">0.3em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.3em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.3em</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master * 0.9"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<!-- Use code syntax highlighting -->
<xsl:param name="highlight.source" select="1"/>
<xsl:param name="highlight.default.language" select="xml" />
<xsl:template match='xslthl:keyword'>
<fo:inline font-weight="bold" color="#7F0055"><xsl:apply-templates/></fo:inline>
</xsl:template>
<xsl:template match='xslthl:comment'>
<fo:inline font-style="italic" color="#3F5F5F"><xsl:apply-templates/></fo:inline>
</xsl:template>
<xsl:template match='xslthl:oneline-comment'>
<fo:inline font-style="italic" color="#3F5F5F"><xsl:apply-templates/></fo:inline>
</xsl:template>
<xsl:template match='xslthl:multiline-comment'>
<fo:inline font-style="italic" color="#3F5FBF"><xsl:apply-templates/></fo:inline>
</xsl:template>
<xsl:template match='xslthl:tag'>
<fo:inline color="#3F7F7F"><xsl:apply-templates/></fo:inline>
</xsl:template>
<xsl:template match='xslthl:attribute'>
<fo:inline color="#7F007F"><xsl:apply-templates/></fo:inline>
</xsl:template>
<xsl:template match='xslthl:value'>
<fo:inline color="#2A00FF"><xsl:apply-templates/></fo:inline>
</xsl:template>
<xsl:template match='xslthl:string'>
<fo:inline color="#2A00FF"><xsl:apply-templates/></fo:inline>
</xsl:template>
<!--###################################################
Tables
################################################### -->
<!-- Some padding inside tables -->
<xsl:attribute-set name="table.cell.padding">
<xsl:attribute name="padding-left">4pt</xsl:attribute>
<xsl:attribute name="padding-right">4pt</xsl:attribute>
<xsl:attribute name="padding-top">4pt</xsl:attribute>
<xsl:attribute name="padding-bottom">4pt</xsl:attribute>
</xsl:attribute-set>
<!-- Only hairlines as frame and cell borders in tables -->
<xsl:param name="table.frame.border.thickness">0.1pt</xsl:param>
<xsl:param name="table.cell.border.thickness">0.1pt</xsl:param>
<!--###################################################
Labels
################################################### -->
<!-- Label Chapters and Sections (numbering) -->
<xsl:param name="chapter.autolabel" select="1"/>
<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.autolabel.max.depth" select="1"/>
<xsl:param name="section.label.includes.component.label" select="1"/>
<xsl:param name="table.footnote.number.format" select="'1'"/>
<!--###################################################
Programlistings
################################################### -->
<!-- Verbatim text formatting (programlistings) -->
<xsl:attribute-set name="monospace.verbatim.properties">
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.small * 1.0"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="verbatim.properties">
<xsl:attribute name="space-before.minimum">1em</xsl:attribute>
<xsl:attribute name="space-before.optimum">1em</xsl:attribute>
<xsl:attribute name="space-before.maximum">1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
<xsl:attribute name="border-color">#444444</xsl:attribute>
<xsl:attribute name="border-style">solid</xsl:attribute>
<xsl:attribute name="border-width">0.1pt</xsl:attribute>
<xsl:attribute name="padding-top">0.5em</xsl:attribute>
<xsl:attribute name="padding-left">0.5em</xsl:attribute>
<xsl:attribute name="padding-right">0.5em</xsl:attribute>
<xsl:attribute name="padding-bottom">0.5em</xsl:attribute>
<xsl:attribute name="margin-left">0.5em</xsl:attribute>
<xsl:attribute name="margin-right">0.5em</xsl:attribute>
</xsl:attribute-set>
<!-- Shade (background) programlistings -->
<xsl:param name="shade.verbatim">1</xsl:param>
<xsl:attribute-set name="shade.verbatim.style">
<xsl:attribute name="background-color">#F0F0F0</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="list.block.spacing">
<xsl:attribute name="space-before.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<xsl:attribute-set name="example.properties">
<xsl:attribute name="space-before.minimum">0.5em</xsl:attribute>
<xsl:attribute name="space-before.optimum">0.5em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.5em</xsl:attribute>
<xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
<xsl:attribute name="keep-together.within-column">always</xsl:attribute>
</xsl:attribute-set>
<!--###################################################
Title information for Figures, Examples etc.
################################################### -->
<xsl:attribute-set name="formal.title.properties" use-attribute-sets="normal.para.spacing">
<xsl:attribute name="font-weight">normal</xsl:attribute>
<xsl:attribute name="font-style">italic</xsl:attribute>
<xsl:attribute name="font-size">
<xsl:value-of select="$body.font.master"/>
<xsl:text>pt</xsl:text>
</xsl:attribute>
<xsl:attribute name="hyphenate">false</xsl:attribute>
<xsl:attribute name="space-before.minimum">0.1em</xsl:attribute>
<xsl:attribute name="space-before.optimum">0.1em</xsl:attribute>
<xsl:attribute name="space-before.maximum">0.1em</xsl:attribute>
</xsl:attribute-set>
<!--###################################################
Callouts
################################################### -->
<!-- don't use images for callouts -->
<xsl:param name="callout.graphics">0</xsl:param>
<xsl:param name="callout.unicode">1</xsl:param>
<!-- Place callout marks at this column in annotated areas -->
<xsl:param name="callout.defaultcolumn">90</xsl:param>
<!--###################################################
Misc
################################################### -->
<!-- Placement of titles -->
<xsl:param name="formal.title.placement">
figure after
example after
equation before
table before
procedure before
</xsl:param>
<!-- Format Variable Lists as Blocks (prevents horizontal overflow) -->
<xsl:param name="variablelist.as.blocks">1</xsl:param>
<xsl:param name="body.start.indent">0pt</xsl:param>
<!-- Show only Sections up to level 3 in the TOCs -->
<xsl:param name="toc.section.depth">3</xsl:param>
<!-- Remove "Chapter" from the Chapter titles... -->
<xsl:param name="local.l10n.xml" select="document('')"/>
<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
<l:l10n language="en">
<l:context name="title-numbered">
<l:template name="chapter" text="%n.&#160;%t"/>
<l:template name="section" text="%n&#160;%t"/>
</l:context>
<l:context name="title">
<l:template name="example" text="Example&#160;%n&#160;%t"/>
</l:context>
</l:l10n>
</l:i18n>
<!--###################################################
colored and hyphenated links
################################################### -->
<xsl:template match="ulink">
<fo:basic-link external-destination="{@url}"
xsl:use-attribute-sets="xref.properties"
text-decoration="underline"
color="blue">
<xsl:choose>
<xsl:when test="count(child::node())=0">
<xsl:value-of select="@url"/>
</xsl:when>
<xsl:otherwise>
<xsl:apply-templates/>
</xsl:otherwise>
</xsl:choose>
</fo:basic-link>
</xsl:template>
<xsl:template match="link">
<fo:basic-link internal-destination="{@linkend}"
xsl:use-attribute-sets="xref.properties"
text-decoration="underline"
color="blue">
<xsl:choose>
<xsl:when test="count(child::node())=0">
<xsl:value-of select="@linkend"/>
</xsl:when>
<xsl:otherwise>
<xsl:apply-templates/>
</xsl:otherwise>
</xsl:choose>
</fo:basic-link>
</xsl:template>
</xsl:stylesheet>

101
spring-integration-reference/styles/pdf/titlepage.xml
View File

@@ -1,101 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE t:templates [
<!ENTITY hsize0 "10pt">
<!ENTITY hsize1 "12pt">
<!ENTITY hsize2 "14.4pt">
<!ENTITY hsize3 "17.28pt">
<!ENTITY hsize4 "20.736pt">
<!ENTITY hsize5 "24.8832pt">
<!ENTITY hsize0space "7.5pt"> <!-- 0.75 * hsize0 -->
<!ENTITY hsize1space "9pt"> <!-- 0.75 * hsize1 -->
<!ENTITY hsize2space "10.8pt"> <!-- 0.75 * hsize2 -->
<!ENTITY hsize3space "12.96pt"> <!-- 0.75 * hsize3 -->
<!ENTITY hsize4space "15.552pt"> <!-- 0.75 * hsize4 -->
<!ENTITY hsize5space "18.6624pt"> <!-- 0.75 * hsize5 -->
]>
<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<t:titlepage t:element="book" t:wrapper="fo:block">
<t:titlepage-content t:side="recto">
<title
t:named-template="division.title"
param:node="ancestor-or-self::book[1]"
text-align="center"
font-size="&hsize5;"
space-before="&hsize5space;"
font-weight="bold"
font-family="{$title.fontset}"/>
<subtitle
text-align="center"
font-size="&hsize4;"
space-before="&hsize4space;"
font-family="{$title.fontset}"/>
<!-- <corpauthor space-before="0.5em"
font-size="&hsize2;"/>
<authorgroup space-before="0.5em"
font-size="&hsize2;"/>
<author space-before="0.5em"
font-size="&hsize2;"/> -->
<mediaobject space-before="2em" space-after="2em"/>
<releaseinfo space-before="5em" font-size="&hsize2;"/>
<copyright space-before="1.5em"
font-weight="normal"
font-size="8"/>
<legalnotice space-before="5em"
font-weight="normal"
font-style="italic"
font-size="8"/>
<othercredit space-before="2em"
font-weight="normal"
font-size="8"/>
<pubdate space-before="0.5em"/>
<revision space-before="0.5em"/>
<revhistory space-before="0.5em"/>
<abstract space-before="0.5em"
text-align="start"
margin-left="0.5in"
margin-right="0.5in"
font-family="{$body.fontset}"/>
</t:titlepage-content>
<t:titlepage-content t:side="verso">
</t:titlepage-content>
<t:titlepage-separator>
</t:titlepage-separator>
<t:titlepage-before t:side="recto">
</t:titlepage-before>
<t:titlepage-before t:side="verso">
</t:titlepage-before>
</t:titlepage>
<!-- ==================================================================== -->
</t:templates>