+ Connection Factory Attributes
+
+
+
+
+
+
+
+
+
+ Attribute Name
+ Client?
+ Server?
+ Allowed Values
+ Attribute Description
+
+
+
+
+ type
+ Y
+ Y
+ client, server
+ Determines whether the connection factory is a client or server.
+
+
+ host
+ Y
+ N
+
+ The host name or ip address of the destination.
+
+
+ port
+ Y
+ Y
+
+ The port.
+
+
+ serializer
+ Y
+ Y
+
+ An implementation of Serializer used to serialize
+ the payload. Defaults to ByteArrayCrLfSerializer
+
+
+ deserializer
+ Y
+ Y
+
+ An implementation of Deserializer used to deserialize
+ the payload. Defaults to ByteArrayCrLfSerializer
+
+
+ using-nio
+ Y
+ Y
+ true, false
+ Whether or not the tcp adapter is using NIO. Refer to the java.nio
+ package for more information. Default false.
+
+
+ using-direct-buffers
+ Y
+ N
+ true, false
+ When using NIO, whether or not the tcp adapter uses direct buffers.
+ Refer to java.nio.ByteBuffer documentation for
+ more information. Must be false if using-nio is false.
+
+
+ so-timeout
+ Y
+ Y
+
+ See java.net.Socket
+ setSoTimeout() methods for more information.
+
+
+ so-send-buffer-size
+ Y
+ Y
+
+ See java.net.Socket
+ setSendBufferSize() methods for more information.
+
+
+ so-receive-buffer- size
+ Y
+ Y
+
+ See java.net.Socket
+ setReceiveBufferSize() methods for more information.
+
+
+ so-keep-alive
+ Y
+ Y
+ true, false
+ See java.net.Socket. setKeepAlive().
+
+
+ so-linger
+ Y
+ Y
+
+ Sets linger to true with supplied value.
+ See java.net.Socket. setSoLinger().
+
+
+ so-tcp-no-delay
+ Y
+ Y
+ true, false
+ See java.net.Socket. setTcpNoDelay().
+
+
+ so-traffic-class
+ Y
+ Y
+
+ See java.net.Socket. setTrafficClass().
+
+
+ local-address
+ N
+ Y
+
+ On a multi-homed system, specifies an IP address
+ for the interface to which the socket will be bound.
+
+
+
+ task-executor
+ Y
+ Y
+
+
+ Specifies a specific Executor to be used for socket handling. If not supplied, an internal
+ pooled executor will be used. Needed on some platforms that require the use of specific
+ task executors such as a WorkManagerTaskExecutor. See pool-size for thread
+ requirements, depending on other options.
+
+
+ single-use
+ Y
+ Y
+ true, false
+ Specifies whether a connection can be used for multiple messages.
+ If true, a new connection will be used for each message.
+
+
+ pool-size
+ Y
+ Y
+
+ Specifies the concurrency. 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.
+ It only applies in this sense if task-executor is not configured.
+ However, pool-size is also used for the server socket backlog,
+ regardless of whether an external task executor is used. Defaults to 5.
+
+
+ interceptor-factory-chain
+ Y
+ Y
+
+ Documentation to be supplied.
+
+
+
+
+
+ UDP Outbound Channel Adapter Attributes
+
+
+
+
+
+
+
+ Attribute Name
+ Allowed Values
+ Attribute Description
+
+
+
+
+ host
+
+ The host name or ip address of the destination. For multicast udp
+ adapters, the multicast address.
+
+
+ port
+
+ The port on the destination.
+
+
+ multicast
+ true, false
+ Whether or not the udp adapter uses multicast.
+
+
+ acknowledge
+ true, false
+ Whether or not a udp adapter requires an acknowledgment from the destination.
+ when enabled, requires setting the following 4 attributes.
+
+
+ ack-host
+
+ 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.
+
+
+ ack-port
+
+ When acknowledge is true, indicates the port to which the
+ acknowledgment should be sent. The adapter listens on this port for
+ acknowledgments.
+
+
+ ack-timeout
+
+ 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.
+
+
+ min-acks-for- success
+
+ Defaults to 1. For multicast adapters, you can set this to a larger
+ value, requiring acknowlegments from multiple destinations.
+
+
+ check-length
+ true, false
+ Whether or not a udp adapter includes a data length field in the
+ packet sent to the destination.
+
+
+ time-to-live
+
+ For multicast adapters, specifies the time to live attribute for
+ the MulticastSocket; controls the scope
+ of the multicasts. Refer to the Java API
+ documentation for more information.
+
+
+ so-timeout
+
+ See java.net.DatagramSocket
+ setSoTimeout() methods for more information.
+
+
+ so-send-buffer-size
+
+ See java.net.DatagramSocket
+ setSendBufferSize() methods for more information.
+
+
+ so-receive-buffer- size
+
+ Used for udp acknowlegment packets. See java.net.DatagramSocket
+ setReceiveBufferSize() methods for more information.
+
+
+ local-address
+
+ On a multi-homed system, for the UDP adapter, specifies an IP address
+ for the interface to which the socket will be bound for reply messages.
+ For a multicast adapter it is also used to determine which interface
+ the multicast packets will be sent over.
+
+
+ task-executor
+
+
+ Specifies a specific Executor to be used for acknowledgment handling. If not supplied, an internal
+ single threaded executor will be used. Needed on some platforms that require the use of specific
+ task executors such as a WorkManagerTaskExecutor. One thread will be dedicated to handling
+ acknowledgments (if the acknowledge option is true).
+
+
+
+
+
+ UDP Inbound Channel Adapter Attributes
+
+
+
+
+
+
+
+ Attribute Name
+ Allowed Values
+ Attribute Description
+
+
+
+
+ port
+
+ The port on which the adapter listens.
+
+
+ multicast
+ true, false
+ Whether or not the udp adapter uses multicast.
+
+
+ multicast-address
+
+ When multicast is true, the multicast address to which the adapter
+ joins.
+
+
+ pool-size
+
+ Specifies the concurrency. Specifies how many packets can
+ be handled concurrently.
+ It only applies if task-executor is not configured.
+ Defaults to 5.
+
+
+ task-executor
+
+
+ Specifies a specific Executor to be used for socket handling. If not supplied, an internal
+ pooled executor will be used. Needed on some platforms that require the use of specific
+ task executors such as a WorkManagerTaskExecutor. See pool-size for thread
+ requirements.
+
+
+ receive-buffer-size
+
+ 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..
+
+
+ check-length
+ true, false
+ Whether or not a udp adapter expects a data length field in the
+ packet received. Used to detect packet truncation.
+
+
+ so-timeout
+
+ See java.net.DatagramSocket
+ setSoTimeout() methods for more information.
+
+
+ so-send-buffer-size
+
+ Used for udp acknowlegment packets. See java.net.DatagramSocket
+ setSendBufferSize() methods for more information.
+
+
+ so-receive-buffer- size
+
+ See java.net.DatagramSocket
+ setReceiveBufferSize() for more information.
+
+
+ local-address
+
+ On a multi-homed system, specifies an IP address
+ for the interface to which the socket will be bound.
+
+
+
+
+
+ TCP Inbound Gateway Attributes
+
+
+
+
+
+
+
+ Attribute Name
+ Allowed Values
+ Attribute Description
+
+
+
+
+ port
+
+ The port on which the gateway listens.
+
+
+
+
+
+ TCP Outbound Gateway Attributes
+
+
+
+
+
+
+
+ Attribute Name
+ Allowed Values
+ Attribute Description
+
+
+
+
+ host
+
+ The host name or ip address of the destination.
+
+
+
+
+
+
+
diff --git a/docs/src/reference/docbook/jdbc.xml b/docs/src/reference/docbook/jdbc.xml
new file mode 100644
index 0000000000..1a1b498625
--- /dev/null
+++ b/docs/src/reference/docbook/jdbc.xml
@@ -0,0 +1,224 @@
+
+
+ JDBC Support
+
+ Spring Integration provides Channel Adapters for receiving and sending
+ messages via database queries.
+
+
+ Inbound Channel Adapter
+
+ The main function of an inbound Channel Adapter is to execute a SQL
+ SELECT query and turn the result set into a message. The
+ message payload is the whole result set, expressed as a
+ List, and the types of the items in the list
+ depends on the row-mapping strategy that is used. The default strategy is
+ a generic mapper that just returns a Map for each
+ row i nthe query. Optionally this can be changed by adding a reference to
+ requires a reference to a RowMapper instance (see
+ the Spring
+ JDBC documentation for more detailed information about row
+ mapping).
+ If you want to convert rows in the SELECT query result to
+ individual messages you can use a downstream splitter.
+
+
+ The inbound adapter also requires a reference to either
+ JdbcTemplate instance or
+ DataSource.
+
+ As well as the SELECT statement to generate the
+ messages, the adapter above also has an UPDATE statement that
+ is being used to mark the records as processed, so they don't show up in
+ the next poll. The update can be parameterised by the list of ids from the
+ original select. This is done through a naming convention by default (a
+ column in the input result set called "id" is translated into a list in
+ the parameter map for the update called "id"). The following example
+ defines an inbound Channel Adapter with an update query and a
+ DataSource reference. <jdbc:inbound-channel-adapter query="select * from item where status=2"
+ channel="target" data-source="dataSource"
+ update="update item set status=10 where id in (:id)" />
+
+ The parameters in the update query are specified with a colon (:) prefix to the name of a parameter (which in this case is an expression to be applied to each of the rows in the polled result set). This is a standard feature of the named parameter JDBC support in Spring JDBC combined with a convention (projection onto the polled result list) adopted in Spring Integration. The underlying Spring JDBC features limit the available expressions (e.g. most special characters other than period are disallowed), but since the target is usually a list of or an individual object addressable by simple bean paths this isn't unduly restrictive.
+ To change the parameter generation strategy you can inject a
+ SqlParameterSourceFactory into the adapter to
+ override the default behaviour (the adapter has a
+ sql-parameter-source-factory attribute).
+
+
+ Polling and Transactions
+
+ The inbound adapter accepts a regular Spring Integration poller as
+ a sub element, so for instance the frequency of the polling can be
+ controlled. A very important feature of the poller for JDBC usage is the
+ option to wrap the poll operation in a transaction, for example:
+
+ <jdbc:inbound-channel-adapter query="..."
+ channel="target" data-source="dataSource"
+ update="...">
+ <poller fixed-rate"1000">
+ <transactional/>
+ </poller>
+</jdbc:inbound-channel-adapter>
+
+
+ If a poller is not explicitly specified a default value will be used (and as per normal with Spring Integration can be defined as a top level bean)
+ In this example the database is polled every 1000
+ milliseconds, and the update and select queries are both executed in the
+ same transaction. The transaction manager configuration is not shown,
+ but as long as it is aware of the data source then the poll is
+ transactional. A common use case is for the downstream channels to be
+ direct channels (the default), so that the endpoints are invoked in the
+ same thread, and hence the same transaction. then if any of them fails,
+ the transaction rolls back and the input data are reverted to their
+ original state.
+
+
+
+
+ Outbound Channel Adapter
+
+ The outbound Channel Adapter is the inverse of the inbound: its role
+ is to handle a message and use it to execute a SQL query. The message
+ payload and headers are available by default as input parameters to the
+ query, for instance: <jdbc:outbound-channel-adapter
+ query="insert into foos (id, status, name) values (:headers[$id], 0, :payload[foo])"
+ channel="input" data-source="dataSource"/> In the
+ example above, messages arriving on the channel "input" have a payload of
+ a map with key "foo", so the [] operator dereferences that
+ value from the map. The headers are also accessed as a map.
+ The parameters in the query above are bean property expressions on the incoming message (not Spring EL expressions). This behaviour is part of the
+
+ SqlParameterSource
+
+ which is the default source created by the outbound adapter. Other behaviour is possible in the adapter, and requires the user to inject a different
+
+ SqlParameterSourceFactory
+
+ .
+
+
+ The outbound adapter requires a reference to either a DataSource or
+ a JdbcTemplate. It can also have a
+ SqlParameterSourceFactory injected to control the
+ binding of incoming message to the query.
+
+ If the input channel is a direct channel then the outbound adapter
+ runs its query in the same thread, and therefor ethe same transaction (if
+ there is one) as the sender of the message.
+
+
+
+ Outbound Gateway
+
+ The outbound Gateway is like a combination of the outbound and
+ inbound adapters: its role is to handle a message and use it to execute a
+ SQL query and then respond with the result sending it to a reply channel.
+ The message payload and headers are available by default as input
+ parameters to the query, for instance: <jdbc:outbound-gateway
+ update="insert into foos (id, status, name) values (:headers[$id], 0, :payload[foo])"
+ request-channel="input" reply-channel="output" data-source="dataSource" />
+
+ The result of the above would be to insert a record into the "foos"
+ table and return a message to the output channel indicating the number of
+ rows affected (the payload is a map {UPDATED=1}.
+
+ If the update query is an insert with auto-generated keys, the reply
+ message can be populated with the generated keys by adding
+ keys-generated="true" to the above example (this is not
+ the default because it is not supported by some database platforms). For
+ example:
+
+ <jdbc:outbound-gateway
+ update="insert into foos (status, name) values (0, :payload[foo])"
+ request-channel="input" reply-channel="output" data-source="dataSource"
+ keys-generated="true"/>
+
+ Instead of the update count or the generated keys, you can also
+ provide a select query to execute and generate a reply message that way
+ (like the inbound adapter), e.g:
+
+ <jdbc:outbound-gateway
+ update="insert into foos (id, status, name) values (:headers[$id], 0, :payload[foo])"
+ query="select * from foos where id=:headers[$id]"
+ request-channel="input" reply-channel="output" data-source="dataSource" />
+
+ Like with the adapters there is also the option to provide
+ SqlParameterSourceFactory instances for request and
+ reply. The default is the same as for the outbound adapter, so the request
+ message is available as the root of an expression. If
+ keys-generated="true" then the root of the expression is the generated
+ keys (a map if there is only one or a list of maps if
+ multi-valued).
+
+ The outbound gateway requires a reference to either a DataSource or
+ a JdbcTemplate. It can also have a
+ SqlParameterSourceFactory injected to control the
+ binding of incoming message to the query.
+
+
+
+ Message Store
+
+ The JDBC module provides an implementation of the Spring Integration
+ MessageStore (important in the Claim Check pattern)
+ and MessageGroupStore (important in stateful
+ patterns like Aggregator) backed by a database. Both interfaces are
+ implemented by the JdbcMessageStore and there is also support for
+ configuring store instances in XML. For example:
+
+ <jdbc:message-store id="messageStore" data-source="dataSource"/>
+
+ A JdbcTemplate can be specified instead of a
+ DataSource.
+
+ Other optional attributes are show in the next example:
+
+ <jdbc:message-store id="messageStore" data-source="dataSource"
+ lob-handler="lobHandler" table-prefix="MY_INT_"/>Here we
+ have specified a LobHandler for dealing with
+ messages as large objects (e.g. often necessary if using Oracle) and a
+ prefix for the table names in the queries generated by the store. The
+ table name prefix defaults to "INT_".
+
+
+ Initializing the Database
+
+ Spring Integration ships with some sample scripts that can be used
+ to initialize a database. In the spring-integration-jdbc JAR file you
+ will find scripts in the
+ org.springframework.integration.jdbc package:
+ there is a create and a drop script example for a range of common
+ database platforms. A common way to use these scripts is to reference
+ them in a Spring
+ JDBC data source initializer. Note that the scripts are provided
+ as samples or specifications of the the required table and column names.
+ You may find that you need to enhance them for production use (e.g. with
+ index declarations).
+
+
+
+ Partitioning a Message Store
+
+ It is common to use a JdbcMessageStore as a
+ global store for a group of applications, or nodes in the same
+ application. To provide some portection against name clashes, and to
+ give control over the database meta-data configuration, the message
+ store allows the tables to be partitioned in two ways. One is to use
+ separate table names, by changing the prefix as described above, and the
+ other is to specify a "region" name for partitioning data within a
+ single table. An important use case for this is using the store to
+ manage persistent queues backing a Spring Integration channel. The
+ message data for a persistent channel is keyed in the store on the
+ channel name, so if the channel names are not globally unique then there
+ is the danger of channels picking up data that was not intended for
+ them. To avoid this the message store region can be used to keep data
+ separate for different physical channels that happen to have the same
+ logical name.
+
+
+
diff --git a/docs/src/reference/docbook/jms.xml b/docs/src/reference/docbook/jms.xml
new file mode 100644
index 0000000000..98f875935b
--- /dev/null
+++ b/docs/src/reference/docbook/jms.xml
@@ -0,0 +1,311 @@
+
+
+ JMS Support
+
+ 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 JmsTemplate 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 JmsTemplate to convert and send a JMS Message on
+ demand.
+
+
+ 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.
+
+
+
+ Inbound Channel Adapter
+
+ The inbound Channel Adapter requires a reference to either a single JmsTemplate
+ instance or both ConnectionFactory and Destination
+ (a 'destinationName' can be provided in place of the 'destination' reference). The following example defines an
+ inbound Channel Adapter with a Destination reference.
+
+
+ ]]>
+
+ 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 message-driven-channel-adapter described below is a better option.
+
+
+ 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.
+
+
+
+ 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.
+
+
+ ]]>
+
+
+
+
+ Message-Driven Channel Adapter
+
+ The "message-driven-channel-adapter" requires a reference to either an instance of a Spring MessageListener
+ container (any subclass of AbstractMessageListenerContainer) or both
+ ConnectionFactory and Destination
+ (a 'destinationName' can be provided in place of the 'destination' reference). The following example defines a
+ message-driven Channel Adapter with a Destination reference.
+ ]]>
+
+ 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-2.0.xsd) for more detail.
+
+
+
+ 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 MessageChannel as soon as they are received from the underlying
+ JMS consumer.
+
+
+
+
+ Outbound Channel Adapter
+
+ The JmsSendingMessageHandler implements the MessageHandler
+ interface and is capable of converting Spring Integration Messages 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".
+ ]]>
+
+
+ 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
+ itself 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'.
+
+ 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 to Spring Integration MessageHeaders).
+
+
+
+
+
+ Inbound Gateway
+
+ Spring Integration's message-driven JMS inbound-gateway delegates to a
+ MessageListener container, supports dynamically adjusting concurrent consumers,
+ and can also handle replies. The inbound gateway requires references to a
+ ConnectionFactory, and a request Destination (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".
+ ]]>
+
+
+ Since the gateways provide request/reply behavior instead of unidirectional send or
+ 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'.
+
+
+ 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 payload will be converted into a JMS Message (e.g. String payload
+ becomes a JMS TextMessage).
+
+
+ As with anything else, Gateway invocation might result in error.
+ By default Producer will not be notified of the errors thta might have occurredon ythe consumer side and will time out waiting for
+ the reply. However there might be times when you to communicate error condition back to the consumer,
+ in other words treat the Exception as a valid reply valid reply by mapping it to a Message. To accomplish this
+ JMS Inbound Gateway provides support for Exception mappers via exception-mapper
+ attribute.
+
+
+
+
+
+
+ ]]>
+
+ foo.bar.SampleExceptionMapper is the implementation of
+ org.springframework.integration.message.InboundMessageMapper which only defines one method toMessage(Object object).
+{
+ public Message toMessage(Throwable object) throws Exception {
+ MessageHandlingException ex = (MessageHandlingException) object;
+ return MessageBuilder.withPayload("Error happened in message: " +
+ ex.getFailedMessage().getPayload()).build();
+ }
+
+}
+ ]]>
+
+
+
+
+ Outbound Gateway
+
+ 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.
+ ]]>
+
+
+ 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
+ sent as a request, and the 'extract-reply-payload' property value applies to the
+ JMS Message that is received as a reply and then converted into a Spring Integration
+ Message to be subsequently sent to the 'reply-channel' as shown in the example configuration above.
+
+
+
+ Message Conversion, Marshalling and Unmarshalling
+
+ If you need to convert the message, all JMS adapters and gateways, allow you to
+ provide a MessageConverter via message-converter attribute. Simply provide the
+ bean name of an instance of MessageConverter that is available within the same
+ ApplicationContext.
+ Also, to provide some consistency with Marshaller and Unmarshaller interfaces Spring provides MarshallingMessageConverter
+ which you can configure with your own custom Marshallers and Unmarshallers
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+
+ 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.
+
+
+
+
+
+ JMS Backed Message Channels
+
+ 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.
+
+
+ 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.
+ ]]>
+
+
+ The channel in the above example will behave much like a normal <channel/> 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 <queue/> sub-element within a
+ non-JMS <channel/> 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 store and forward 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 <channel/>
+ element that has no <queue/> sub-element.
+
+
+ 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.
+ ]]>
+
+
+ For either type of JMS-backed channel, the name of the destination may be provided instead of a reference.
+
+
+ ]]>
+
+
+ In the examples above, the Destination names would be resolved by Spring's default
+ DynamicDestinationResolver implementation, but any implementation of the
+ DestinationResolver interface could be provided. Also, the JMS
+ ConnectionFactory 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.
+ ]]>
+
+
+
+
+ JMS Samples
+
+ 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.
+
+
+
+
diff --git a/docs/src/reference/docbook/jmx.xml b/docs/src/reference/docbook/jmx.xml
new file mode 100644
index 0000000000..d9802cd296
--- /dev/null
+++ b/docs/src/reference/docbook/jmx.xml
@@ -0,0 +1,190 @@
+
+
+ JMX Support
+
+ 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.
+
+
+ Notification Listening Channel Adapter
+
+ 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:
+ <jmx:notification-listening-channel-adapter id="adapter"
+ channel="channel"
+ object-name="example.domain:name=publisher"/>
+
+ 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 <context:mbean-server/> element. If you need to use a different name be sure to include the "mbean-server" attribute.
+ 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: <jmx:notification-listening-channel-adapter id="adapter"
+ channel="channel"
+ mbean-server="someServer"
+ object-name="example.domain:name=somePublisher"
+ notification-fliter="notificationFilter"
+ handback="myHandback"/>
+ Since the notification-listening adapter is registered with
+ the MBeanServer directly, it is event-driven and does not require any
+ poller configuration.
+
+
+
+ Notification Publishing Channel Adapter
+
+ The Notification-publishing Channel Adapter is relatively simple. It
+ only requires a JMX ObjectName in its configuration as shown below.
+ <context:mbean:export/>
+
+ <jmx:notification-publishing-channel-adapter id="adapter"
+ channel="channel"
+ object-name="example.domain:name=publisher"/>
+ It does also require that an MBeanExporter be present in the
+ context. That is why the <context:mbean-export/> element is shown
+ above as well.
+
+ 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.
+
+ 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. <context:mbean:export/>
+
+ <jmx:notification-publishing-channel-adapter id="adapter"
+ channel="channel"
+ object-name="example.domain:name=publisher"
+ default-notification-type="some.default.type"/>
+
+
+
+
+ Attribute Polling Channel Adapter
+
+ 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. <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" fixed-rate="5000"/>
+ </jmx:attribute-polling-channel-adapter>
+
+
+
+
+ Operation Invoking Channel Adapter
+
+ 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. Both of these must be explicitly provided
+ via adapter configuration: <jmx:operation-invoking-channel-adapter id="adapter"
+ object-name="example.domain:name=TestBean"
+ operation-name="ping"/>
+ Then the 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.
+
+ 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.
+
+ 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.
+
+
+
+ Operation Invoking outbound Gateway
+
+ Similar to operation-invoking-channel-adapter
+ Spring Integration also provides
+ operation-invoking-outbound-gateway which could be
+ used when dealing with non-void operations and return value is required.
+ Such return value will be sent as message payload to the 'reply-channel'
+ specified by this Gateway. <jmx:operation-invoking-outbound-gateway request-channel="requestChannel"
+ reply-channel="replyChannel"
+ object-name="org.springframework.integration.jmx.config:type=TestBean,name=testBeanGateway"
+ operation-name="testWithReturn"/> Another way of
+ provideing the 'reply-channel' is by setting
+ MessageHeaders.REPLY_CHANNEL Message
+ Header
+
+
+
+ MBean Exporter
+
+ Spring Integration components themselves may be exposed as MBeans
+ when the IntegrationMBeanExporter is configured. To
+ create an instance of the IntegrationMBeanExporter,
+ define a bean and provide a reference to an MBeanServer and a domain name
+ (if desired). The domain can be left out in which case the default domain
+ is "spring.application". <jmx:mbean-exporter domain="my.company.domain" mbean-server="mbeanServer"/>
+
+ <bean id="mbeanServer" class="org.springframework.jmx.support.MBeanServerFactoryBean">
+ <property name="locateExistingServerIfPossible" value="true"/>
+ </bean>
+
+ The MBean exporter is orthogonal to the one provided in Spring core
+ - it registers message channels and message handlers, but not itself (you
+ can expose the exporter itself using the standard
+ <context:mbean-export/> tag).
+
+
+
+ Control Bus
+
+ As described in (EIP), 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. <jmx:control-bus mbean-exporter="mbeanExporter" operation-channel="operationChannel"/>
+
+ <jmx:mbean-exporter id="mbeanExporter" mbean-server="mbeanServer"/>
+
+
+ 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.
+
+ 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.
+
+
diff --git a/docs/src/reference/docbook/mail.xml b/docs/src/reference/docbook/mail.xml
new file mode 100644
index 0000000000..842224a0eb
--- /dev/null
+++ b/docs/src/reference/docbook/mail.xml
@@ -0,0 +1,161 @@
+
+
+ Mail Support
+
+
+ Mail-Sending Channel Adapter
+
+ Spring Integration provides support for outbound email with the
+ MailSendingMessageHandler. It delegates to a configured instance of Spring's
+ JavaMailSender:
+ JavaMailSender mailSender = (JavaMailSender) context.getBean("mailSender");
+
+ MailSendingMessageHandler mailSendingHandler = new MailSendingMessageHandler(mailSender);
+ MailSendingMessageHandler has various mapping strategies that use Spring's
+ MailMessage abstraction. If the received Message's payload is already
+ a MailMessage 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 ObjectToStringTransformer prior to the outbound
+ Mail adapter (see the example within for more detail).
+
+
+ The outbound MailMessage may also be configured with certain values from the
+ MessageHeaders. 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:
+ MailHeaders.SUBJECT
+ MailHeaders.TO
+ MailHeaders.CC
+ MailHeaders.BCC
+ MailHeaders.FROM
+ MailHeaders.REPLY_TO
+
+
+ MailHeaders also allows you to override corresponding MailMessage values.
+ For example: If MailMessage.to is set to 'foo@bar.com' and MailHeaders.TO
+ Message header is provided it will take precedence and override the corresponding value in MailMessage
+
+
+
+
+ Mail-Receiving Channel Adapter
+
+ Spring Integration also provides support for inbound email with the
+ MailReceivingMessageSource. It delegates to a configured instance of Spring
+ Integration's own MailReceiver interface, and there are two implementations:
+ Pop3MailReceiver and ImapMailReceiver. The easiest way to
+ instantiate either of these is by passing the 'uri' for a Mail store to the receiver's constructor. For example:
+
+
+
+ Another option for receiving mail is the IMAP "idle" command (if supported by the mail server you are using).
+ Spring Integration provides the ImapIdleChannelAdapter which is itself a Message-producing
+ endpoint. It delegates to an instance of the ImapMailReceiver 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.
+
+
+
+
+ Mail Namespace Support
+
+ Spring Integration provides a namespace for mail-related configuration. To use it, configure the following schema
+ locations.
+]]>
+
+
+ To configure an outbound Channel Adapter, provide the channel to receive from, and the MailSender:
+ ]]>
+ Alternatively, provide the host, username, and password:
+ ]]>
+
+ Keep in mind, as with any outbound Channel Adapter, if the referenced channel is a PollableChannel, a
+ <poller> sub-element should be provided with either an interval-trigger or cron-trigger.
+
+
+
+ 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":
+
+
+]]>
+ 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:
+ ]]>
+ ... where javaMailProperties could be provided by creating and populating
+ a regular java.utils.Properties object. For example via util namespace
+ provided by Spring.
+
+ javax.net.ssl.SSLSocketFactory
+ false
+ imaps
+ false
+]]>
+
+
+
+ In both configurations channel and should-delete-messages are the REQUIRED
+ attributes. The important thing to understand is why should-delete-messages is required?
+ The issue is with POP3 protocol, which does NOT have any knowlege of messages that were READ. It can only know what's been read
+ within a single session. This means that when your POP3 mail adapter is running emails are successfully consumed as as they become available during each poll
+ and no single email message will be delivered more then once. However, as soon as you restart your adapter and begin a new session
+ all the email messages that might have been retreeved in the previous session will be retrieved again. That is the nature of POP3. Some might argue
+ that why not set should-delete-messages to TRUE by default? Becouse there are two valid amd mutually exclusive use cases
+ which makes it very hard pick the right default. You may want to configure your adapter as the only email receiever in which
+ case you want to be able to restart such adapter without fear that messages that were delivered before will not be redelivered again.
+ In this case setting should-delete-messages to TRUE would make most sence. However, you may have anoher use case where
+ you may want to have multiple adapters that simply monitor email servers and their content. In other words you just want to 'peek but not touch'.
+ Then setting should-delete-messages to FALSE would be much more appropriate. So since it is hard to choose what should be
+ the right default value for should-delete-messages attribute we simply made it required to be set - leaving it up to you
+ while also not letting you to forget that you must set it.
+
+
+ When configuring a polling adapter (e.g., inbound-channel-adapter) should-mark-messages-as-read
+ be aware of the protocol you are configuring to retrieve messages. For example POP3 does not support this flag
+ which means setting it to either value will have no effect as messages will NOT be marked as read
+
+
+
+ When using the namespace support, a header-enricher 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.
+ ]]>
+
+
+
+
diff --git a/docs/src/reference/docbook/message-history.xml b/docs/src/reference/docbook/message-history.xml
new file mode 100644
index 0000000000..63857a403f
--- /dev/null
+++ b/docs/src/reference/docbook/message-history.xml
@@ -0,0 +1,64 @@
+
+
+ Message History
+
+ The key benefit of messaging architecture is loose coupling where participating components do not maintain any awareness about one another. This fact
+ alone makes you architecture extremely flexible allowing you to change components without affecting the rest of the flow, change messaging routs,
+ message consuming styles (polling vs event driven) etc...
+ However, this unassuming style of architecture could prove to be problematic when things go wrong. For example, if something happened
+ you would probably like to get as much information about the message as you can (its origin, where it was etc.)
+
+
+ Message History is one of those patterns that could help by giving you an option to maintain some level of awareness of a
+ message path either for debugging purposes or to maintain an audit trail.
+ Spring integration provides a simple way to configure your message flows to maintain Message History by adding Message History header to a
+ Message every time a message goes through a tracked component.
+
+
+ Message History Configuration
+
+ To enable Message History all you need is define message-history element in your configuration.
+ ]]>
+
+
+ Now every named component (component that has an 'id' defined) will be tracked.
+ The framework will set the '$history' header in your Message who's value is very simple - List<Properties>.
+ The need for this simple structure is mandated by the loosely coupled architecture of messaging systems where the framework
+ must not require you to share any dependencies outside of Java itself.
+
+
+
+
+
+
+
+
+]]>
+The above configuration will produce a very simple Message History structure:
+
+ To get access to Message History all you need is access the MessageHistory header. For example:
+ historyIterator =
+ message.getHeaders().get(MessageHistory.HEADER_NAME, MessageHistory.class).iterator();
+assertTrue(historyIterator.hasNext());
+Properties gatewayHistory = historyIterator.next();
+assertEquals("sampleGateway", gatewayHistory.get("name"));
+assertTrue(historyIterator.hasNext());
+Properties chainHistory = historyIterator.next();
+assertEquals("sampleChain", chainHistory.get("name"));]]>
+
+
+ Some times you might not want to track all of the components. To accomplish this all you need is provide tracked-components attribute where you can specify
+ comma delimited list of component names and/or patterns you want to track.
+ ]]>
+ In the above example, Message History will only be maintained for all of the components that end with 'Gateway', all components that start with 'sample' and 'foo' component.
+
+
+ Remember, that by definition History is immutable (you can't re-write history,although some try), therefore Message History can not
+ be changed once written. Every attempt will end in exception.
+
+
+
diff --git a/docs/src/reference/docbook/message-publishing.xml b/docs/src/reference/docbook/message-publishing.xml
new file mode 100644
index 0000000000..f599808dfc
--- /dev/null
+++ b/docs/src/reference/docbook/message-publishing.xml
@@ -0,0 +1,371 @@
+
+
+ Message Publishing
+
+ The AOP Message Publishing feature allows you to construct and send a message as a by-product of method invocation. For example, imagine you
+ have a component and every time the state of this component changes you would like to be notified via a Message. The easiest
+ way to send such notifications 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 how should the notification Message be structured?
+ The AOP Message Publishing feature handles these responsibilities with a configuration-driven approach.
+
+
+ Message Publishing Configuration
+
+ Spring Integration provides two approaches: XML and Annotation-driven.
+
+
+ Annotation-driven approach via @Publisher annotation
+
+ The annotation-driven approach allows you to annotate any method with the @Publisher annotation, specifying 'channel' attribute.
+ The Message will be constructed from the return value of method invocation and sent to a channel specified by 'channel' attribute.
+ To further manage message structure you can also use a combination of both @Payload and @Header annotations.
+
+
+ Internally message publishing feature of Spring Integration uses both Spring AOP by defining PublisherAnnotationAdvisor and
+ Spring 3.0 Expression Language (SpEL) support, giving you considerable flexibility and control over the structure of the Message it will build.
+
+
+ PublisherAnnotationAdvisor defines and binds the following variables:
+
+
+ #return - will bind to a return value allowing you to reference it or its
+ attributes (e.g., #return.foo where 'foo' is an attribute of the object bound to
+ #return)
+
+
+ #exception - will bind to an exception if one is thrown by the method invocation.
+
+
+ #args - will bind to method arguments, so individual arguments could be extracted by name
+ (e.g., #args.fname as in the above method)
+
+
+
+
+
+ Let's look at couple of examples:
+
+
+@Publisher
+public String defaultPayload(String fname, String lname) {
+ return fname + " " + lname;
+}
+
+
+ In the above example the Message will be constructed with the following structure:
+
+
+ Message payload - will be the return type and value of the method. This is the default.
+
+
+ A newly constructed message will be sent to a default publisher channel configured with annotation post processor (see the end of this section).
+
+
+
+
+@Publisher(channel="testChannel")
+public String defaultPayload(String fname, @Header("last") String lname) {
+ return fname + " " + lname;
+}
+
+
+ In this example everything is the same as above, however we are not using default publishing channel. Instead we are specifying
+ the publishing channel via 'channel' attribute of @Publisher annotation.
+ We are also adding @Header annotation which results in the Message header with the name 'last' and the value of 'lname' input parameter
+ to be added to the newly constructed Message.
+
+
+
+@Publisher(channel="testChannel")
+@Payload
+public String defaultPayloadButExplicitAnnotation(String fname, @Header String lname) {
+ return fname + " " + lname;
+}
+
+
+ The above example is almost identical to the previous one. The only difference here is that we are using @Payload annotation
+ on the method, thus explicitly specifying that the return value of the method should be used as a payload of the Message.
+
+
+
+@Publisher(channel="testChannel")
+@Payload("#return + #args.lname")
+public String setName(String fname, String lname, @Header("x") int num) {
+ return fname + " " + lname;
+}
+
+
+ Here we are expending on the previous configuration by using Spring Expression language in the @Payload annotation further instructing
+ the framework on how the message should be constructed. In this particular case the message will be a concatenation of the return value of the method invocation and
+ 'lname' input argument. Message header 'x' with value of 'num' input argument will be added to the newly constructed Message.
+
+
+
+@Publisher(channel="testChannel")
+public String argumentAsPayload(@Payload String fname, @Header String lname) {
+ return fname + " " + lname;
+}
+
+
+ In the above example you see another usage of @Payload annotation. Here we are annotating method argument
+ which will become a payload of newly constructed message.
+
+
+
+
+ As with most other annotation-driven features in Spring, you will need to register a post-processor
+ (PublisherAnnotationBeanPostProcessor).
+ <bean class="org.springframework.integration.aop.PublisherAnnotationBeanPostProcessor"/>
+ You can also use namespace support for added convenience:
+
+<si:annotation-config default-publisher-channel="defaultChannel"/>
+
+
+
+ Similar to other Spring annotations (e.g., @Controller), @Publisher is a meta-annotation, which means you can define your own annotations
+ that will be treated as @Publisher
+
+Here we defined @Audit annotation which itself is a @Publisher. Also note that you can define channel
+attribute on the meta-annotation thus encapsulating the behavior of where messages will be sent inside of this annotation.
+
+Now you can annotate any method:
+
+
+In the above example every invocation of test() method will result in Message with payload which is the return value of the method
+invocation to be sent to auditChannel
+
+You can also annotate the class which would mean that the properties of this annotation will be applied on every public method of this class
+
+
+
+
+
+
+
+ XML-based approach via <publishing-interceptor> element
+
+ The XML-based approach allows you to configure the same AOP-based Message Publishing functionality with
+ simple namespace-based configuration of a MessagePublishingInterceptor.
+ It certainly has some benefits over the annotation-driven 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 the source code.
+
+
+ To configure Message Publishing via XML, you only need to do the following two things:
+
+
+ Provide configuration for MessagePublishingInterceptor
+ via the <publishing-interceptor> XML element.
+
+
+ Provide AOP configuration to apply the MessagePublishingInterceptor to managed objects.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+ As you can see the <publishing-interceptor> configuration look rather similar to Annotation-based approach
+ and it also utilizes the power of the Spring 3.0 Expression Language.
+
+
+ In the above example the execution of the echo method of a testBean will
+ render a Message with the following structure:
+
+
+ The Message payload will be of type String and value of "Echoing: [value]" where value is the value
+ returned by an executed method.
+
+
+ The Message will have header with the key "foo" value "bar".
+
+
+ The Message will be sent to echoChannel.
+
+
+
+
+
+ The second method is very similar to the first. Here every method that begins with 'repl' will render a Message with the following structure:
+
+
+ The Message payload will be the same as in the above sample
+
+
+ The Message will have header with the key "foo" and value that is the result of the SpEL expression 'bar'.toUpperCase() .
+
+
+ The Message will be sent to echoChannel.
+
+
+
+
+
+ The second method, mapping the execution of any method that begins with echoDef of testBean, will produce a
+ Message with the following structure.
+
+
+ The Message payload will be the value returned by an executed method.
+
+
+ Since the channel attribute is not provided explicitly, the Message will be sent to the
+ defaultChannel defined by the publisher.
+
+
+
+
+
+ For simple mapping rules you can rely on the publisher defaults. For example:
+
+<publishing-interceptor id="anotherInterceptor"/>
+
+ This will map the return value of every method that matches the pointcut expression to a payload and will be sent to a default-channel.
+ If the defaultChannelis not specified (as above) the messages will be sent to the global nullChannel.
+
+
+ Async Publishing
+
+
+ One important thing to understand is that publishing occurs in the same thread as your component's execution. So by default in is synchronous.
+ This means that the entire message flow would have to wait until he publisher flow completes.
+ However, quite often you want the complete opposite and that is to use Message publishing feature to initiate asynchronous sub-flows.
+ For example, you might host a service (HTTP, WS etc.) which receives a remote request.You may want to send this request internally into a
+ process that might take a while. However you may also want to reply to the user right away. So, instead of sending inbound
+ request for processing via the output channel (the conventional way), you can simply use ''outout-channel or $replyChannel'' header
+ to send simple acknowledgment-like reply back to the caller while using Message publisher feature to initiate a complex flow.
+
+
+ EXAMPLE:
+ Here is the simple service that receives a complex payload, which needs to be sent further for processing, but it
+ also need to reply to the caller with a simple acknowledgment.
+
+ So instead of hooking up the complex flow to the output channel we use Message publishing feature instead configuring it to create a
+ new Message using the input argument of the service method (above) and sending it to the 'localProcessChannel'. And to make sure this sub-flow
+ is asynchronous all we need to do is make sure that we send it to any type of async channel (ExecutorChannel in this example).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+ Another way of handling thi type of scenario is through wire-tap
+
+
+
+
+ Producing and publishing messages based on a scheduled trigger
+
+ In the above sections we looked at the Message publishing feature of Spring Integration which constructs and publishes messages as by-products of Method invocations.
+ However in that case, you are still responsible for invoking the method.
+ In Spring Integration 2.0 we've added another related useful feature: support for scheduled Message producers/publishers via the new "expression" attribute
+ on the 'inbound-channel-adapter' element. Scheduling could be based on several triggers, any one of which may be configured on the 'poller' sub-element.
+ Currently we support cron, fixed-rate, fixed-delay as well as any custom trigger implemented by you.
+
+
+ As mentioned above, support for scheduled producers/publishers is provided via the <inbound-channel-adapter> xml element.
+ Let's look at couple of examples:
+
+
+
+
+
+]]>
+
+ In the above example an inbound Channel Adapter will be created which will construct a Message with its payload being the result of the expression
+ defined in the expression attribute. Such message will be created and sent every time after the delay specified by the fixed-delay attribute.
+
+
+
+]]>
+
+ This example is very similar to the previous one, except that we are using the fixed-rate attribute which will allow us to send messages at a fixed rate (measuring from the start time of each task).
+
+
+
+]]>
+
+ This example demonstrates how you can apply a Cron trigger with a value specified in the cron attribute.
+
+
+
+
+
+
+]]>
+
+ Here you can see that in a way very similar to the Message publishing feature we are enriching a newly constructed Message with
+ extra Message headers which could take scalar values as well as the results of evaluating Spring expressions.
+
+
+
+ If you need to implement your own custom trigger you can use the trigger attribute to provide a reference to any spring configured
+ bean which implements the org.springframework.scheduling.Trigger interface.
+
+
+
+
+
+
+
+]]>
+
+
+
+
+
diff --git a/docs/src/reference/docbook/message.xml b/docs/src/reference/docbook/message.xml
new file mode 100644
index 0000000000..7656b0b030
--- /dev/null
+++ b/docs/src/reference/docbook/message.xml
@@ -0,0 +1,222 @@
+
+
+ Message Construction
+
+ The Spring Integration Message is a generic container for data. Any object can
+ be provided as the payload, and each Message also includes headers containing
+ user-extensible properties as key-value pairs.
+
+
+
+ The Message Interface
+ Here is the definition of the Message interface:
+ public interface Message<T> {
+
+ T getPayload();
+
+ MessageHeaders getHeaders();
+
+}
+
+
+ The Message 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 does require access to information about the Message,
+ such metadata can typically be stored to and retrieved from the metadata in the Message Headers.
+
+
+
+
+ Message Headers
+
+ 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 MessageHeaders class implements the
+ java.util.Map interface:
+ public final class MessageHeaders implements Map<String, Object>, Serializable {
+ ...
+}
+
+ Even though the MessageHeaders implements Map, it is effectively a read-only implementation. Any attempt to
+ put a value in the Map will result in an UnsupportedOperationException.
+ The same applies for remove and clear. 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 set 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.
+
+
+
+ As an implementation of Map, the headers can obviously be retrieved by calling get(..)
+ with the name of the header. Alternatively, you can provide the expected Class 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:
+ Object someValue = message.getHeaders().get("someKey");
+
+ CustomerId customerId = message.getHeaders().get("customerId", CustomerId.class);
+
+ Long timestamp = message.getHeaders().getTimestamp();
+
+
+
+ The following Message headers are pre-defined:
+
+ Pre-defined Message Headers
+
+
+
+
+ Header Name
+ Header Type
+
+
+
+
+ ID
+ java.util.UUID
+
+
+ TIMESTAMP
+ java.lang.Long
+
+
+ EXPIRATION_DATE
+ java.lang.Long
+
+
+ CORRELATION_ID
+ java.lang.Object
+
+
+ REPLY_CHANNEL
+ java.lang.Object (can be a String or MessageChannel)
+
+
+ ERROR_CHANNEL
+ java.lang.Object (can be a String or MessageChannel)
+
+
+ SEQUENCE_NUMBER
+ java.lang.Integer
+
+
+ SEQUENCE_SIZE
+ java.lang.Integer
+
+
+ PRIORITY
+ MessagePriority (an enum)
+
+
+
+
+
+
+ Many inbound and outbound adapter implementations will also provide and/or expect certain headers, and additional
+ user-defined headers can also be configured.
+
+
+
+
+ Message Implementations
+
+ The base implementation of the Message interface is
+ GenericMessage<T>, and it provides two constructors:
+ new GenericMessage<T>(T payload);
+
+new GenericMessage<T>(T payload, Map<String, Object> headers)
+ 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.
+
+
+ There are also two convenient subclasses available: StringMessage and
+ ErrorMessage. The former accepts a String as its payload:
+ StringMessage message = new StringMessage("hello world");
+
+String s = message.getPayload();
+ And, the latter accepts any Throwable object as its payload:
+ ErrorMessage message = new ErrorMessage(someThrowable);
+
+Throwable t = message.getPayload();
+ Notice that these implementations take advantage of the fact that the GenericMessage
+ base class is parameterized. Therefore, as shown in both examples, no casting is necessary when retrieving
+ the Message payload Object.
+
+
+
+
+ The MessageBuilder Helper Class
+
+ 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
+ unmodifiable Collection, and the MessageHeaders' map further exemplifies that; even though
+ the MessageHeaders class implements java.util.Map, any attempt to invoke a
+ put operation (or 'remove' or 'clear') on the MessageHeaders will result in an
+ UnsupportedOperationException.
+
+
+ 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: MessageBuilder.
+ 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 and payload of that
+ Message will be copied to the new Message:
+ Message<String> message1 = MessageBuilder.withPayload("test")
+ .setHeader("foo", "bar")
+ .build();
+
+Message<String> message2 = MessageBuilder.fromMessage(message1).build();
+
+assertEquals("test", message2.getPayload());
+assertEquals("bar", message2.getHeaders().get("foo"));
+
+
+ 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.
+ Message<String> message3 = MessageBuilder.withPayload("test3")
+ .copyHeaders(message1.getHeaders())
+ .build();
+
+Message<String> message4 = MessageBuilder.withPayload("test4")
+ .setHeader("foo", 123)
+ .copyHeadersIfAbsent(message1.getHeaders())
+ .build();
+
+assertEquals("bar", message3.getHeaders().get("foo"));
+assertEquals(123, message4.getHeaders().get("foo"));
+ Notice that the copyHeadersIfAbsent does not overwrite existing values. Also, in the
+ second example above, you can see how to set any user-defined header with setHeader.
+ 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).
+ Message<Integer> importantMessage = MessageBuilder.withPayload(99)
+ .setPriority(MessagePriority.HIGHEST)
+ .build();
+
+assertEquals(MessagePriority.HIGHEST, importantMessage.getHeaders().getPriority());
+
+Message<Integer> anotherMessage = MessageBuilder.fromMessage(importantMessage)
+ .setHeaderIfAbsent(MessageHeaders.PRIORITY, MessagePriority.LOW)
+ .build();
+
+assertEquals(MessagePriority.HIGHEST, anotherMessage.getHeaders().getPriority());
+
+
+
+ The MessagePriority is only considered when using a PriorityChannel
+ (as described in the next chapter). It is defined as an enum with five possible values:
+ public enum MessagePriority {
+ HIGHEST,
+ HIGH,
+ NORMAL,
+ LOW,
+ LOWEST
+}
+
+
+
+
diff --git a/docs/src/reference/docbook/overview.xml b/docs/src/reference/docbook/overview.xml
new file mode 100644
index 0000000000..6241073c9f
--- /dev/null
+++ b/docs/src/reference/docbook/overview.xml
@@ -0,0 +1,327 @@
+
+
+ Spring Integration Overview
+
+
+ Background
+
+ One of the key themes of the Spring Framework is inversion of control. 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, dependency injection relieves the components of the responsibility of locating or
+ creating their dependencies. Likewise, aspect-oriented programming 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.
+
+
+ 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.
+
+
+ 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 when certain business logic
+ should execute and where 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.
+
+
+ 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 Enterprise Integration Patterns
+ 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.
+
+
+
+
+ Goals and Principles
+ Spring Integration is motivated by the following goals:
+
+
+ Provide a simple model for implementing complex enterprise integration solutions.
+
+
+ Facilitate asynchronous, message-driven behavior within a Spring-based application.
+
+
+ Promote intuitive, incremental adoption for existing Spring users.
+
+
+
+ Spring Integration is guided by the following principles:
+
+
+ Components should be loosely coupled for modularity and testability.
+
+
+ The framework should enforce separation of concerns between business logic and
+ integration logic.
+
+
+ Extension points should be abstract in nature but within well-defined boundaries to promote
+ reuse and portability.
+
+
+
+
+
+
+ Main Components
+
+ From the vertical 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
+ horizontal 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.
+
+
+
+ Message
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+ Message Channel
+
+ 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.
+
+
+
+
+
+
+
+
+ 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.
+
+
+ Whereas "Point-to-Point" and "Publish/Subscribe" define the two options for how many
+ consumers will ultimately receive each Message, there is another important consideration: should the channel
+ buffer messages? In Spring Integration, Pollable Channels 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 poller is configured. On
+ the other hand, a consumer connected to a Subscribable Channel is simply Message-driven.
+ The variety of channel implementations available in Spring Integration will be discussed in detail in
+ .
+
+
+
+
+ Message Endpoint
+
+ One of the primary goals of Spring Integration is to simplify the development of enterprise integration
+ solutions through inversion of control. 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 routing and
+ transformation. 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.
+
+
+
+
+
+ Message Endpoints
+
+ 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
+ Enterprise Integration Patterns 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.
+
+
+
+ Transformer
+
+ 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.
+
+
+
+
+ Filter
+
+ 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.
+
+ 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.
+
+
+
+
+
+ Router
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+ Splitter
+
+ 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.
+
+
+
+
+ Aggregator
+
+ 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 CompletionStrategy as well as configurable settings for timeout, whether
+ to send partial results upon timeout, and the discard channel.
+
+
+
+
+ Service Activator
+
+ 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.
+
+ The output channel is optional, since each Message may also provide its own 'Return Address' header. This
+ same rule applies for all consumer endpoints.
+
+ 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.
+
+
+
+
+
+
+
+
+ A request-reply "Service Activator" endpoint connects a target object's method to input and output
+ Message Channels.
+
+
+
+
+
+
+ Channel Adapter
+
+ 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.
+
+
+
+
+
+
+
+
An inbound "Channel Adapter" endpoint connects a source system to a MessageChannel.
+
+
+
+
+
+
+
+
+
An outbound "Channel Adapter" endpoint connects a MessageChannel to a target system.
+
+
+
+
+
+
diff --git a/src/docbkx/resequencer.xml b/docs/src/reference/docbook/resequencer.xml
similarity index 100%
rename from src/docbkx/resequencer.xml
rename to docs/src/reference/docbook/resequencer.xml
diff --git a/docs/src/reference/docbook/resources.xml b/docs/src/reference/docbook/resources.xml
new file mode 100644
index 0000000000..109faa9b53
--- /dev/null
+++ b/docs/src/reference/docbook/resources.xml
@@ -0,0 +1,17 @@
+
+
+ Additional Resources
+
+
+ Spring Integration Home
+
+ The definitive source of information about Spring Integration is the
+ Spring Integration Home at
+ http://www.springsource.org. 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.
+
+
+
+
diff --git a/docs/src/reference/docbook/rmi.xml b/docs/src/reference/docbook/rmi.xml
new file mode 100644
index 0000000000..ec642fe05c
--- /dev/null
+++ b/docs/src/reference/docbook/rmi.xml
@@ -0,0 +1,66 @@
+
+
+ RMI Support
+
+
+ Introduction
+
+ 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.
+
+
+
+
+ Outbound RMI
+
+ To send messages from a channel over RMI, simply define an RmiOutboundGateway. 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.
+
+
+ To configure the outbound gateway write a bean definition like this:
+
+
+
+ ]]>
+
+
+
+
+
+ Inbound RMI
+
+ To receive messages over RMI you need to use a RmiInboundGateway. This gateway can be configured like this
+
+
+ ]]>
+
+
+
+
+
+ RMI namespace support
+
+ 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.
+
+
+
+
+
+
+
+
+ ]]>
+
+
+ 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.
+ ]]>
+
+
+
+
diff --git a/docs/src/reference/docbook/router.xml b/docs/src/reference/docbook/router.xml
new file mode 100644
index 0000000000..1fcc281e77
--- /dev/null
+++ b/docs/src/reference/docbook/router.xml
@@ -0,0 +1,405 @@
+
+
+ Router
+
+
+ Router Implementations
+
+ 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.
+
+
+ PayloadTypeRouter
+
+ A PayloadTypeRouter will send Messages to the channel as defined by payload-type
+ mappings.
+
+
+
+
+]]>
+
+
+ Configuration of PayloadTypeRouter is also supported via the namespace provided by Spring Integration (see ),
+ which essentially simplifies configuration by combining <router/> configuration and its corresponding implementation defined using <bean/> element
+ into a single and more concise configuration element.
+ The example below demonstrates PayloadTypeRouter configuration which is equivalent to the one above using Spring Integration's namespace support:
+
+
+
+
+
+]]>
+
+
+
+ HeaderValueRouter
+
+ A HeaderValueRouter will send Messages to the channel based on the individual header value mappings.
+ When HeaderValueRouter is created it is initialized with the name of the header to be evaluated, using constructor-arg.
+ The value of the header could be one of two things:
+
+ 1. Arbitrary value
+
+
+ 2. Channel name
+
+
+ If arbitrary value, then a channelResolver should be provided to map header values to channel names.
+ The example below uses MapBasedChannelResolver to set up a map of header values to channel names.
+
+
+
+
+
+
+
+
+
+
+]]>
+ If channelResolver is not specified, then the header value will be treated as a channel name
+ making configuration much simpler, where no channelResolver needs to be specified.
+
+
+
+]]>
+
+
+ Similar to the PayloadTypeRouter, configuration of HeaderValueRouter is also supported via namespace support provided by Spring Integration (see ).
+ The example below demonstrates two types of namespace-based configuration of HeaderValueRouter which are equivalent to the ones above using Spring Integration namespace support:
+
+ 1. Configuration where mapping of header values to channels is required
+
+
+
+
+]]>
+
+ 2. Configuration where mapping of header values is not required if header values themselves represent the channel names
+
+ ]]>
+
+
+ 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.
+
+
+
+ RecipientListRouter
+
+ A RecipientListRouter will send each received Message to a statically-defined
+ list of Message Channels:
+
+
+
+
+
+
+
+
+]]>
+
+
+
+ Configuration for RecipientListRouter is also supported via namespace support provided by Spring Integration (see ).
+ The example below demonstrates namespace-based configuration of RecipientListRouter and all the supported attributes using Spring Integration namespace support:
+
+
+
+
+
+]]>
+
+
+ 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
+ for more information.
+
+
+
+
+ The <router> element
+
+ 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):
+
+
+
+
+
+
+]]>
+
+ 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.
+ ]]>
+ Using a "ref" attribute is generally recommended if the custom router implementation can be reused in other
+ <router> definitions. However if the custom router implementation should be scoped to a
+ concrete definition of the <router>, you can provide an inner bean definition:
+
+
+]]>
+
+
+
+ Using both the "ref" attribute and an inner handler definition in the same <router> configuration
+ is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
+
+
+
+
+
+ The @Router Annotation
+
+ When using the @Router annotation, the annotated method can return either the
+ MessageChannel or String 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.
+ @Router
+public MessageChannel route(Message message) {...}
+
+@Router
+public List<MessageChannel> route(Message message) {...}
+
+@Router
+public String route(Foo payload) {...}
+
+@Router
+public List<String> route(Foo payload) {...}
+
+
+ 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
+ Message type as the method parameter, the @Router
+ annotation may also use the @Header parameter annotation that is documented in .
+ @Router
+public List<String> route(@Header("orderStatus") OrderStatus status)
+
+
+
+ For routing of XML-based Messages, including XPath support, see .
+
+
+
+ Dynamic Routers
+
+ So as you can see, Spring Integration provides quite a few different router configurations for most common
+ content-based routing use cases as well as the option of implementing custom routers as POJOs.
+ For example; Payload Type Router provides a simple way to configure a router which computes channels
+ based on the payload type of the incoming Message while Header Value Router provides the
+ same convenience in configuring a router which computes channels based on evaluating the value
+ of a particular Message Header. There is also an expression-based (SpEL) routers where the channel
+ is determined based on evaluating an expression which gives these type of routers some dynamic characteristics.
+
+
+ However these routers share one common attribute - static configuration. Even in the case of
+ expression-based routers, the expression itself is defined as part of the router configuration which means that
+ the same expression operating on the same value will always result in the computation of the same channel.
+ This is good in most cases since such routes are well defined and therefore predictable. But there are times when we
+ need to change router configurations dynamically so message flows could be routed to a different channel.
+
+ For example:
+
+ You might want to bring down some part of your system for maintenance. So, temporarily you want to re-reroute
+ messages to a different message flow. Or you may want to introduce more granularity to your message flow by adding another
+ route to handle a more concrete type of java.lang.Number (in cases of Payload Type Router).
+
+
+ Unfortunately with static router configuration to accomplish this you'd have to bring down your entire application,
+ change the configuration of the router (change routes) and bring it back up. This is obviously not the solution.
+
+
+
+ Dynamic Router
+
+ pattern describes the mechanisms by which one can change/configure routers dynamically without
+ bringing down your system or individual routers.
+
+
+ Before we get into the specifics of how it is accomplished in Spring Integration lets quickly summarize the
+ typical flow of the router, which consists of 3 simple steps:
+
+
+ Step 1 - Compute channel identifier which is a value calculated by the
+ router once it receives the Message. Typically it is a String or and instance of the actual
+ MessageChannel.
+
+
+ Step 2 - Resolve channel identifier to channel name. We'll describe
+ specifics of this process in a moment.
+
+
+ Step 3 - Resolve channel name to the actual MessageChannel
+
+
+
+
+
+ There is not much that could be done with regard to router dynamics if Step 1 results in the actual instance of the
+ MessageChannel simply because MessageChannel is the final product of any
+ router's job. However, if Step 1 results in channel identifier that is not and instance of MessageChannel,
+ then there are quite a few possibilities to influence the process of calculating what will be the final instance of the Message Channel.
+ Lets look at couple of the examples in the context of the 3 steps mentioned above:
+
+
+ Payload Type Router
+
+
+
+
+
+]]>
+
+
+ Within the context of the Payload Type Router the 3 steps mentioned above would be realized as:
+
+
+ Step 1 - Compute channel identifier which is the fully qualified name of the payload type
+ (e.g., java.lang.String).
+
+
+ Step 2 - Resolve channel identifier to channel name where
+ the result of the previous step is used to select the appropriate value from the payload type mapping
+ defined via mapping element.
+
+
+ Step 3 - Resolve channel name to the actual instance of the
+ MessageChannel where using ChannelResolver router will obtain a
+ reference to a bean (which is hopefully a MessageChannel) identified by the result of the
+ previous step.
+
+
+ In other words each step feeds the next step until thr process completes.
+
+
+ Header Value Router
+
+
+
+
+
+]]>
+
+
+ Similar to the PayloadTypeRouter:
+
+
+ Step 1 - Compute channel identifier which is the value of the header identified by the
+ header-name attribute.
+
+
+ Step 2 - Resolve channel identifier to channel name where
+ the result of the previous step is used to select the appropriate value from the general mapping
+ defined via mapping element.
+
+
+ Step 3 - Resolve channel name to the actual instance of the
+ MessageChannel where using ChannelResolver router will obtain a
+ reference to a bean (which is hopefully a MessageChannel) identified by the result of the
+ previous step.
+
+
+
+
+ The above two configurations of two different router types look almost identical.
+ However if we look at the different configuration of the HeaderValueRouter we clearly see that
+ there is no mapping sub element:
+ ]]>
+ But configuration is still perfectly valid. So the natural question is what about the maping in the Step 2?
+
+
+ What this means is that Step 2 is now an optional step. If mapping is not defined then the channel identifier
+ value computed in Step 1 will automatically be treated as the channel name which will now be resolved to the
+ actual MessageChannel in the Step 3. What it also means is that Step 2 is one of the key steps to
+ provide dynamic characteristics to the routers, since it introduces a process which
+ allows you to change the way 'channel identifier' resolves to 'channel name',
+ thus influencing the process of determining the final instance of the MessageChannel from the initial
+ channel identifier.
+
+ For Example:
+
+ In the above configuration lets assume that the testHeader value is 'kermit' which is now a channel identifier
+ (Step 1). Since there is no mapping in this router, resolving this channel identifier to a channel name
+ (Step 2) is impossible and this channel identifier is now treated as channel name. However what if
+ there was mapping but for a different value, the end result would still be the same and that is:
+ if new value can not be determined through the process of resolving 'channel identifier' to a 'channel name',
+ such 'channel identifier' becomes 'channel name'
+
+
+ So all that is left is for Step 3 to resolve channel name ('kermit') to an actual instance of the
+ MessageChannel identified by this name. That will be done via default
+ ChannelResolver implementation which is BeanFactoryChannelResolver which
+ basically does a bean lookup by the name provided. So now all messages which contain the header/value pair as testHeader=kermit
+ are going to be routed to a 'kermit' MessageChannel.
+
+
+ But what if you want to route these messages to 'simpson' channel? Obviously changing static configuration would work,
+ but would also require bringing your system down. However if you had access to channel identifier map, then you
+ could just introduce a new mapping where header/value pair is now kermit=simpson, thus allowing Step 2 to treat
+ 'kermit' as channel identifier while resolving it to 'simpson' as channel name .
+
+
+ The same obviously applies for PayloadTypeRouter where you can now remap or remove a particular payload type
+ mapping, and every other router including expression-based routers since their computed value
+ will now have a chance to go through Step 2 to be aditionally resolved to the actual channel name.
+
+
+ In Spring Integration 2.0 routers hierarchy underwent major refactoring and now any router that is a subclass of the
+ AbstractMessageRouter (all framework defined routers) is a Dynamic Router simply because
+ channelIdentiferMap is defined at the AbstractMessageRouter with convenient accessors
+ and modifiers exposed as public methods allowing you to change/add/remove router mapping at runtime via JMX (see section section 29) or
+ ControlBus (see section section 29.7) functionality.
+
+
+
+ Control Bus
+
+
+ One of the way to manage the router mappings is through the Control Bus
+ which exposes a Control Channel where you can send
+ control messages to manage and monitor Spring Integration components which includes routers.
+ For more information about the Control Bus see section 29.7. Typically you would send a control message asking to invoke a
+ particular JMX operation on a particular managed component (e.g., router). The two managed operations (methods) that are
+ specific to changing router resolution process are:
+
+
+ public void setChannelMapping(String channelIdentifier, String channelName) -
+ will allow you to add new or modify existing mapping of channel identifier to channel name
+
+
+ public void removeChannelMapping(String channelIdentifier) -
+ will allow you to remove a particular channel mapping, thus disconnecting the relationship between
+ channel identifier and channel name
+
+
+ There are obviously other managed operations, so please refer to an AbstractMessageRouter for more detail
+
+
+ You can also use your favorite JMX client (e.g., JConsole) and use those operations (methods) to change
+ router configuration. For more information on Spring Integration management and monitoring please visit
+ section 29 of this manual.
+
+
+
+
diff --git a/docs/src/reference/docbook/samples.xml b/docs/src/reference/docbook/samples.xml
new file mode 100644
index 0000000000..b2ca7d18fe
--- /dev/null
+++ b/docs/src/reference/docbook/samples.xml
@@ -0,0 +1,662 @@
+
+
+ Spring Integration Samples
+
+
+ Introduction
+
+ Starting with the current release of Spring Integration the samples are no longer included with
+ Spring Integration distribution. Instead we've switched to a much simpler collaborative model that should promote
+ better community participation and community contributions. Samples now have a dedicated Git SCM repository and a
+ dedicated JIRA Issue Tracking system. Sample development will also have its own lifecycle which is not dependent on the
+ lifecycle of the framework releases although the repository will still be tagged with each major release for compatibility
+ reasons.
+
+
+ The great benefit to the community is that we can now add more samples and make them available to you right away
+ without waiting for the release to get them out to you. Having its own JIRA that is not tied up to the the actual
+ framework is also a great benefit. You now have a dedicated place to suggest samples as well as report issues with existing
+ samples. Or you may want to submit a sample to us as an attachment through the JIRA and if we believe your sample adds value we
+ would be more then glad to add it to a samples repository properly crediting the author.
+
+
+
+
+ Where to get Samples
+
+ To monitor samples development and to get more information on the repository you can visit the following
+ URL: http://git.springsource.org/spring-integration/samples
+ Since we are using Git SCM we should use the proper terminology as well when it comes to the tasks you need to perform to make
+ samples available locally on your machine. For more information on Git SCM please visit their
+ website: http://git-scm.com/
+
+
+ CLONE samples repository. (For those unfamiliar with Git, this is somewhat the equivalent of a checkout.)
+
+
+ This is the first step you should go through. You must have Git installed on your machine. There are many GUI-based products
+ available for many platforms. Simple Google search will let you find them.
+ To clone samples repository from command line:
+ mkdir spring-itegration-samples
+> cd spring-itegration-samples
+> git clone git://git.springsource.org/spring-integration/samples.git]]>
+
+
+ That is all you need to do. Now you have cloned the entire samples repository. Since samples repository is a live
+ repository, you might want to perform periodic updates to get new samples as well as updates to the existing samples.
+ To get the updates use git PULL command:
+ git pull]]>
+
+
+ Submit samples or sample requests
+
+
+ As mentioned earlier, Spring Integration samples have a dedicated JIRA Issue tracking system.
+ To submit new sample request or to submit the actual sample (as an attachment) please visit our JIRA Issue Tracking system:
+ https://jira.springframework.org/browse/INTSAMPLES
+
+
+
+ Samples structure
+
+ The structure of the samples changed as well. With plans for more samples we realized that some
+ samples have different goals then others. While they all share the common goal of showing you how to apply and work with
+ Spring Integration framework, they also defer in areas where some samples were meant to concentrate on a technical
+ use case while others on the business use case and some samples are all about showcasing various techniques that
+ could be applied to address certain scenarios (both technical and business). Categorization of samples will allow us
+ better organize them based on the problem each sample addresses while giving you a simpler way of finding the right sample
+
+
+ Currently there are 4 categories. Within the samples repository each category has its own directory which is named after the
+ category name:
+
+
+
+ BASIC (samples/basic)
+
+
+ This is a good place to get started. The samples here are technically motivated and demonstrate the bare
+ minimum with regard to configuration and code, to help you to get started quickly by introducing you to the basic concepts,
+ API and configuration of Spring Integration as well as Enterprise Integration Patterns (EIP). For example; If your are
+ looking for an answer on how to implement and wire Service Activator to a Channel
+ or how to use Messaging Gateway to your message exchange or how to get started with using MAIL or
+ TCP/UDP modules etc., this would be the right place to find a good sample. The bottom line is this is a good place
+ to get started.
+
+
+
+ INTERMEDIATE (samples/intermediate)
+
+
+ This category targets developers who are already familiar with Spring Integration framework (past getting started),
+ but need some more guidance while resolving a more advanced technical problems one might deal with
+ once switch to a Messaging architecture.
+ For example; If you are looking for an answer on how to handle errors in various message exchange
+ scenarios or how to properly configure the Aggregator for the situations where some messages
+ might not ever arrive for aggregation etc,. and any other issue that goes beyond a basic implementation and configuration
+ of a particular component and addresses "what else you can do with it" type of problem this
+ would be the right place to find these type of samples.
+
+
+
+ ADVANCED (samples/advanced)
+
+
+ This category targets develoopers who are very familiar with Spring Integration framework but looking to
+ extend it to address a specific custom need by using Spring Integration public API.
+ For example; if you are looking for samples showing you how to implement a custom Channel or
+ Consumer (event-based or polling-based), or you trying to figure out what is the most appropriate
+ way to implement custom Bean parser on top of Spring Integration Bean parsers hierarchy when implementing custom name space
+ for a custom component, this would be the right place to look.
+ Here you can also find samples that will help you with Adapter development. Spring Integration comes
+ with an extensive library of adapters to allow you to connect remote systems with Spring Integration messaging framework.
+ However you might have a need to integrate with system for which the core framework does not provide an adapter.
+ So you have to implement your own. This category would include samples showing you how to do it.
+
+
+
+
+ APPLICATIONS (samples/applications)
+
+
+ This category targets developers and architects who have a good understanding of the Messaging architecture,
+ EIP and above average understanding of Spring and Spring Integration frameworks and are looking for samples that
+ address a particular business problem. In other words the emphasis of samples in this category
+ is business use cases and how it could be solved via Messaging Architecture and Spring Integration
+ in particular.
+ For example; If you are interested to see how a Loan Broker or Travel Agent
+ process could be implemented and automated via Spring Integration this would be the right place to find these types of samples.
+
+
+
+
+ Remember! Spring Integration is a community driven framework, therefore community participation is IMPORTANT.
+That includes Samples, so if you can't find what you are looking for let us know.
+
+
+
+
+
+ Samples
+
+ Currently Spring Integration comes with quite a few samples and you can only expect more.
+ To help you better navigate through them, each sample comes with its own readme.txt file which coveres
+ sevaral details about the sample (e.g., what EIP patterns it addresses, what problem it is trying to solve, how to run sample etc.).
+ However, certain samples require a more detailed and some times graphical explanation. In these section you'll
+ find details on samples that we believe require special attention.
+
+
+ Loan Broker
+
+ In this section, we will review a Loan Broker sample application that is included in the
+ Spring Integration samples. This sample is inspired by one of the samples featured in Gregor
+ Hohpe's Ramblings.
+
+ The diagram below represents the entire process
+
+
+
+
+
+
+
+
+
+
+ Now lets look at this process in more details
+
+ At the core of EIP architecture are the very simple yet powerful concepts of Pipes and Filters and Message. Endpoints (Filters) are
+ connected with one another via Channels (Pipes). The producing endpoint sends Message to the Channel and the Message is retrieved
+ by the Consuming endpoint. This architecture is meant to define various mechanisms that describe How information is exchanged between
+ the endpoints, without any awareness of What those endpoints are or What information they are exchanging, thus providing for a very loosely
+ coupled and flexible collaboration model while also, decoupling Integration concerns from Business concerns. EIP extends this architecture
+ by further defining:
+
+
+ The types of pipes (Point-to-Point Channel, Publish-Subscribe Channel, Channel Adapter, etc.)
+
+
+
+ The core filters and patterns around how filters collaborate with pipes
+ (Message Router, Splitters and Aggregators, various Message Transformation patterns, etc.)
+
+
+
+
+ The details and variations of this use case are very nicely described in Chapter 9 of the EIP Book, but here is the brief summary;
+ A Consumer while shopping for the best Loan Quote(s) subscribes to the services of a Loan Broker, which handles details such as:
+
+
+ Consumer pre-screening (e.g., obtain and review the consumer's Credit history)
+
+
+
+ Determine the most appropriate Banks (e.g., based on consumer's credit history/score)
+
+
+
+ Send a Loan quote request to each selected Bank
+
+
+ Collect responses from each Bank
+
+
+ Filter responses and determine the best quote(s), based on consumer's requirements.
+
+
+ Pass the Loan quote(s) back to the consumer.
+
+
+
+
+ Obviously the real process of obtaining a loan quote is a bit more complex, but since our goal here is to demonstrate how
+ Enterprise Integration Patterns are realized and implemented within SI, the use case has been simplified to concentrate only on
+ the Integration aspects of the process. It is not an attempt to give you an advice in consumer finances.
+
+
+ As you can see, by hiring a Loan Broker, the consumer is isolated from the details of the Loan Broker's operations, and each Loan Broker's
+ operations may defer from one another to maintain competitive advantage, so whatever we assemble/implement must be flexible so any changes
+ could be introduced quickly and painlessly.
+ Speaking of change, the Loan Broker sample does not actually talk to any 'imaginary' Banks or Credit bureaus. Those services are stubbed out.
+ Our goal here is to assemble, orchestrate and test the integration aspect of the process as a whole. Only then can we start thinking about
+ wiring such process to the real services. At that time the assembled process and its configuration will not change regardless of the number
+ of Banks a particular Loan Broker is dealing with, or the type of communication media (or protocols) used (JMS, WS, TCP, etc.)
+ to communicate with these Banks.
+
+ DESIGN
+
+ As you analyze the 6 requirements above you'll quickly see that they all fall into the category of Integration concerns.
+ For example, in the consumer pre-screening step we need to gather additional information about the consumer and the consumer's desires
+ and enrich the loan request with additional meta information. We then have to filter such information to select the most appropriate list of
+ Banks, and so on. Enrich, filter, select – these are all integration concerns for which EIP defines a solution in the form of patterns.
+ SI provides an implementation of these patterns.
+
+ Messaging Gateway
+
+
+
+
+
+
+
+
+
+
+ The Messaging Gateway pattern provides a simple mechanism to access messaging systems, including our Loan Broker.
+ In SI you define the Gateway as a Plain Old Java Interface (no need to provide an implementation), configure it via the
+ XML <gateway&gr; element or via annotation and use it as any other Spring bean. SI will take care of
+ delegating and mapping method invocations to the Messaging infrastructure by generating a Message (payload is mapped to an
+ input parameter of the method) and sending it to the designated channel.
+
+
+
+
+]]>
+
+
+ Our current Gateway provides two methods that could be invoked. One that will return the best single quote and another one that
+ will return all quotes. Somehow downstream we need to know what type of reply the caller is looking for. The best way to achieve
+ this in Messaging architecture is to enrich the content of the message with some meta-data describing your intentions.
+ Content Enricher is one of the patterns that addresses this and although Spring Integration does provide a
+ separate configuration element to enrich Message Headers with arbitrary data (we'll see it later), as a convenience, since
+ Gateway element is responsible to construct the initial Message it provides embedded
+ capability to enrich the newly created Message with arbitrary Message Headers. In our
+ example we are adding header RESPONSE_TYPE with value 'BEST'' whenever the getBestQuote() method is invoked. For other method
+ we are not adding any header. Now we can check downstream for an existence of this header and based on its presence and its value
+ we can determine what type of reply the caller is looking for.
+
+
+
+ Based on the use case we also know there are some pre-screening steps that needs to be performed such as getting and evaluating the consumer's
+ credit score, simply because some premiere Banks will only typically accept quote requests from consumers that meet a minimum credit
+ score requirement. So it would be nice if the Message would be enriched with such information before it is forwarded
+ to the Banks. It would also be nice if when several processes needs to be completed to provide such meta-information, those
+ processes could be grouped in a single unit. In our use case we need to determine credit score and based on the credit score and some
+ rule select a list of Message Channels (Bank Channels) we will sent quote request to.
+
+ Composed Message Processor
+
+ The Composed Message Processor pattern describes rules around building endpoints that maintain control over message flow which
+ consists of multiple message processors. In Sprig Integration Composed Message Processor pattern is implemented via
+ <chain> element.
+
+
+
+
+
+
+
+
+
+
+ As you can see from the above configuration we have a chain with inner header-enricher element which will further enrich the
+ content of the Message with the header CREDIT_SCORE and value that will be determined by the call to a
+ credit service (simple POJO spring bean identified by 'creditBureau' name) and then it will delegate to the Message Router
+
+ Message Router
+
+
+
+
+
+
+
+
+
+
+ There are several implementation of Message Routing pattern available in Spring Integration. Here we are using
+ router that will determine a list of channels based on evaluating an expression (Spring Expression Language) which will look at
+ the credit score that was determined is the previous step and will select the list of channels from the Map bean with id 'banks'
+ whose values are 'premier' or 'secondary' based o the value of credit score. Once the list of Channels is selected, the
+ Message will be routed to those Channels.
+
+
+ Now, one last thing the Loan Broker needs to to is to receive the loan quotes form the banks, aggregate them by consumer
+ (we don't want to show quotes from one consumer to another), assemble the response based on the consumer's selection criteria
+ (single best quote or all quotes) and reply back to the consumer.
+
+ Message Aggregator
+
+
+
+
+
+
+
+
+
+
+
+ An Aggregator pattern describes an endpoint which groups related Messages into a single
+ Message. Criteria and rules can be provided to determine an aggregation and correlation strategy.
+ SI provides several implementations of the Aggregator pattern as well as a convenient name-space based configuration.
+
+
+]]>
+
+
+
+ Our Loan Broker defines a 'quotesAggregator' bean via the <aggregator> element which provides a default
+ aggregation and correlation strategy. The default correlation strategy correlates messages based on the $corelationId header
+ (see Correlation Identifier pattern). What's interesting is that we never provided the value for this header.
+ It was set earlier by the router automatically, when it generated a separate Message for each Bank channel.
+
+
+ Once the Messages are correlated they are released to the actual Aggregator implementation.
+ Although default Aggregator is provided by SI, its strategy (gather the list of payloads from all
+ Messages and construct a new Message with this List as payload) does not satisfy our
+ requirement. The reason is that our consumer might require a single best quote or all quotes. To communicate the consumer's
+ intention, earlier in the process we set the RESPONSE_TYPE header. Now we have to evaluate this header and return either
+ all the quotes (the default aggregation strategy would work) or the best quote (the default aggregation strategy will not work
+ because we have to determine which loan quote is the best).
+
+
+
+ Obviously selecting the best quote could be based on complex criteria and would influence the complexity of the aggregator implementation and
+ configuration, but for now we are making it simple. If consumer wants the best quote we will select a quote with the lowest interest
+ rate. To accomplish that the LoanQuoteAggregator.java will sort all the quotes and return the first one.
+ The LoanQuote.java implements Comparable which compares quotes based on the rate attribute.
+ Once the response Message is created it is sent to the default-reply-channel of the Messaging Gateway
+ (thus the consumer) which started the process. Our consumer got the Loan Quote!
+
+ Conclusion
+
+ As you can see a rather complex process was assembled based on POJO (read existing, legacy), light weight, embeddable messaging
+ framework (Sprig Integration) with a loosely coupled programming model intended to simplify integration of heterogeneous systems
+ without requiring a heavy-weight ESB-like engine or proprietary development and deployment environment, becouse as a developer you
+ should not be porting your Swing or console-based application to an ESB-like server or implementing proprietary interfaces just
+ because you have an integration concern.
+
+
+ This and other samples in this section are build on top of Enterprise Integration Patterns that meant to describe "building blocks"
+ for YOUR solution but not to be solutions in of themselves. Integration concerns exist in all types of applications (server based and not)
+ and should not require change in design, testing and deployment strategy if such applications need to integrate with one another.
+
+
+
+
+
+
+
+ The Cafe Sample
+
+ In this section, we will review a Cafe sample application that is included in the
+ Spring Integration samples. This sample is inspired by another sample featured in Gregor
+ Hohpe's Ramblings.
+
+
+ The domain is that of a Cafe, and the basic flow is depicted in the following diagram:
+
+
+
+
+
+
+
+
+
+
+
+
+ The Order object may contain multiple OrderItems. Once the order
+ is placed, a Splitter will break the composite order message into a single message per
+ drink. Each of these is then processed by a Router that determines whether the drink is hot
+ or cold (checking the OrderItem object's 'isIced' property). The
+ Barista 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 Delivery object.
+
+
+ Here is the XML configuration:
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+ 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:
+ split(Order order) {
+ return order.getItems();
+ }
+ }]]>
+ In the case of the Router, the return value does not have to be a MessageChannel
+ instance (although it can be). As you see in this example, a String-value representing the channel name is
+ returned instead.
+
+
+
+ Now turning back to the XML, you see that there are two <service-activator> elements. Each of these
+ is delegating to the same Barista instance but different methods: 'prepareHotDrink'
+ or 'prepareColdDrink' corresponding to the two channels where order items have been routed.
+
+
+
+ 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
+ CafeDemo '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 <gateway> 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 Cafe interface.
+ public interface Cafe {
+
+ @Gateway(requestChannel="orders")
+ void placeOrder(Order order);
+
+ }
+ Finally, have a look at the main() method of the CafeDemo itself.
+ 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);
+ }
+ }]]>
+
+
+ To run this sample as well as 8 others, refer to the README.txt within the "samples" directory
+ of the main distribution as described at the beginning of this chapter.
+
+
+ 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:
+
+
+
+ ]]>
+ ]]>
+
+ ]]>]]>
+
+
+ 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.
+
+
+ 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.
+
+
+
+
+ The XML Messaging Sample
+
+ The xml messaging sample in the org.springframework.integration.samples.xml 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.
+
+
+ First the order is split into a number of messages, each one representing a single order item using
+ the XPath splitter component.
+
+
+
+ ]]>
+
+
+ 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
+ MapBasedChannelResolver which maps the XPath evaluation result to a channel reference.
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+ Where the order item is not in stock the message is transformed using
+ xslt into a format suitable for sending to the supplier.
+
+ ]]>
+
+
+
+
+
+
diff --git a/docs/src/reference/docbook/security.xml b/docs/src/reference/docbook/security.xml
new file mode 100644
index 0000000000..1d17fb6ed6
--- /dev/null
+++ b/docs/src/reference/docbook/security.xml
@@ -0,0 +1,64 @@
+
+
+ Security in Spring Integration
+
+
+ Introduction
+
+ Spring Integration provides integration with the
+ Spring Security project
+ to allow role based security checks to be applied to channel send and receive invocations.
+
+
+
+
+ Securing channels
+
+ Spring Integration provides the interceptor ChannelSecurityInterceptor, which extends
+ AbstractSecurityInterceptor and intercepts send and receive calls on the channel. Access decisions
+ are then made with reference to ChannelInvocationDefinitionSource which provides the definition of
+ the send and receive security constraints. The interceptor requires that a valid SecurityContext
+ has been established by authenticating with Spring Security, see the Spring Security reference documentation for details.
+
+
+ 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 java.util.regexp.Pattern.
+
+
+
+
+
+
+]]>
+
+
+ By default the secured-channels namespace element expects a bean named authenticationManager which implements
+ AuthenticationManager and a bean named accessDecisionManager which implements
+ AccessDecisionManager. Where this is not the case references to the appropriate beans can be configured
+ as attributes of the secured-channels element as below.
+
+
+
+]]>
+
+
+
+
+
+
+
diff --git a/docs/src/reference/docbook/service-activator.xml b/docs/src/reference/docbook/service-activator.xml
new file mode 100644
index 0000000000..2325d17e54
--- /dev/null
+++ b/docs/src/reference/docbook/service-activator.xml
@@ -0,0 +1,71 @@
+
+
+ Service Activator
+
+
+ Introduction
+
+ 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.
+
+
+
+
+ The <service-activator/> Element
+
+ To create a Service Activator, use the 'service-activator' element with the 'input-channel' and 'ref' attributes:
+ <service-activator input-channel="exampleChannel" ref="exampleHandler"/>
+
+
+ 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.
+ <service-activator input-channel="exampleChannel" ref="somePojo" method="someMethod"/>
+
+
+ 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:
+ <service-activator input-channel="exampleChannel" output-channel="replyChannel"
+ ref="somePojo" method="someMethod"/>
+ If no "output-channel" is available, it will then check the Message's REPLY_CHANNEL header
+ value. If that value is available, it will then check its type. If it is a
+ MessageChannel, the reply message will be sent to that channel. If it is a
+ String, then the endpoint will attempt to resolve the channel name to a channel instance.
+ If the channel cannot be resolved, then a ChannelResolutionException will be thrown.
+
+
+ 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 annotations as described in
+
+
+ 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.
+
+
+ Using a "ref" attribute is generally recommended if the custom Service Activator handler implementation can be reused
+ in other <service-activator> definitions. However if the custom Service Activator handler implementation
+ should be scoped to a single definition of the <service-activator>, you can use an inner bean definition:
+
+
+]]>
+
+
+
+ Using both the "ref" attribute and an inner handler definition in the same <service-activator>
+ configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
+
+
+
+
+
diff --git a/docs/src/reference/docbook/splitter.xml b/docs/src/reference/docbook/splitter.xml
new file mode 100644
index 0000000000..b22ffe64b8
--- /dev/null
+++ b/docs/src/reference/docbook/splitter.xml
@@ -0,0 +1,157 @@
+
+
+ Splitter
+
+
+ Introduction
+
+ 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.
+
+
+
+ Programming model
+
+ 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.
+
+ An excerpt from AbstractMessageSplitter can be seen below:
+
+ public abstract class AbstractMessageSplitter
+ extends AbstractReplyProducingMessageConsumer {
+ ...
+ protected abstract Object splitMessage(Message<?> message);
+
+}
+
+ 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:
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ Configuring a Splitter using XML
+
+ A splitter can be configured through XML as follows:<channel id="inputChannel"/>
+
+<splitter id="splitter"
+ ref="splitterBean"
+ method="split"
+ input-channel="inputChannel"
+ output-channel="outputChannel" />
+
+<channel id="outputChannel"/>
+
+<beans:bean id="splitterBean" class="sample.PojoSplitter"/>
+
+ The id of the splitter is
+ optional.
+
+
+
+ A reference to a bean defined in the application context. The
+ bean must implement the splitting logic as described in the section
+ above. Optional.
+ If reference to a bean is not provided, then it is assumed that the payload of the Message that arrived on the input-channel is
+ an implementation of java.util.Collection and the default splitting logic will be applied on such Collection,
+ incorporating each individual element into a Message and depositing it on the output-channel.
+
+
+
+
+ The method (defined on the bean specified above) that
+ implements the splitting logic.
+ Optional.
+
+
+
+ The input channel of the splitter.
+ Required.
+
+
+
+ The channel where the splitter will send the results of
+ splitting the incoming message. Optional (because incoming
+ messages can specify a reply channel themselves).
+
+
+
+ Using a "ref" attribute is generally recommended if the custom splitter handler implementation can be reused in other
+ <splitter> definitions. However if the custom splitter handler implementation should be scoped to a
+ single definition of the <splitter>, you can configure an inner bean definition:
+
+
+]]>
+
+
+
+ Using both a "ref" attribute and an inner handler definition in the same <splitter>
+ configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
+
+
+
+
+
+ Configuring a Splitter with Annotations
+
+ The @Splitter annotation is
+ applicable to methods that expect either the
+ Message 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 Message
+ 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 @Splitter is defined.
+ @Splitter
+List<LineItem> extractItems(Order order) {
+ return order.getItems()
+}
+
+
+
diff --git a/docs/src/reference/docbook/stream.xml b/docs/src/reference/docbook/stream.xml
new file mode 100644
index 0000000000..f4b1c35d8e
--- /dev/null
+++ b/docs/src/reference/docbook/stream.xml
@@ -0,0 +1,91 @@
+
+
+ Stream Support
+
+
+ Introduction
+
+ In many cases application data is obtained from a stream. It is not 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.
+
+
+
+
+ Reading from streams
+
+ Spring Integration provides two adapters for streams. Both ByteStreamReadingMessageSource and
+ CharacterStreamReadingMessageSource implement MessageSource.
+ 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
+ InputStream, and the character stream version requires a Reader as
+ the single constructor argument. The ByteStreamReadingMessageSource also accepts the 'bytesPerMessage'
+ property to determine how many bytes it will attempt to read into each Message. The
+ default value is 1024
+
+
+
+
+
+
+
+]]>
+
+
+
+
+
+ Writing to streams
+
+ For target streams, there are also two implementations: ByteStreamWritingMessageHandler and
+ CharacterStreamWritingMessageHandler. Each requires a single constructor argument -
+ OutputStream for byte streams or Writer for character streams,
+ and each provides a second constructor that adds the optional 'bufferSize'. Since both of these
+ ultimately implement the MessageHandler interface, they can be referenced from a
+ channel-adapter configuration as described in more detail in
+ .
+
+
+
+
+
+
+
+]]>
+
+
+
+
+
+
+
+ Stream namespace support
+
+ To reduce the configuration needed for stream related channel adapters there is a namespace defined. The following schema locations are needed to use it.
+
+]]>
+
+
+ To configure the inbound channel adapter the following code snippet shows the different configuration options that are supported.
+
+
+]]>
+
+
+ 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.
+
+
+
+
+
+
+
+ ]]>
+
+
+
diff --git a/docs/src/reference/docbook/transactions.xml b/docs/src/reference/docbook/transactions.xml
new file mode 100644
index 0000000000..99c173f65e
--- /dev/null
+++ b/docs/src/reference/docbook/transactions.xml
@@ -0,0 +1,175 @@
+
+
+ Transaction Support
+
+
+ Understanding Transactions in Message flows
+
+ Spring Integration exposes several hooks to address transactional needs of you message flows.
+ But to better understand these hooks and how you can benefit from them we must first revisit the 6 mechanisms
+ that could be used to initiate Message flows and see how transactional needs of these flows
+ could be addressed within each of these mechanisms.
+
+
+ Here are the 6 mechanisms to initiate a Message flow and their short summary (details for each are provided throughout this manual):
+
+
+ Gateway Proxy - Your basic Messaging Gateway
+
+
+ MessageChannel - Direct interactions with MessageChannel methods (e.g., channel.send(message))
+
+
+ Message Publisher - the way to initiate message flow as a bi-product of method invocations on Spring beans
+
+
+ Inbound Channel Adapters/Gateways - the way to initiate message flow based on connecting third-party
+ system with Spring Integration messaging system(e.g., [JmsMessage] -> Jms Inbound Adapter[SI Message] -> SI Channel)
+
+
+ Scheduler - the way to initiate message flow based on scheduling events distributed
+ by a pre-configured Scheduler
+
+
+ Poller - similar to the Scheduler and is the way to initiate message flow based on scheduling
+ or interval-based events distributed by a pre-configured Poller
+
+
+
+
+ These 6 cold be split in 2 general categories:
+
+
+ Message flows initiated by a USER process - Example scenarios in this category
+ would be invoking a Gateway method or explicitly sending a Message to a MessageChannel. In other words these message flows depend on third
+ party process (e.g., some code that we wrote) to be initiated
+
+
+ Message flows initiated by the DAEMON process - Example scenarios in this category would be a Poller
+ polling for a Message queue to initiate a new Message flow with the polled Message or a Scheduler scheduling the
+ process, by creating a new Message and initiating a message flow at a predefined time
+
+
+
+
+ Clearly the Gateway Proxy, MessageChannel.send(..) and MessagePublisher are
+ all belong to the 1st category and Inbound Adapters/Gateways, Scheduler and Poller belong to the 2nd.
+
+
+ So, how do we address transactional needs in various scenarios within each category and is there a need for Spring Integration
+ to provide something explicitly with regard to transaction for a particular scenario or Spring's Transaction Support could be leveraged instead?.
+
+
+
+ First of all, the first and obvious goal is NOT to re-invent something that has already been invented unless you can provide a beter solution.
+ In our case Spring itself provides a first class support for transaction management. So our goal here is not to provide something new but rather
+ delegate/use Spring to benefit from the existing support for transactions. In other words as a framework we must expose hooks to the Transaction management functionality
+ provided by Spring. But since Spring Integration configuration is based on Spring Configuration it is not always neccessery to expose these hooks as they already
+ expposed via Spring natively. Remeber every Spring Integration component is a Spring Bean after all.
+
+
+ With this goal in mind let's look at the two scenarios.
+
+
+ If you think about it, Message flows that are initiated by the USER process (Category 1) and obviously configured in Spring Application Context,
+ are subject to transactional configuration of such process and therefore don't need to be explicitly configured by Spring Integration to support transactions.
+ The transaction could and should be initiated by such process through standard Transaction support provided by Spring and Spring Integration message flow will honor
+ transactional semantics of the components naturally because it is Spring configured. For example; A Gateway or ServiceActivator methods could
+ be annotated with @Transactional or TransactionInterceptor could be configured in XML configuration
+ with point-cut expression pointing to specific methods that should be transactional.
+ The bottom line you have full control over transaction configuration and boundaries in these scenarios.
+
+
+
+ However, things are a bit different when it comes to Message flows initiated by the DAEMON process (Category 2).
+ Although configured by the developer these flows do not directly involve human or some other process to be initiated. These are trigger-based flows
+ that are initiated by a trigger process (DAEMON process) based on the configuration of such process. For example, we could have a Scheduler
+ initiating a message flow every Friday night of every week. We can also configure a trigger that initiates a Message flow every second, etc.
+ So, we obviously need the same way to let these trigger-based processes know of our intention to make these Message flows transactional so
+ Transaction context could be created whenever a new Message flow is initiated. In other words we need to expose some Transaction configuration, but ONLY enough
+ to delegate to Transaction support already provided by Spring (as we do in other scenarios).
+
+
+
+ Spring Integration provides transactional support for Pollers. Pollers are a special case comoponents becouse
+ we can call receive() within that poller task against a resource that is itself transactional thus including receive()
+ call in the the boundaries of the Transaction allowing it to be rolled back in case of a task failure. If we were to add the same support
+ for channels, the added transactions would affect all downstream components starting with that send() call. That is
+ providing a rather wide scope for transaction demarcation without any strong reason especially when Spring already provides several way to
+ address transactional needs of any component downstream. However the receive() method being included in a transaction
+ boundary is the "strong reason" for pollers.
+
+
+
+
+
+ Poller Transaction Support
+
+ Any time you configure a Poller you can provide transactional configuration via transactional element and its attributes:
+
+
+]]>
+ As you can see this configuration looks evry similar to native Spring transaction configuration. You must still provide reference to Transaction manager and specify
+ transaction attributes or rely on defauls (e.g., if 'transaction-manager'' attribute is not specified then it will default to the bean with the name 'transactionManager').
+ Internally the process would be wrapped in the Spring's native Transaction where TransactionInterceptor is responsible to handle transactions.
+ For more information on how to configure Transaction Manager, the types of Transaction Managers (e.g., JTA, Datasource etc.) and other details related to
+ transaction configuration please refer to Spring's Reference manual (Chapter 10 - Transaction Management).
+
+
+ With the above configuration all Message flows initiated by this poller will be transactional. For more information and details on
+ Poller's transactional configuration please refer to section - 21.1.1. Polling and Transactions.
+
+
+
+ There times when besides transaction several more cross cutting concerns needs to be addressed when running Poller. To help with that,
+ Poller element defines <advice-chain> sub-element which allows you to define a custom chain of Advices
+ to be applied on the Poller. (see section 4.4 for more details)
+ In Spring Integration 2.0 Poller went through the major refactoring effort and is now using proxy mechanism to address transactional
+ concerns as well as other cross cutting concerns, one of the significant changes evolving from this effort is that we
+ made <transactional> and <advice-chain> elements mutually exclusive.
+ The rational behind this is; If you need more then one advice, and one of them is Transaction advice, then you can simply
+ include it in the <advice-chain> with the same convenience as before but with much more control
+ since you now have an option to position any advice in the desired order.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+As yo can see from the example above, we have provided a very basic XML-based configuration of Spring Transaction advice - "txAdvice" and
+included it within the <advice-chain> defined by the Poller.
+
+And if you only need to address transactional concerns of the Poller, then you can still use <transactional> element
+as a convinience.
+
+
+
+
+ Transaction Boundaries
+
+ Another important factor that needs to be understood is the boundaries of the Transactions within the Message flow.
+ When transaction is started, transaction context is bound to the current thread. So regardless of how many endpoints and channels you have in your
+ Message flow you transaction context will be preserved as long as you are ensuring that the flow continues on the same thread.
+ As soon as you break it by introducing a Pollable Channel or Executor Channel or initiate a new thread manually in some
+ service, the Transactional boundary will be broken as well. Essentially the Transaction will END right there and if
+ successfull hand of happened between the threads, the flow would be considered a success and COMMIT signal would be sent
+ even though the flow might still result in the exception somewhere downstream. If such flow was synchronous the exception would be thrown back to the
+ initiator of the Message flow who is also the initiator of the transactional context and transaction would result in a ROLLBACK.
+
+
+
diff --git a/docs/src/reference/docbook/transformer.xml b/docs/src/reference/docbook/transformer.xml
new file mode 100644
index 0000000000..42014c7e67
--- /dev/null
+++ b/docs/src/reference/docbook/transformer.xml
@@ -0,0 +1,183 @@
+
+
+ Transformer
+
+
+ Introduction
+
+ Message Transformers play a very important role in enabling the loose-coupling of Message Producers and Message
+ Consumers. Rather than requiring every Message-producing component to know what type is expected by the next
+ consumer, Transformers can be added between those components. Generic transformers, such as one that converts a
+ String to an XML Document, are also highly reusable.
+
+
+ For some systems, it may be best to provide a
+ Canonical Data Model, but Spring
+ Integration's general philosophy is not to require any particular format. Rather, for maximum flexibility, Spring
+ Integration aims to provide the simplest possible model for extension. As with the other endpoint types, the use
+ of declarative configuration in XML and/or Annotations enables simple POJOs to be adapted for the role of Message
+ Transformers. These configuration options will be described below.
+
+ 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
+ .
+
+
+
+
+
+ The <transformer> Element
+
+ The <transformer> element is used to create a Message-transforming endpoint. In addition to "input-channel"
+ and "output-channel" attributes, it requires a "ref". The "ref" may either point to an Object that contains the
+ @Transformer annotation on a single method (see below) or it may be combined with an explicit method name value
+ provided via the "method" attribute.
+
+]]>
+
+
+ Using a "ref" attribute is generally recommended if the custom transformer handler implementation can be reused in
+ other <transformer> definitions. However if the custom transformer handler implementation should
+ be scoped to a single definition of the <transformer>, you can define an inner bean definition:
+
+
+]]>
+
+
+
+ Using both the "ref" attribute and an inner handler definition in the same <transformer>
+ configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown.
+
+
+
+ The method that is used for transformation may expect either the Message type or
+ the payload type of inbound Messages. It may also accept Message header values either individually or as a full
+ map by using the @Header and @Headers parameter annotations respectively. The return value of the method can be
+ any type. If the return value is itself a Message, that will be passed along to
+ the transformer's output channel. If the return type is a Map, and the original Message payload was
+ not 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 null, 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.
+
+
+ There are a also a few Transformer implementations available out of the box. Because, it is fairly common
+ to use the toString() representation of an Object, Spring Integration provides an
+ ObjectToStringTransformer whose output is a Message with a String payload. That String
+ is the result of invoking the toString operation on the inbound Message's payload.
+ ]]>
+ A potential example for this would be sending some arbitrary object to the 'outbound-channel-adapter' in the
+ file namespace. Whereas that Channel Adapter only supports String, byte-array, or
+ java.io.File payloads by default, adding this transformer immediately before the
+ adapter will handle the necessary conversion. Of course, that works fine as long as the result of the
+ toString() call is what you want to be written to the File. Otherwise, you can
+ just provide a custom POJO-based Transformer via the generic 'transformer' element shown previously.
+
+ When debugging, this transformer is not typically necessary since the 'logging-channel-adapter' is capable
+ of logging the Message payload. Refer to for more detail.
+
+
+
+ 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.
+
+
+ ]]>
+
+
+ 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.
+
+
+ ]]>
+
+
+ As added convenience, Spring Integration also provides Object-to-Map and Map-to-Object transformers which
+ utilize Spring Expression Language (SpEL) to serialize and de-serialize the object graphs. Object hierarchy is introspected
+ to the most primitive types (e.g., String, int etc.). The path to this type is described via SpEL, which becomes the keykey in the
+ transformed Map with primitive type being the value.
+
+
+ For example:
+ nickNames;
+ // setters and getters are omitted
+}]]>
+... will be transformed to a Map which looks like this:
+{person.name=George, person.child.name=Jenna, person.child.nickNames[0]=Bimbo . . . etc}
+
+
+ SpEL-based Map allows you to describe the object structure without sharing the actual types allowing
+ you to restore/rebuild the object graph into a differently typed Object graph as long as you maintain the structure.
+
+
+ For example:
+ The above structure could be easily restored back to the following Object graph via Map-to-Object transformer:
+ nickNames;
+ // setters and getters are omitted
+}]]>
+
+
+ To configure these transformers, Spring Integration provides namespace support
+ Object-to-Map:
+]]>
+ Map-to-Object
+]]>
+ or
+
+
+]]>
+
+
+
+ NOTE: 'ref' and 'type' attributes are mutually exclusive. You can only use either one.
+ Also, if using 'ref' attribute you must point to a 'prototype' scoped bean, otherwise
+ BeanCreationException will be thrown.
+
+
+
+
+ The @Transformer Annotation
+
+ The @Transformer annotation can also be added to methods that expect either the
+ Message type or the message payload type. The return value will be handled in the
+ exact same way as described above in the section describing the <transformer> element.
+ @Transformer
+Order generateOrder(String productId) {
+ return new Order(productId);
+}
+
+
+ Transformer methods may also accept the @Header and @Headers annotations that is documented in
+ @Transformer
+Order generateOrder(String productId, @Header("customerName") String customer) {
+ return new Order(productId, customer);
+}
+
+
+
+
diff --git a/docs/src/reference/docbook/ws.xml b/docs/src/reference/docbook/ws.xml
new file mode 100644
index 0000000000..254bae2b17
--- /dev/null
+++ b/docs/src/reference/docbook/ws.xml
@@ -0,0 +1,134 @@
+
+
+ Web Services Support
+
+
+ Outbound Web Service Gateways
+
+ To invoke a Web Service upon sending a message to a channel, there are two options - both of which build
+ upon the Spring Web Services
+ project: SimpleWebServiceOutboundGateway and
+ MarshallingWebServiceOutboundGateway. The former will accept either a
+ String or javax.xml.transform.Source as the message
+ payload. The latter provides support for any implementation of the Marshaller
+ and Unmarshaller interfaces. Both require a Spring Web Services
+ DestinationProvider for determining the URI of the Web Service to be
+ called. simpleGateway = new SimpleWebServiceOutboundGateway(destinationProvider);
+
+ marshallingGateway = new MarshallingWebServiceOutboundGateway(destinationProvider, marshaller);
+
+
+ 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
+ javadoc for
+ more information about the DestinationProvider strategy.
+
+
+
+ For more detail on the inner workings, see the Spring Web Services reference guide's chapter covering
+ client access
+ as well as the chapter covering
+ Object/XML mapping.
+
+
+
+
+ Inbound Web Service Gateways
+
+ To send a message to a channel upon receiving a Web Service invocation, there are two options again: SimpleWebServiceInboundGateway and
+ MarshallingWebServiceInboundGateway. The former will extract a javax.xml.transform.Source
+ from the WebServiceMessage and set it as the message
+ payload. The latter provides support for implementation of the Marshaller
+ and Unmarshaller interfaces.
+ If the incoming web service message is a SOAP message the SOAP Action header will be added to the headers of the
+ Message that is forwarded onto the request channel.
+
+ simpleGateway = new SimpleWebServiceInboundGateway();
+ simpleGateway.setRequestChannel(forwardOntoThisChannel);
+ simpleGateway.setReplyChannel(listenForResponseHere); //Optional
+
+ marshallingGateway = new MarshallingWebServiceInboundGateway(marshaller);
+ //set request and optionally reply channel
+
+Both gateways implement the Spring Web Services MessageEndpoint
+interface, so they can be configured with a MessageDispatcherServlet
+as per standard Spring Web Services configuration.
+
+
+ For more detail on how to use these components, see the Spring Web Services reference guide's chapter covering
+ creating a Web Service.
+ The chapter covering
+ Object/XML mapping is also applicable again.
+
+
+
+ Web Service Namespace Support
+
+ To configure an outbound Web Service Gateway, use the "outbound-gateway" element from the "ws" namespace:
+ ]]>
+
+ 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.
+
+
+ When invoking a Web Service that returns an empty response after using a String payload
+ for the request Message, no reply Message will be sent by default.
+ 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 do want to receive
+ the empty response as a Message, then provide the 'ignore-empty-responses' attribute with
+ a value of false (this only applies for Strings, because using a
+ Source or Document object simply leads to a NULL response and will therefore
+ never generate a reply Message).
+
+
+ To set up an inbound Web Service Gateway, use the "inbound-gateway":
+ ]]>
+
+ To use Spring OXM Marshallers and/or Unmarshallers, provide bean references. For outbound:
+ ]]>
+ And for inbound:
+ ]]>
+
+
+ Most Marshaller implementations also implement the
+ Unmarshaller interface. When using such a
+ Marshaller, only the "marshaller"
+ attribute is necessary. Even when using a Marshaller,
+ you may also provide a reference for the "request-callback" on the outbound gateways.
+
+
+
+ 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).
+
+
+ For either outbound gateway type, the "message-factory" attribute can also be configured with a reference to any
+ Spring Web Services WebServiceMessageFactory implementation.
+
+
+ For the simple inbound gateway type, the "extract-payload" attribute can be set to false to forward
+ the entire WebServiceMessage instead of just its payload as a
+ Message to the request channel. This might be useful, for example,
+ when a custom Transformer works against the WebServiceMessage directly.
+
+
+
+
diff --git a/docs/src/reference/docbook/xml.xml b/docs/src/reference/docbook/xml.xml
new file mode 100644
index 0000000000..f466fc7014
--- /dev/null
+++ b/docs/src/reference/docbook/xml.xml
@@ -0,0 +1,505 @@
+
+
+ XML Support - Dealing with XML Payloads
+
+
+ Introduction
+
+ 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
+ java.lang.String, org.w3c.dom.Document
+ and javax.xml.transform.Source. It should be noted however that
+ where a DOM representation is required, for example in order to evaluate an XPath expression,
+ the String payload will be converted into the required type and then
+ converted back again to String. Components that require an instance of
+ DocumentBuilder 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 DocumentBuilder should be provided.
+
+
+
+ Transforming xml payloads
+
+ This section will explain the workings of
+ UnmarshallingTransformer,
+ MarshallingTransformer,
+ XsltPayloadTransformer
+ and how to configure them as
+ beans. All of the provided xml transformers extend
+ AbstractTransformer or AbstractPayloadTransformer
+ and therefore implement Transformer. When configuring xml
+ transformers as beans in Spring Integration you would normally configure the transformer
+ in conjunction with either a MessageTransformingChannelInterceptor or a
+ MessageTransformingHandler. 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.
+
+
+ UnmarshallingTransformer allows an xml Source
+ to be unmarshalled using implementations of Spring OXM Unmarshaller.
+ Spring OXM provides several implementations supporting marshalling and unmarshalling using JAXB,
+ Castor and JiBX amongst others. Since the unmarshaller requires an instance of
+ Source where the message payload is not currently an instance of
+ Source, conversion will be attempted. Currently String
+ and org.w3c.dom.Document payloads are supported. Custom conversion to a
+ Source is also supported by injecting an implementation of
+ SourceFactory.
+
+
+
+
+
+
+]]>
+
+
+ The MarshallingTransformer allows an object graph to be converted
+ into xml using a Spring OXM Marshaller. By default the
+ MarshallingTransformer will return a DomResult.
+ However the type of result can be controlled by configuring an alternative ResultFactory
+ such as StringResultFactory. In many cases it will be more convenient to transform
+ the payload into an alternative xml format. To achieve this configure a
+ ResultTransformer. Two implementations are provided, one which converts to
+ String and another which converts to Document.
+
+
+
+
+
+
+
+
+
+]]>
+
+
+ By default, the MarshallingTransformer will pass the payload Object
+ to the Marshaller, but if its boolean "extractPayload" property
+ is set to "false", the entire Message instance will be passed
+ to the Marshaller instead. That may be useful for certain custom
+ implementations of the Marshaller interface, but typically the
+ payload is the appropriate source Object for marshalling when delegating to any of the various
+ out-of-the-box Marshaller implementations.
+
+
+ XsltPayloadTransformer transforms xml payloads using xsl.
+ The transformer requires an instance of either Resource or
+ Templates. Passing in a Templates instance
+ allows for greater configuration of the TransformerFactory used to create
+ the template instance. As in the case of XmlPayloadMarshallingTransformer
+ by default XsltPayloadTransformer will create a message with a
+ Result payload. This can be customised by providing a
+ ResultFactory and/or a ResultTransformer.
+
+
+
+
+
+]]>
+
+
+
+
+ Namespace support for xml transformers
+
+ 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
+ EventDrivenConsumer or PollingConsumer
+ 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.
+
+
+]]>
+ The namespace support for UnmarshallingTransformer 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.
+
+
+
+
+
+ ]]>
+
+
+
+ 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 ResultFactory 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 Result after marshalling.
+
+
+
+
+]]>
+
+
+
+ Namespace support for the XsltPayloadTransformer allows either a resource to be passed in in order to create the
+ Templates instance or alternatively a precreated Templates
+ 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 ResultTransfomer where conversion of the result
+ is required before sending.
+
+]]>
+
+
+ Very often to assist with transformation you may need to have access to Message data (e.g., Message Headers). For example; you may need to get access to certain Message Headers
+ and pass them on as parameters to a transformer (e.g., transformer.setParameter(..)).
+ Spring Integration provides two convenient ways to accomplish this. Just look at the following XML snippet.
+
+
+
+
+]]>
+ If message header names match 1:1 to parameter names, you can simply use xslt-param-headers attribute. There you can also use wildcards for
+ simple pattern matching which supports the following simple pattern styles: "xxx*", "*xxx", "*xxx*" and "xxx*yyy".
+
+
+ You can also configure individual xslt parameters via xslt-param sub element. There you can use expression or value attribute.
+ The expression attribute should be any valid SpEL expression with Message being the root object of the expression evaluation context.
+ The value attribute just like any value in Spring beans allows you to specify simple scalar vallue. YOu can also use property placeholders (e.g., ${some.value})
+ So as you can see, with the expression and value attribute xslt parameters could now be mapped to any accessible part of the Message as well as any literal value.
+
+
+
+
+ Splitting xml messages
+
+ XPathMessageSplitter supports messages with either
+ String or Document payloads.
+ The splitter uses the provided XPath expression to split the payload into a number of
+ nodes. By default this will result in each Node instance
+ becoming the payload of a new message. Where it is preferred that each message be a Document
+ the createDocuments flag can be set. Where a String 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 MessageHandler and should
+ therefore be configured in conjunction with an appropriate endpoint (see the namespace support below
+ for a simpler configuration alternative).
+
+
+
+
+
+
+
+
+
+]]>
+
+
+
+
+
+ Routing xml messages using XPath
+
+ Two Router implementations based on XPath are provided XPathSingleChannelRouter and
+ XPathMultiChannelRouter. 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 Node, Document and
+ String. For other payload types a custom implementation
+ of XmlPayloadConverter can be provided. The router
+ implementations use ChannelResolver to convert the
+ result(s) of the XPath expression to a channel name. By default a
+ BeanFactoryChannelResolver 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 ChannelResolver can
+ be used. Where there is a simple mapping from Xpath result to channel name
+ the provided MapBasedChannelResolver can be used.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+
+
+ Selecting xml messages using XPath
+
+ Two MessageSelector implementations are provided,
+ BooleanTestXPathMessageSelector and StringValueTestXPathMessageSelector.
+ BooleanTestXPathMessageSelector requires an XPathExpression which evaluates to a boolean,
+ for example boolean(/one/two) which will only select messages which have an element named
+ two which is a child of a root element named one. StringValueTestXPathMessageSelector
+ evaluates any XPath expression as a String and compares the result with the provided value.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+
+ Transforming xml messages using XPath
+
+ When it comes to message transformation XPath is a great way to transform Messages that have XML
+ payloads by defining XPath transformers via xpath-transformer element.
+
+
+ Simple XPath transformation
+
+
+ Let's look at the following transformer configuration:
+ ]]>
+
+ . . . and Message
+ message =
+ MessageBuilder.withPayload("").build();]]>
+ After sending this message to the 'inputChannel' the XPath transformer configured above will transform
+ this XML Message to a simple Message with payload of 'John Doe' all based on
+ the simple XPath Expression specified in the xpath-expression attribute.
+
+
+ XPath also has capability to perform simple conversion of extracted elements
+ to a desired type. Valid return types are defined in XPathConstants and follows
+ the conversion rules specified by the XPath.
+
+
+ The following constants are defined by the XPathConstants: BOOLEAN, DOM_OBJECT_MODEL, NODE, NODESET, NUMBER, STRING
+
+
+ You can configure the desired type by simply using evaluation-type
+ attribute of the xpath-transformer element.
+
+
+
+]]>
+
+
+ Node Mappers
+
+
+ If you need to provide custom mapping for the node extracted by the XPath expression simply provide a reference to the
+ implementation of the org.springframework.xml.xpath.NodeMapper - an interface used by
+ XPathOperations implementations for mapping Node objects on a per-node basis. To provide a
+ reference to a NodeMapper simply use node-mapper attribute:
+
+]]>
+. . . and Sample NodeMapper implementation:
+
+
+
+ XML Payload Converter
+
+
+ You can also use implementation of the org.springframework.integration.xml.XmlPayloadConverter to
+ provide more granular transformation:
+
+]]>
+. . . and Sample XmlPayloadConverter implementation:
+")));
+ }
+ catch (Exception e) {
+ throw new IllegalStateException(e);
+ }
+ }
+ //
+ public Document convertToDocument(Object object) {
+ throw new UnsupportedOperationException();
+ }
+}]]>
+
+
+ Combination of SpEL and XPath expressions
+
+
+ You can also combine Spring Expression Language (SpEL) expressions with XPath expression and configure
+ them using expression attribute:
+ ]]>
+ In the above case the overall result of the expression will be the result of the XPathe expression multiplied by 2.
+
+
+
+
+
+ XPath components namespace support
+ 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
+ XPathExpression using the Spring XPathExpressionFactory
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+ XPath splitter namespace support allows the creation of a Message Endpoint with an input channel and output channel.
+
+
+
+
+
+
+
+
+
+]]>
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+]]>
+
+
+
+
diff --git a/docs/src/reference/docbook/xmpp.xml b/docs/src/reference/docbook/xmpp.xml
new file mode 100644
index 0000000000..9576a9fe9c
--- /dev/null
+++ b/docs/src/reference/docbook/xmpp.xml
@@ -0,0 +1,442 @@
+
+
+ XMPP Support
+
+ Spring Integration provides Channel Adapters for XMPP.
+
+
+ Introduction
+
+ Spring Integration provides adapters for sending and receiving both XMPP messages and status changes from other
+ entries in your roster as well as XMPP.
+
+
+ XMPP describes a way for multiple agents to communicate with each other in a distributed system.
+ The canonical use case is to send and receive instant messages, though XMPP can be, and is, used for far more
+ applications.
+ XMPP is used to describe a network of actors. Within that network, actors may address each other directly, as well
+ as broadcast status changes.
+
+
+
+ XMPP provides the messaging fabric that underlies some of the biggest Instant Messaging networks in the world,
+ including Google Talk (GTalk)
+ - which is also available from within GMail - and Facebook Chat.
+ There are many good open-source XMPP servers available. Two popular implementations are
+
+ Openfire
+
+ and
+
+ ejabberd
+
+ .
+
+
+ In XMPP,
+ rosters
+ (the roster corresponds to the notion of a "buddy list" in your typical IM client) are used to manage a list of
+ other agents ("contacts", or "buddies", in an IM client)
+ in the system, calledroster items.
+ The roster item contains - at a minimum - the roster item's JID which is its unique ID on the network.
+ An actor may subscribe to the state changes of another actor in the system. The subscription can be bidirectional,
+ as well.
+ The subscription settings determine whose status updates are broadcast, and to whom.
+ These subscriptions are stored on the XMPP server, and are thus durable.
+
+
+
+
+
+
+ Using The Spring Integration XMPP Namespace
+
+
+ Using the Spring Integration XMPP namespace support is simple.
+
+ Its use is like any other module in the Spring framework: import the XML schema, and use it to define elements.
+
+ A prototypical XMPP-based integration might feature the following header. We won't repeat this in subsequent
+ examples, because it is uninteresting.
+
+
+
+
+
+ ...
+
+
+]]>
+
+
+
+
+
+
+
+ XMPP Connection
+
+ To participate in the network, an actor must connect to an XMPP server. Typically this requires - at a minimum - a
+ user, apassword, ahost, and aport.
+
+ To create an XMPP connection, you may use the XML namespace.
+
+
+ ]]>
+
+
+
+
+ XMPP Messages
+
+ Inbound Message Adapter
+ The Spring Integration adapters support receiving messages from other users in the system. To do this, the
+ adapter "logs in" as a user on your behalf and receives the messages sent to that user. Those messages are then
+ forwarded to your Spring Integration client.
+ The payload of the inbound Spring Integration message may be of the raw type
+ org.jivesoftware.smack.packet.Message, or of the type
+ java.lang.String
+ - which is the type of the raw
+ Message's
+ body
+ property -
+ depending on whether you specify
+ extract-payload
+ on the adapter's configuration or not.
+ Inbound Messages are typically small and are text-oriented. Messages received using the adapter have
+ a pretty standard layout, with known headers (all headers have keys defined on
+ org.springframework.integration.xmpp.XmppHeaders):
+
+
+
+ Header Values
+
+
+
+
+
+
+
+
+ Header Name
+ What It Describes
+
+
+
+
+ XmppHeaders.TYPE
+ The value of the
+ the
+
+ org.jivesoftware.smack.packet.Message.Type
+
+ enum that describes the inbound message. Possible values are:
+ normal,
+ chat,
+ groupchat,
+ headline,
+ error.
+
+
+
+
+ XmppHeaders.CHAT
+ A reference to the
+ org.jivesoftware.smack.Chat
+ class which represents the
+ threaded conversation containing the message.
+
+
+
+
+
+
+
+
+
+
+ This adapter requires a reference to an XMPP Connection. You may
+ use the
+ xmpp-connection
+ element to define one.
+
+ An example might look as follows:
+
+
+
+
+
+
+
+
+
+
+
+ ]]>
+
+
+ ]]>
+
+]]>
+
+
+
+
+ In this example, the message is received from the XMPP adapter and passed to a
+ service-activator
+ component. Here's the declaration of theservice-activator.
+
+
+
+
+
+ Outbound Message Adapter
+
+ You may also send messages to other users on XMPP using the
+ outbound-message-channel-adapter
+ adapter. The is configured like the
+
+ xmpp-message-inbound-channel-adapter. The
+ adapter takes an
+ xmpp-connection
+ reference.
+
+
+ Here is a (necessarily) contrived example solution using the outbound adapter.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+]]>
+
+
+
+
+ The adapter expects as its input - at a minimum - a payload of type java.lang.String, and
+ a header value
+ for
+ XmppHeaders.CHAT_TO_USER
+ that specifies to which the user the payload body should be sent to.
+ To create a message destined for theoutbound-message-channel-adapter, you might use the following
+ Java code:
+
+
+ xmppOutboundMsg = MessageBuilder.withPayload("Hello, world!" )
+ .setHeader(XmppHeaders.CHAT_TO_USER, "userhandle")
+ .build();
+]]>
+
+
+
+ It's easy enough to use Java to update the XmppHeaders.CHAT_TO_USER header, and this has the advantage of dynamically updating the header at runtime in Java code.
+ If, however, the target is more static in nature, you can
+ configure it using the
+ XMPP enricher support. Here is an example using the enricher. The enricher enriches the Spring Integration
+ message
+ to support the header values that the outbound XMPP adapters expect.
+
+
+
+
+
+
+
+]]>
+
+
+
+
+
+ XMPP Presence
+
+
+
+ XMPP also supports broadcasting state. You can use this capability to
+ let people who have you on their roster see your state changes. This happens all the time with your IM clients - you
+ change your away status, and then set an away message, and everybody who has you on their roster sees your icon or username change to reflect this new state, and
+ additionally might see your new "away" message.
+
+
+ If you would like to receive notification, or notify others, of state changes, you can use Spring Integration's "presence" adapters.
+
+
+ The most important data for these adapters resides in the headers. The header keys are enumerated on
+ the org.springframework.integration.xmpp.XmppHeaders class.
+
+ The header keys specific to these "presence" adapters start with the token "PRESENCE_".
+
+ Not all headers are available for both inbound and outbound.
+
+
+ Header Values
+
+
+
+
+
+
+
+
+ Header Name
+ What It Describes
+
+
+
+
+
+
+ XmppHeaders.PRESENCE_LANGUAGE
+ The java.lang.String language in which the message was written.
+
+
+
+ XmppHeaders.PRESENCE_PRIORITY
+
+ The priority (int) of the message. Arbitrary, but it can be used to help assign relevance to a message which
+ in turn might be used in its handling.
+
+
+
+ XmppHeaders.PRESENCE_MODE
+
+ An instance of the enum org.jivesoftware.smack.packet.Presence.Mode that has one of the following values:
+ chat,available,away,
+ xa,dnd
+
+
+
+ XmppHeaders.PRESENCE_TYPE
+
+ An instance of the enum org.jivesoftware.smack.packet.Presence.Type
+ that has one of the following values:
+ available,unavailable,subscribe,subscribed,
+ unsubscribe,unsubscribed, and error.
+
+
+
+
+ XmppHeaders.PRESENCE_STATUS
+
+ A java.lang.String string representing the status of the agent. This corresponds to an agents "away" message.
+
+
+
+ XmppHeaders.PRESENCE_FROM
+
+ A java.lang.String string representing the handle of the user whose state is being received.
+
+
+
+
+
+
+
+
- 
-