diff --git a/docs/src/reference/docbook/aggregator.xml b/docs/src/reference/docbook/aggregator.xml index 014e4062bc..6d7d3b7ad7 100644 --- a/docs/src/reference/docbook/aggregator.xml +++ b/docs/src/reference/docbook/aggregator.xml @@ -8,13 +8,13 @@ Basically a mirror-image of the Splitter, the Aggregator is a type of Message Handler that receives multiple Messages and combines them into - a single Message. In fact, Aggregators are often downstream consumers in a + a single Message. In fact, an Aggregator is often a downstream consumer 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. In order to do - this it requires a MessageStore + it is stateful as it must hold the Messages to be aggregated and determine + when the complete group of Messages is ready to be aggregated. In order to do + this it requires a MessageStore.
@@ -23,24 +23,24 @@ The Aggregator combines a group of related messages, by correlating and storing them, until the group is deemed complete. At that point, the Aggregator will create a single message by processing the whole group, and - will send that aggregated message as output. + will send the aggregated message as output. - An main aspect of implementing an Aggregator is providing the logic - that has to be executed when the aggregation (creation of a single message - out of many) takes place. The other two aspects are correlation and + Implementing an Aggregator requires providing the logic + to perform the aggregation (i.e., the creation of a single message + from many). Two related concepts are correlation and release - In Spring Integration, the grouping of the messages for aggregation - (correlation) is done by default based on their CORRELATION_ID message - header (i.e. the messages with the same CORRELATION_ID will be grouped - together). However, this can be customized, and the users can opt for - other ways of specifying how the messages should be grouped together, by - using a CorrelationStrategy (see below). + Correlation determines how messages are grouped for aggregation. + In Spring Integration correlation is done by default based on the CORRELATION_ID message + header. Messages with the same CORRELATION_ID will be grouped + together. However, the correlation strategy may be customized to allow + other ways of specifying how the messages should be grouped together by + implementing a CorrelationStrategy (see below). - To determine whether or not a group of messages may be processed, a - ReleaseStrategy is consulted. The default release strategy for aggregator - will release groups that have all messages from the sequence, but this can - be entirely customized + To determine the state in which a group of messages may be processed, a + ReleaseStrategy is consulted. + The default release strategy for Aggregator will release groups when all + messages included in the sequence are present but this may be customized.
@@ -50,20 +50,20 @@ - The interface MessageGroupProcessor and related - base class AbstractAggregatingMessageGroupProcessor and + The interface MessageGroupProcessor and related + base class AbstractAggregatingMessageGroupProcessor and its subclass - MethodInvokingAggregatingMessageGroupProcessor + MethodInvokingAggregatingMessageGroupProcessor - The ReleaseStrategy interface and its default - implementation SequenceSizeReleaseStrategy + The ReleaseStrategy interface and its default + implementation SequenceSizeReleaseStrategy - The CorrelationStrategy interface and its default - implementation HeaderAttributeCorrelationStrategy + The CorrelationStrategy interface and its default + implementation HeaderAttributeCorrelationStrategy @@ -74,8 +74,8 @@ - The CorrelatingMessageHandler is a - MessageHandler implementation, encapsulating the common + The CorrelatingMessageHandler is a + MessageHandler implementation, encapsulating the common functionalities of an Aggregator (and other correlating use cases), which are: @@ -83,33 +83,32 @@ - maintaining those messages in a MessageStore until the group - may be released + maintaining those messages in a MessageStore until the group + can be released - deciding when the group is in fact may be released + deciding when the group can be released - processing the released group into a single aggregated - message + aggregating the released group into a single message recognizing and responding to an expired group The responsibility of deciding how the messages should - be grouped together is delegated to a CorrelationStrategy + be grouped together is delegated to a CorrelationStrategy instance. The responsibility of deciding whether the message group can - be released is delegated to a ReleaseStrategy + be released is delegated to a ReleaseStrategy instance. Here is a brief highlight of the base - AbstractAggregatingMessageGroupProcessor (the - responsibility of implementing the aggregateMessages method is left to + AbstractAggregatingMessageGroupProcessor (the + responsibility of implementing the aggregateMessages method is left to the developer): @@ -125,74 +124,72 @@ }]]> - The CorrelationStrategy is owned by the + The CorrelationStrategy is owned by the - CorrelatingMessageHandler + CorrelatingMessageHandler - and it has a default value based on the correlation ID message header: + and it has a default value based on the CORRELATION_ID message header: - + When appropriate, the simplest option is the - DefaultAggregatingMessageGroupProcessor. It creates a + DefaultAggregatingMessageGroupProcessor. It creates a single Message whose payload is a List of the payloads received for a - given group. It uses the default CorrelationStrategy and - CompletionStrategy as shown above. This works well for - simple Scatter Gather implementations with either a Splitter, Publish + given group. This works well for simple Scatter Gather implementations with either a Splitter, Publish Subscribe Channel, or Recipient List Router upstream. - - When using a Publish Subscribe Channel or Recipient List Router in this type of scenario, be sure to enable the flag to - apply-sequence. That will add the necessary - headers (correlation id, sequence number and sequence size). That + apply-sequence. That will add the necessary + headers (CORRELATION_ID, SEQUENCE_NUMBER and SEQUENCE_SIZE). That behavior is enabled by default for Splitters in Spring Integration, but it is not enabled for the Publish Subscribe Channel or Recipient List Router because those components may be used in a variety of - contexts where those headers are not necessary. + contexts in which these headers are not necessary. When implementing a specific aggregator object for an application, a developer can extend - AbstractAggregatingMessageGroupProcessor and implement the - aggregatePayloads method. However, there are better suited - (which reads, less coupled to the API) solutions for implementing the - aggregation logic, which can be configured easily either through XML or - through annotations. - - - - In general, any ordinary Java class (i.e. POJO) can implement the - aggregation algorithm. For doing so, it must provide a method that - accepts as an argument a single java.util.List (parametrized lists are - supported as well). This method will be invoked for aggregating - messages, as follows: - - + AbstractAggregatingMessageGroupProcessor and implement the + aggregatePayloads method. However, there are better solutions, less + coupled to the API, for implementing the aggregation logic which can be configured easily + either through XML or through annotations. + + In general, any POJO can implement the + aggregation algorithm if it provide a method that + accepts a single java.util.List as an argument + (parametrized lists are supported as well). This method will be invoked for aggregating + messages as follows: - if the argument is a parametrized java.util.List, and the - parameter type is assignable to Message, then the whole list of - messages accumulated for aggregation will be sent to the - aggregator + if the argument is a java.util.List<T>, and the + parameter type T is assignable to Message, then the whole list of + messages accumulated for aggregation will be sent to the aggregator - if the argument is a non-parametrized java.util.List or the - parameter type is not assignable to Message, then the method will + if the argument is a non-parametrized java.util.List or the + parameter type is not assignable to Message, then the method will receive the payloads of the accumulated messages - if the return type is not assignable to Message, then it will + if the return type is not assignable to Message, then it will be treated as the payload for a Message that will be created automatically by the framework. @@ -204,7 +201,7 @@ In the interest of code simplicity, and promoting best practices such as low coupling, testability, etc., the preferred way of implementing the aggregation logic is through a POJO, and using the - XML or annotation support for setting it up in the application. + XML or annotation support for configuring it in the application. @@ -213,7 +210,7 @@
ReleaseStrategy - The ReleaseStrategy interface is defined as + The ReleaseStrategy interface is defined as follows: - In general, any ordinary Java class (i.e. POJO) can implement the - completion decision mechanism. For doing so, it must provide a method - that accepts as an argument a single java.util.List (parametrized lists + In general, any POJO can implement the + completion decision logic if provide a method + that a single java.util.List as an argument (parametrized lists are supported as well), and returns a boolean value. This method will be invoked after the arrival of a new message, to decide whether the group is complete or not, as follows: - if the argument is a parametrized java.util.List, and the - parameter type is assignable to Message, then the whole list of + if the argument is a java.util.List<T>, and the + parameter type T is assignable to Message, then the whole list of messages accumulated in the group will be sent to the method - if the argument is a non-parametrized java.util.List or the - parameter type is not assignable to Message, then the method will + if the argument is a non-parametrized java.util.List or the + parameter type is not assignable to Message, then the method will receive the payloads of the accumulated messages @@ -253,14 +250,14 @@ again. If the group is also complete (i.e. if all messages from a sequence have arrived or if there is no sequence defined) then the group is removed from the message store. Partial sequences can be released, in - which case the next time the ReleaseStrategy is called it + which case the next time the ReleaseStrategy is called it will be presented with a group containing marked messages (already processed) and unmarked messages (a potential new partial sequence) Spring Integration provides an out-of-the box implementation for - ReleaseStrategy, the - SequenceSizeReleaseStrategy. This implementation uses the + ReleaseStrategy, the + SequenceSizeReleaseStrategy. This implementation uses the SEQUENCE_NUMBER and SEQUENCE_SIZE of the arriving messages for deciding when a message group is complete and ready to be aggregated. As shown above, it is also the default strategy. @@ -269,7 +266,7 @@
CorrelationStrategy - The CorrelationStrategy interface is defined as + The CorrelationStrategy interface is defined as follows: - The method shall return an Object which represents the correlation + The method returns an Object which represents the correlation key used for grouping messages together. The key must satisfy the criteria used for a key in a Map with respect to the implementation of equals() and hashCode(). - In general, any ordinary Java class (i.e. POJO) can implement the - correlation decision mechanism, and the rules for mapping a message to a + In general, any POJO can implement the + correlation logic, and the rules for mapping a message to a method's argument (or arguments) are the same as for a - ServiceActivator (including support for @Header + ServiceActivator (including support for @Header annotations). The method must return a value, and the value must not be null. Spring Integration provides an out-of-the box implementation for - CorrelationStrategy, the - HeaderAttributeCorrelationStrategy. This implementation + CorrelationStrategy, the + HeaderAttributeCorrelationStrategy. This implementation returns the value of one of the message headers (whose name is specified by a constructor argument) as the correlation key. By default, the - correlation strategy is a HeaderAttributeCorrelationStrategy returning + correlation strategy is a HeaderAttributeCorrelationStrategy returning the value of the CORRELATION_ID header attribute.
@@ -350,7 +347,7 @@ The id of the aggregator is - optional. + 0ptional. @@ -359,51 +356,50 @@ - The channel where aggregator will receive messages from + The channel from which where aggregator will receive messages. Required. - The channel where the aggregator will send the aggregation + The channel to which the aggregator will send the aggregation results. Optional (because incoming messages can specify a reply channel themselves via 'replyChannel' Message Header). - The channel where the aggregator will send the messages that + The channel to which the aggregator will send the messages that timed out (if send-partial-results-on-expiry is false). Optional. - A reference to a MessageGroupStore that can be used + A reference to a MessageGroupStore used to store groups of messages under their correlation key until they are - complete. Optional with default a volatile + complete. Optional, by default a volatile in-memory store. - Order of this aggregator in when more then one aggregator is subscribig to the same DirectChannel - (use for load balancing purposes) + Order of this aggregator in when more then one aggregator is subscribing to the same DirectChannel + (use for load balancing purposes). Optional. - Tells if partially aggregated messages should be released when their storage time had expired - (see MessageGroupStore.expireMessageGroups(long)) + Indicates if partially aggregated messages should be released when their storage time has expired + (see MessageGroupStore.expireMessageGroups(long)). Optional. - The timeout for sending the aggregated messages to the output or + The timeout interval for sending the aggregated messages to the output or reply channel. Optional. - - - A reference to a bean that implements the decision algorithm as - to whether a given message group is complete. The bean can be an - implementation of the CorrelationStrategy interface or a POJO. In the - latter case the correlation-strategy-method attribute must be defined + + + A reference to a bean that implements the message correlation (grouping) + algorithm. The bean can be an implementation of the CorrelationStrategy + interface or a POJO. In the latter case the correlation-strategy-method attribute must be defined as well. Optional (by default, the aggregator will use sequence size) . @@ -415,13 +411,12 @@ restrictions (requires correlation-strategy to be present). - + A reference to a bean defined in the application context. The bean must implement the aggregation logic - as described above.Optional (by default the list of aggregated Messages will become a - payload of the output message). + as described above.Optional (by default the list of aggregated Messages will become a + payload of the output message). - A method defined on the bean referenced by ref, that implements the message aggregation @@ -430,7 +425,7 @@ A reference to a bean that implements the release strategy. - The bean can be an implementation of the ReleaseStrategy interface + The bean can be an implementation of the ReleaseStrategy interface or a POJO. In the latter case the release-strategy-method attribute must be defined as well. Optional (by default, the aggregator will use the correlation id header attribute) @@ -447,11 +442,11 @@ - Using a "ref" attribute is generally recommended if a custom - aggregator handler implementation can be reused in other + Using a ref attribute is generally recommended if a custom + aggregator handler implementation my be referenced in other <aggregator> definitions. However if a custom - aggregator handler implementation should be scoped to a concrete - definition of the <aggregator>, you can use an inner + aggregator implementation should be scoped to a single + definition of the <aggregator>, use an inner bean definition (starting with version 1.0.3) for custom aggregator handlers within the <aggregator> element: @@ -459,7 +454,7 @@ ]]> - Using both a "ref" attribute and an inner bean definition in the + Using both a ref attribute and an inner bean definition in the same <aggregator> configuration is not allowed, as it creates an ambiguous condition. In such cases, an Exception will be thrown. @@ -523,8 +518,9 @@ - Since Spring Integration 2.0, the release strategy may be handled with SpEL (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html) - which would be recommend if the logic behind such release strategy is relatively simple. + Since Spring Integration 2.0, the release strategy may be handled with + SpEL + which is recommended if the logic behind such release strategy is relatively simple. Let's say you have a legacy component which was designed to receive an array of objects. We know that default release strategy will assemble all aggregated messages in the List. So now we have two problems. First we need to extract individual messages form such list, extract payload of each message and assemble them into the array of objects (see code below) @@ -544,9 +540,9 @@ output-channel="replyChannel" expression="#this.![payload].toArray()"/>]]> - In the above configuration we are using Collection Projection expression - (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html#d0e12113) to - assemble a new collection from the payloads of all messages in the list and then transforming it to an Array, thus + In the above configuration we are using a Collection Projection expression + to assemble a new collection from the payloads of all messages in the list and then transforming it to an Array, thus achieving the same result as the java code above. @@ -557,7 +553,7 @@ Instead of defining a bean for custom CorrelationStrategy via correlation-strategy attribute you can implement your simple correlation logic via SpEL expression and configure it via - correlation-strategy-ecpression attribute. + correlation-strategy-expression attribute. For example: @@ -568,7 +564,7 @@ which is going to be used to correlate messages. - And when it comes to ReleaseStrategy you can implement your release logic via + And when it comes to ReleaseStrategy you can implement your release logic via SpEL expression as well and configure it via release-strategy-expression attribute. @@ -576,7 +572,7 @@ 5"]]> - In this example the root of SpEL Evaluation Context is MessageGroup and you simply stating + In this example the root of SpEL Evaluation Context is MessageGroup and you simply stating that as soon as there are more then 5 messages in this group release the group.
@@ -649,18 +645,18 @@ stateful pattern that requires decisions to be made based on a group of messages that have arrived over a period of time, all with the same correlation key. The design of the interfaces in the stateful patterns - (e.g. ReleaseStrategy) is driven by the principle + (e.g. ReleaseStrategy) is driven by the principle that the components (framework and user) should be to remain stateless. - All state is carried by the MessageGroup and its + All state is carried by the MessageGroup and its management is delegated to the - MessageGroupStore. + MessageGroupStore. - The MessageGroupStore accumulates state - information in MessageGroups, potentially forever. - So to prevent stale state from hanging around, and for volatile stores to - provide a hook for cleaning up when the application shots down, the - MessageGroupStore allows the user to register - callbacks to apply to MessageGroups when they + The MessageGroupStore accumulates state + information in MessageGroups, potentially forever. + So to prevent stale messages from lingering, and for volatile stores to + provide a hook for cleaning up when the application shuts down, the + MessageGroupStore allows the user to register + callbacks to apply to its MessageGroups when they expire. The interface is very straighforward: - The MessageGroupStore maintains a list of these callbacks which it + The MessageGroupStore maintains a list of these callbacks which it applies when asked to all messages whose timestamp is earlier than a time supplied as a parameter: @@ -682,7 +678,7 @@ int expireMessageGroups(long timeout); }]]> - The expireMessageGroups method can be called with a timeout value: + The expireMessageGroups method can be called with a timeout value: any message older than the current time minus this value will be expired, and have the callbacks applied. Thus it is the user of the store that defines what is meant by message group "expiry". @@ -700,7 +696,7 @@ ]]> - The reaper is a Runnable, and all that is happening is that the + The reaper is a Runnable, and all that is happening is that the message group store's expire method is being called in the sample above once every 10 seconds. In addition to the reaper, the expiry callbacks are invoked when the application shuts down via a lifecycle callback in the diff --git a/docs/src/reference/docbook/chain.xml b/docs/src/reference/docbook/chain.xml index f086446d60..4cbe973206 100644 --- a/docs/src/reference/docbook/chain.xml +++ b/docs/src/reference/docbook/chain.xml @@ -13,11 +13,11 @@ progression. For example, it is fairly common to provide a Transformer before other components. Similarly, when providing a Filter before some other component in a chain, you are essentially creating a Selective Consumer. In either case, the - chain only requires a single input-channel and a single output-channel as opposed to the configuration of - channels for each individual component. + chain only requires a single input-channel and a single output-channel eliminating + the need to define channels for each individual component. - Spring Integration's Filter provides a boolean property 'throwExceptionOnRejection'. When - providing multiple Selective Consumers on the same point-to-point channel with different acceptance criteria, + Spring Integration's Filter provides a boolean property throwExceptionOnRejection. + When providing multiple Selective Consumers on the same point-to-point channel with different acceptance criteria, this value should be set to 'true' (the default is false) so that the dispatcher will know that the Message was rejected and as a result will attempt to pass the Message on to other subscribers. If the Exception were not thrown, then it would appear to the dispatcher as if the Message had been passed on successfully even though @@ -36,7 +36,7 @@ handler only needs an output channel if the outputChannel on the MessageHandlerChain is set. - As with other endpoints, the output-channel is optional. If there is a reply Message at the end of the + As with other endpoints, the output-channel is optional. If there is a reply Message at the end of the chain, the output-channel takes precedence, but if not available, the chain handler will check for a reply channel header on the inbound Message. @@ -52,8 +52,8 @@
Configuring Chain - The <chain> element provides an 'input-channel' attribute, and if the last element in the chain is capable - of producing reply messages (optional), it also supports an 'output-channel' attribute. The sub-elements are then + The <chain> element provides an input-channel attribute, and if the last element in the chain is capable + of producing reply messages (optional), it also supports an output-channel attribute. The sub-elements are then filters, transformers, splitters, and service-activators. The last element may also be a router. @@ -65,15 +65,15 @@ The <header-enricher> element used in the above example will set a message header with name "foo" and - value "bar" on the message. A header enricher is a specialization of Transformer that touches only header - values. You could obtain the same result by implementing a MessageHandler that did the header modifications + value "bar" on the message. A header enricher is a specialization of Transformer + that touches only header values. You could obtain the same result by implementing a MessageHandler that did the header modifications and wiring that as a bean. - Some time you need to make a nested call to another chain from within the chain and then come + Sometimes you need to make a nested call to another chain from within the chain and then come back and continue execution within the original chain. - To accomplish this you can utilize Messaging Gateway by including light-configuration via <gateway> element. + To accomplish this you can utilize Messaging Gateway by including a light configured <gateway> element. For example: @@ -105,9 +105,10 @@ In the above example the nested-chain-a will be called at the end of main-chain processing by the 'gateway' element configured there. While in nested-chain-a a call to a nested-chain-b will be made after header enrichment and then it will come back to finish execution in nested-chain-b finally getting back to the main-chain. -When light version of <gateway> element is defined in the chain SI will construct an instance SimpleMessagingGateway - (no need to provide 'service-interface' configuration) which will take the message in its current state and will place it on the channel defined via 'request-channel' attribute. - Upon processing Message will be returned to the gateway and continue its journey within the current chain. +When the light version of <gateway> element is defined in the chain SI will construct an instance SimpleMessagingGateway + (no need to provide a service-interface attribute) which will take the message in its current state and will place it on the channel defined via + the request-channel attribute. + Upon processing Message will be returned to the gateway and continue its journey within the current chain.
diff --git a/docs/src/reference/docbook/channel.xml b/docs/src/reference/docbook/channel.xml index 4225f81987..cd24f29c24 100644 --- a/docs/src/reference/docbook/channel.xml +++ b/docs/src/reference/docbook/channel.xml @@ -373,12 +373,12 @@ public Message receive(final PollableChannel channel) { ... }]]> Configuring Message Channels - To create a Message Channel instance, you can use the 'channel' element: + To create a Message Channel instance, you can use the <channel/> element: <channel id="exampleChannel"/> The default channel type is Point to Point. To create a - Publish Subscribe channel, use the "publish-subscribe-channel" element: + Publish Subscribe channel, use the <publish-subscribe-channel/> element: <publish-subscribe-channel id="exampleChannel"/> @@ -393,11 +393,11 @@ public Message receive(final PollableChannel channel) { ... }]]>]]> - When using the "channel" element without any sub-elements, it will create a DirectChannel + When using the <channel/> element without any sub-elements, it will create a DirectChannel instance (a SubscribableChannel). - However, you can alternatively provide a variety of "queue" sub-elements to create any of + However, you can alternatively provide a variety of <queue/> sub-elements to create any of the pollable channel types (as described in ). Examples of each are shown below. @@ -425,7 +425,7 @@ public Message receive(final PollableChannel channel) { ... }]]> QueueChannel Configuration - To create a QueueChannel, use the "queue" sub-element. + To create a QueueChannel, use the <queue/> sub-element. You may specify the channel's capacity: <channel id="queueChannel"> <queue capacity="25"/> @@ -440,8 +440,8 @@ public Message receive(final PollableChannel channel) { ... }]]> PublishSubscribeChannel Configuration - To create a PublishSubscribeChannel, use the "publish-subscribe-channel" element. - When using this element, you can also specify the "task-executor" used for publishing + To create a PublishSubscribeChannel, use the <publish-subscribe-channel/> element. + When using this element, you can also specify the task-executor used for publishing Messages (if none is specified it simply publishes in the sender's thread): <publish-subscribe-channel id="pubsubChannel" task-executor="someExecutor"/> If you are providing a Resequencer or Aggregator downstream @@ -452,7 +452,7 @@ public Message receive(final PollableChannel channel) { ... }]]><publish-subscribe-channel id="pubsubChannel" apply-sequence="true"/> - The 'apply-sequence' value is false by default so that a Publish Subscribe Channel + The apply-sequence value is false by default so that a Publish Subscribe Channel can send the exact same Message instances to multiple outbound channels. Since Spring Integration enforces immutability of the payload and header references, the channel creates new Message instances with the same payload reference but different header values when the flag is set to @@ -464,7 +464,7 @@ public Message receive(final PollableChannel channel) { ... }]]>ExecutorChannel To create an ExecutorChannel, add the <dispatcher> sub-element along - with a 'task-executor' attribute. Its value can reference any TaskExecutor + with a task-executor attribute. Its value can reference any TaskExecutor within the context. For example, this enables configuration of a thread-pool for dispatching messages to subscribed handlers. As mentioned above, this does break the "single-threaded" execution context between sender and receiver so that any active transaction context will not be shared by the invocation @@ -475,7 +475,7 @@ public Message receive(final PollableChannel channel) { ... }]]>]]> - The "load-balancer" and "failover" options are also both available on the dispatcher sub-element + The load-balancer and failover options are also both available on the <dispatcher/> sub-element as described above in . The same defaults apply as well. So, the channel will have a round-robin load-balancing strategy with failover enabled unless explicit configuration is provided for one or both of those attributes. @@ -487,14 +487,14 @@ public Message receive(final PollableChannel channel) { ... }]]> PriorityChannel Configuration - To create a PriorityChannel, use the "priority-queue" sub-element: + To create a PriorityChannel, use the <priority-queue/> sub-element: ]]> By default, the channel will consult the MessagePriority header of the message. However, a custom Comparator reference may be provided instead. Also, note that the PriorityChannel (like the other types) - does support the "datatype" attribute. As with the QueueChannel, it also supports a "capacity" attribute. + does support the datatype attribute. As with the QueueChannel, it also supports a capacity attribute. The following example demonstrates all of these: receive(final PollableChannel channel) { ... }]]>Channel Interceptor Configuration Message channels may also have interceptors as described in . The - <interceptors> sub-element can be added within <channel> (or the more specific element - types). Provide the "ref" attribute to reference any Spring-managed object that implements the + <interceptors/> sub-element can be added within <channel/> (or the more specific element + types). Provide the ref attribute to reference any Spring-managed object that implements the ChannelInterceptor interface: ]]> @@ -544,11 +544,11 @@ public Message receive(final PollableChannel channel) { ... }]]> Global Channel Interceptor Configuration - Channel Interceptors allow you for a clean and concise way of applying cross-cutting behavior per individual channel. - But what if the same behavior should be applied on multiple channels, configuring the same set of interceptors for - each channel would not be the most efficient way. The better way would be to configure interceptors globally and apply - them on multiple channels in one shot. Spring Integration provides capabilities to configure Global Interceptors - and apply them on multiple channels. + Channel Interceptors provide a clean and concise way of applying cross-cutting behavior per individual channel. + If the same behavior should be applied on multiple channels, configuring the same set of interceptors for + each channel would not be the most efficient way. To avoid repeated configuration, use global interceptors and apply + them to multiple channels. Spring Integration provides Global Interceptors to accomplish this. + Look at the example below: @@ -557,8 +557,8 @@ public Message receive(final PollableChannel channel) { ... }]]> ]]> - <channel-interceptor> element allows you to define a global interceptor which will be applied on all - channels that match patterns defined via pattern attribute. In the above case the global interceptor will be applied on + <channel-interceptor/> element allows you to define a global interceptor which will be applied on all + channels that match patterns defined via pattern attribute. In the above case the global interceptor will be applied on 'foo' channel and all other channels that begin with 'bar' and 'input'. The order attribute allows you to manage the place where this interceptor will be injected. For example, channel 'inputChannel' could have individual interceptors configured locally (see below): @@ -567,18 +567,19 @@ public Message receive(final PollableChannel channel) { ... }]]>  ]]> - The reasonable question would be how global interceptor will be injected in relation to other interceptors - configured locally or through other global interceptor definitions? Current implementation provides - a very simple and clever mechanism of handling this. Positive number in the order attribute will ensure interceptor injection - after existing interceptors and negative number will ensure that such interceptors injected before. - This means that in the above example global interceptor will be injected AFTER (since its order is greater then 0) - 'wire-tap' interceptor configured locally. If there was another global interceptor with matching pattern their - order would be determined based on who's got the higher or lower value in order attribute. - To inject global interceptor BEFORE the existing interceptors use negative value for the order attribute. + A reasonable question is how will a global interceptor be injected in relation to other interceptors + configured locally or through other global interceptor definitions? The current implementation provides + a very simple and clever mechanism for defining the order of interceptor execution. + A positive number in the order attribute will ensure interceptor injection + after any existing interceptors and negative number will ensure that interceptor is injected before. + This means that in the above example global interceptor will be injected AFTER (since its order is greater then 0) + the 'wire-tap' interceptor configured locally. If there was another global interceptor with matching pattern its + order would be determined by comparing the values of the order attribute. + To inject global interceptor BEFORE the existing interceptors use a negative value for the order attribute. - Note that order and pattern attributes are optional. The default value for order - will be 0 and for pattern is '*' + Note that order and pattern attributes are optional. The default value for order + will be 0 and for pattern is '*' @@ -586,8 +587,8 @@ public Message receive(final PollableChannel channel) { ... }]]>Wire Tap As mentioned above, Spring Integration provides a simple Wire Tap interceptor out of - the box. You can configure a Wire Tap on any channel within an 'interceptors' element. - This is especially useful for debugging, and can be used in conjunction with Spring Integration's logging + the box. You can configure a Wire Tap on any channel within an <interceptors/> element. + This is especially useful for debugging, and can be used in conjunction with Spring Integration's logging Channel Adapter as follows: @@ -596,9 +597,9 @@ public Message receive(final PollableChannel channel) { ... }]]>]]> - The 'logging-channel-adapter' also accepts a boolean attribute: 'log-full-message'. - That is false by default so that only the payload is logged. Setting that to - true enables logging of all headers in addition to the payload. + The 'logging-channel-adapter' also accepts a boolean attribute: log-full-message. + That is false by default so that only the payload is logged. Setting that to + true enables logging of all headers in addition to the payload. diff --git a/docs/src/reference/docbook/filter.xml b/docs/src/reference/docbook/filter.xml index 04020c44e7..60205718b0 100644 --- a/docs/src/reference/docbook/filter.xml +++ b/docs/src/reference/docbook/filter.xml @@ -7,17 +7,17 @@ Introduction Message Filters are used to decide whether a Message should be passed along or dropped based on some criteria - such as a Message Header value or even content within the Message itself. Therefore, a Message Filter is similar + such as a Message Header value or Message content itself. Therefore, a Message Filter is similar to a router, except that for each Message received from the filter's input channel, that same Message may or may not be sent to the filter's output channel. Unlike the router, it makes no decision regarding - which Message Channel to send to but only decides whether to send. + which Message Channel to send the Message to but only decides whether to send. - As you will see momentarily, the Filter does also support a discard channel, so in certain cases it + As you will see momentarily, the Filter also supports a discard channel, so in certain cases it can play the role of a very simple router (or "switch") based on a boolean condition. - In Spring Integration, a Message Filter may be configured as a Message Endpoint that delegates to some + In Spring Integration, a Message Filter may be configured as a Message Endpoint that delegates to an implementation of the MessageSelector interface. That interface is itself quite simple: MessageFilter constructor accepts a selector instance: - In combination with the namespace and SpEL very powerful filters can be configured with very little java code. + In combination with the namespace and SpEL, very powerful filters can be configured with very little java code.
Configuring Filter - The <filter> element is used to create a Message-selecting endpoint. In addition to "input-channel" - and "output-channel" attributes, it requires a "ref". The "ref" may point to a MessageSelector implementation: + The <filter> element is used to create a Message-selecting endpoint. In addition to "input-channel + and output-channel attributes, it requires a ref. The ref may point to a + MessageSelector implementation: ]]> - Alternatively, the "method" attribute can be added at which point the "ref" may refer to any object. + Alternatively, the method attribute can be added at which point the ref may refer to any object. The referenced method may expect either the Message type or the payload type of - inbound Messages. The return value of the method must be a boolean value. Any time the method returns 'true', - the Message will be passed along to the output-channel. + inbound Messages. The method must return a boolean value. If the method returns 'true', + the Message will be sent to the output-channel. @@ -51,25 +52,25 @@ If the selector or adapted POJO method returns false, there are a few settings that control the - fate of the rejected Message. By default (if configured like the example above), the rejected Messages will - be silently dropped. If rejection should instead indicate an error condition, then set the - 'throw-exception-on-rejection' flag to true: + handling of the rejected Message. By default (if configured like the example above), rejected Messages will + be silently dropped. If rejection should instead result in an error condition, then set the + throw-exception-on-rejection attribute to true: ]]> - If you want the rejected messages to go to a specific channel, provide that reference as the 'discard-channel': + If you want rejected messages to be routed to a specific channel, provide that reference as the discard-channel: ]]> - A common usage for Message Filters is in conjunction with a Publish Subscribe Channel. Many filter endpoints may - be subscribed to the same channel, and they decide whether or not to pass the Message for the next endpoint which + Message Filters are commonly used in conjunction with a Publish Subscribe Channel. Many filter endpoints may + be subscribed to the same channel, and they decide whether or not to pass the Message to the next endpoint which could be any of the supported types (e.g. Service Activator). This provides a reactive alternative to the more proactive approach of using a Message Router with a single Point-to-Point input channel and multiple output channels. - Using a "ref" attribute is generally recommended if the custom filter implementation can be reused in other - <filter> definitions. However if the custom filter implementation should be scoped to a + Using a ref attribute is generally recommended if the custom filter implementation is referenced in other + <filter> definitions. However if the custom filter implementation is scoped to a single <filter> element, provide an inner bean definition: @@ -77,15 +78,15 @@ - Using both the "ref" attribute and an inner handler definition in the same <filter> configuration - is not allowed, as it creates an ambiguous condition, and it will therefore result in an Exception being thrown. + Using both the ref attribute and an inner handler definition in the same <filter> configuration + is not allowed, as it creates an ambiguous condition, and an Exception will be thrown. - With the introduction of SpEL Spring Integration has added the expression attribute to the filter + With the introduction of SpEL, Spring Integration added the expression attribute to the filter element. It can be used to avoid Java entirely for simple filters. - ]]> + ]]> The string passed as the expression attribute will be evaluated as a SpEL expression in the context of the message. If it is needed to include the result of an expression in the scope of the application context you can use the @@ -94,7 +95,7 @@ SpEL reference documentation . - ]]> + ]]> If the Expression itself needs to be dynamic, then an 'expression' sub-element may be used. That provides a level of indirection for resolving the Expression by its key from an ExpressionSource. That is a strategy interface that you @@ -102,9 +103,10 @@ a "resource bundle" and can check for modifications after a given number of seconds. All of this is demonstrated in the following configuration sample where the Expression could be reloaded within one minute if the underlying file had been modified. If the ExpressionSource bean is named "expressionSource", then it is not necessary to provide the - "source" attribute on the <expression> element, but in this case it's shown for completeness. + source attribute on the <expression> element, but in this case it's shown for completeness. - + @@ -121,7 +123,7 @@ 100 ]]> - All of the examples that use "expression" as an attribute or sub-element can also be applied within + All of the examples that use expression as an attribute or sub-element can also be applied within transformer, router, splitter, service-activator, and header-enricher elements. Of course, the semantics/role of the given component type would affect the interpretation of the evaluation result in the same way that the return or a method-invocation would be interpreted. For example, an expression can return Strings that are diff --git a/docs/src/reference/docbook/index.xml b/docs/src/reference/docbook/index.xml index 6f28145a8d..bb1ecdddac 100644 --- a/docs/src/reference/docbook/index.xml +++ b/docs/src/reference/docbook/index.xml @@ -53,6 +53,10 @@ Josh Long + + David + Turanski + © SpringSource Inc., 2010 diff --git a/docs/src/reference/docbook/resequencer.xml b/docs/src/reference/docbook/resequencer.xml index 227a0feab4..f5b0502da7 100644 --- a/docs/src/reference/docbook/resequencer.xml +++ b/docs/src/reference/docbook/resequencer.xml @@ -59,12 +59,12 @@ - The channel where the resequencer will send the reordered + The channel to which the resequencer will send the reordered messages. Optional. - The channel where the resequencer will send the messages that + The channel to which the resequencer will send the messages that timed out (if send-partial-result-on-timeout is false). Optional. @@ -76,9 +76,9 @@ available, or only after the whole message group arrives. Optional (false by default). - If this flag is not specified (so a complete sequence is defined by the sequence headers) then it can make sense to provide a custom + If this flag is not specified (so a complete sequence is defined by the sequence headers) then it may make sense to provide a custom - Comparator + Comparator to be used to order the messages when sending (use the XML attribute @@ -94,7 +94,7 @@ (also a reference to another bean definition, either a POJO or a - ReleaseStrategy + ReleaseStrategy ). diff --git a/docs/src/reference/docbook/router.xml b/docs/src/reference/docbook/router.xml index ff6c96cd3b..68768f138a 100644 --- a/docs/src/reference/docbook/router.xml +++ b/docs/src/reference/docbook/router.xml @@ -9,7 +9,7 @@ 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. + out-of-the-box since they fulfill common requirements.
PayloadTypeRouter @@ -29,7 +29,7 @@ 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: + The example below demonstrates a PayloadTypeRouter configuration which is equivalent to the one above using Spring Integration's namespace support: @@ -65,14 +65,12 @@ ]]> - Obviously during the resolution process this router may encounter resolution failures, thus resulting in - exception. If you want to suppress such resolution failures and send all messages to the - default output channel (i.e., identified with default-output-channel attribute) you may do so by setting - ignore-channel-name-resolution-failures to true. This particular attribute may sound confusing when compared with - the default-output-channel. So just to clarify, the default-output-channel handles messages where routing - information can not be determined. However, in the above scenario route has determined successfully but the - resolution of that route failed and that is why we need an extra attribute to let Spring Integration know that it is - OK to suppress resolution failures and treat such route as undetermined thus routing messages to the default-output-channel + During the resolution process this router may encounter channel resolution failures, causing an + exception. If you want to suppress such exceptions and send unresolved messages to the default output channel + (identified with the default-output-channel attribute) set ignore-channel-name-resolution-failures to true. + Normally, messages for which the header value is not explicitly mapped to a channel will be sent to the default-output-channel. + However, in cases where the header value is mapped to a channel name but the channel cannot be resolved, setting ignore-channel-name-resolution-failures + attribute to true will result in routing such messages to the default-output-channel. 2. Configuration where mapping of header values to channel names @@ -82,9 +80,9 @@ - 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 + The two router implementations shown above share some common attributes, such as default-output-channel and resolution-required. + If resolution-required 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 default-output-channel has been specified), then an Exception will be thrown.
@@ -94,7 +92,7 @@
RecipientListRouter - A RecipientListRouter will send each received Message to a statically-defined + A RecipientListRouter will send each received Message to a statically defined list of Message Channels: @@ -108,8 +106,8 @@
- 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: + Spring Integration also provides namespace support for RecipientListRouter configuration (see ) + as the example below demonstrates. ]]> - 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 + The 'apply-sequence' flag here has the same effect 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. - Another convenient option to configure Recipient List Router is to use Spring Expression Language (SpEL) support + Another convenient option to configure RecipientListRouter is to use Spring Expression Language (SpEL) support ]]> - In the above configuration a SpEL expression identified by selector-expression attribute will be evaluated to determine if this recipient + In the above configuration a SpEL expression identified by the selector-expression attribute will be evaluated to determine if this recipient should be included in the recipient list for a given input Message. The evaluation result of the expression must be a boolean. If this attribute is not defined, the channel will always be among the list of recipients. @@ -146,9 +144,9 @@
Configuring Router with XML - 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): + The "router" element provides a simple way to connect a router to an input channel and also accepts the + optional default-output-channel attribute. The ref attribute references the bean name of a custom Router implementation + (extending AbstractMessageRouter): @@ -157,31 +155,31 @@ ]]> - 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 + Alternatively, ref may point to a simple POJO that contains the @Router annotation (see below), or the + ref may be combined with an explicit method name. Specifying a method applies the same behavior described in the @Router annotation section below. ]]> - Using a "ref" attribute is generally recommended if the custom router implementation can be reused in other + Using a ref attribute is generally recommended if the custom router implementation is referenced 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: + single definition of the <router>, you may 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. + 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 an Exception will be thrown. Routers and Spring Expression Language (SpEL) - Some times the routing logic may be simple and writing a separate class for it and configuring it as a bean may seem - like an overkill. Since Spring Integration 2.0 we offer an alternative where you can now use SpEL - (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html) - to implement simple computations that otherwise were implemented in a custom POJO router. + Sometimes the routing logic may be simple and writing a separate class for it and configuring it as a bean may seem + like overkill. Since Spring Integration 2.0 we offer an alternative where you can now use + SpEL + to implement simple computations that previously required a custom POJO router. ]]> In the above configuration the result channel will be computed by the SpEL expression which simply concatenates the value @@ -189,28 +187,28 @@ - Another value of SpEL when it comes to configuring routers is that expression can actually return a Collection, - thus making every <router> a Recipient List Router. Whenever expression returns - multiple channel values Message will be forwarded to all such channels. + Another value of SpEL for configuring routers is that an expression can actually return a Collection, + effectively making every <router> a Recipient List Router. Whenever the expression returns + multiple channel values the Message will be forwarded to each channel. ]]> - In the above configuration lets assume that you have a message header with the name 'channels' and the value being the - List of channel names. Now, message will be sent to all channels in this list. + In the above configuration, if the Message includes a header with the name 'channels' the value of which is a + List of channel names then the Message will be sent to each channel in the list. - You ,ay also fine Collection Projection and Collection Selection - expressions usefull to select multiple channels. - See (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html#d0e12084) + You may also find Collection Projection and Collection Selection + expressions useful to select multiple channels. + See "http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/expressions.html#d0e12084"
Configuring Router with Annotations - 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 + When using @Router to annotate a method, the method may return either a + MessageChannel or String type. In the latter case, + the endpoint will resolve the channel name as it does for the default output channel. Additionally, the method may return + either a single value or a collection. If 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) {...} @@ -225,10 +223,11 @@ public String route(Foo payload) {...} 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 . + In addition to payload-based routing, a Message may be routed based on metadata available within the + message header as either a property or attribute. In this case, a method annotated with @Router + may include a parameter annotated with @Header which is mapped to a header value as illustrated + below and documented in . + @Router public List<String> route(@Header("orderStatus") OrderStatus status) @@ -244,40 +243,38 @@ public List<String> route(@Header("orderStatus") OrderStatus status) Dynamic Routers - So as you can see, Spring Integration provides quite a few different router configurations for most common + So as you can see, Spring Integration provides quite a few different router configurations for 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. + For example PayloadTypeRouter provides a simple way to configure a router which computes channels + based on the payload type of the incoming Message while HeaderValueRouter provides the + same convenience in configuring a router which computes channels by evaluating the value + of a particular Message Header. There are also expression-based (SpEL) routers where the channel + is determined based on evaluating an expression. Thus, these type of routers exhibit some dynamic characteristics. - However these routers share one common attribute - static configuration. Even in the case of + However these routers all require 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. + the same expression operating on the same value will always result in the computation of the same channel. + This is acceptable 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 may be routed to a different channel. - For example: + Example: - You might want to bring down some part of your system for maintenance. So, temporarily you want to re-reroute + You might want to bring down some part of your system for maintenance and temporarily 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). + route to handle a more concrete type of java.lang.Number (in the case of PayloadTypeRouter). - Unfortunately with static router configuration to accomplish this you'd have to bring down your entire application, + Unfortunately with static router configuration to accomplish this you would 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.  + + The Dynamic Router + pattern describes the mechanisms by which one can change/configure routers dynamically without + bringing down the system or individual routers.  - Before we get into the specifics of how it is accomplished in Spring Integration lets quickly summarize the + Before we get into the specifics of how this is accomplished in Spring Integration let's quickly summarize the typical flow of the router, which consists of 3 simple steps: @@ -296,10 +293,10 @@ public List<String> route(@Header("orderStatus") OrderStatus status) - 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. + There is not much that can be done with regard to dynamic routing if Step 1 results in the actual instance of the + MessageChannel simply because the MessageChannel is the final product of any + router's job. However, if Step 1 results in a channel identifier that is not an instance of MessageChannel, + then there are quite a few possibilities to influence the process of deriving the Message Channel. Lets look at couple of the examples in the context of the 3 steps mentioned above:  @@ -325,12 +322,12 @@ public List<String> route(@Header("orderStatus") OrderStatus status) Step 3 - Resolve channel name to the actual instance of the - MessageChannel where using ChannelResolver router will obtain a + MessageChannel where using ChannelResolver, the 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. + In other words each step feeds the next step until the process completes. Header Value Router @@ -355,7 +352,7 @@ public List<String> route(@Header("orderStatus") OrderStatus status) Step 3 - Resolve channel name to the actual instance of the - MessageChannel where using ChannelResolver router will obtain a + MessageChannel where using ChannelResolver, the router will obtain a reference to a bean (which is hopefully a MessageChannel) identified by the result of the previous step. @@ -363,10 +360,10 @@ public List<String> route(@Header("orderStatus") OrderStatus status) 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 + However if we look at the alternate 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? + But the 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 @@ -382,20 +379,20 @@ public List<String> route(@Header("orderStatus") OrderStatus status)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: + there was a 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 + MessageChannel identified by this name. That will be done via a default + ChannelResolver implementation which is a 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 + But what if you want to route these messages to 'simpson' channel? Obviously changing a static configuration will work, + but will also require bringing your system down. However if you had access to the 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 . @@ -405,11 +402,11 @@ public List<String> route(@Header("orderStatus") OrderStatus status)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 + In Spring Integration 2.0 the routers hierarchy underwent major refactoring and now any router that is a subclass of the + AbstractMessageRouter (which includes all framework defined routers) is a Dynamic Router simply because the 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.  + and modifiers exposed as public methods allowing you to change/add/remove router mapping at runtime via JMX (see ) or + the ControlBus (see ) functionality.  @@ -417,28 +414,28 @@ public List<String> route(@Header("orderStatus") OrderStatus status) 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 + pattern which exposes a Control Channel where you can send + control messages to manage and monitor Spring Integration components, including routers. + For more information about the Control Bus see . 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: + specific to changing router resolution process are: - public void setChannelMapping(String channelIdentifier, String channelName) - + 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) - + 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 + For additional managed operations 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/splitter.xml b/docs/src/reference/docbook/splitter.xml index 3f1f568525..3a2851430d 100644 --- a/docs/src/reference/docbook/splitter.xml +++ b/docs/src/reference/docbook/splitter.xml @@ -15,17 +15,20 @@
Programming model - The API for performing splitting consists from one base class, - AbstractMessageSplitter, which is a MessageHandler implementation, + The API for performing splitting consists of 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 + SEQUENCE_NUMBER on the messages that are produced. This enables tracking 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. + example, in a + + Composed Message Processor scenario. - An excerpt from AbstractMessageSplitter can be seen below: + An excerpt from AbstractMessageSplitter can be seen below: public abstract class AbstractMessageSplitter extends AbstractReplyProducingMessageConsumer { @@ -34,15 +37,16 @@ } - 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: + To implement a specific Splitter in an application, + extend AbstractMessageSplitter and implement the splitMessage method, + which contains logic for splitting the messages. The return + value may 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 + 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 @@ -50,17 +54,17 @@ - a Collection (or subclass thereof) or an array of non-Message - objects - works like the prior case, except that each collection + 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. + a Message or non-Message object + (but not a Collection or an Array) - it works like the previous cases, + except a single message will be sent out. @@ -68,9 +72,9 @@ 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 + 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.
@@ -80,7 +84,7 @@
Configuring a Splitter using XML - A splitter can be configured through XML as follows:<channel id="inputChannel"/> + A splitter can be configured through XML as follows:<channel id="inputChannel"/> <splitter id="splitter" ref="splitterBean" @@ -99,10 +103,12 @@ 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. + 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 to the Collection, + incorporating each individual element into a Message and sending it to the output-channel. @@ -118,15 +124,15 @@ - The channel where the splitter will send the results of + The channel to which 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 + Using a ref attribute is generally recommended if the custom splitter implementation may be referenced 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: + single definition of the <splitter>, configure an inner bean definition: @@ -134,7 +140,7 @@ - Using both a "ref" attribute and an inner handler definition in the same <splitter> + 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. @@ -146,10 +152,10 @@ 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 + 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 item will be wrapped in a Message as its payload. Each + message will be sent to the designated output channel for the endpoint on which the @Splitter is defined. @Splitter List<LineItem> extractItems(Order order) { @@ -157,8 +163,4 @@ List<LineItem> extractItems(Order order) { }
- - - - diff --git a/docs/src/reference/docbook/xml.xml b/docs/src/reference/docbook/xml.xml index f466fc7014..b76b34f84c 100644 --- a/docs/src/reference/docbook/xml.xml +++ b/docs/src/reference/docbook/xml.xml @@ -81,8 +81,8 @@ 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, 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 @@ -147,10 +147,10 @@ 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, + 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 + 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. 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 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. ]]> - 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 + 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. + 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. @@ -332,7 +332,7 @@ 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. + payloads by defining XPath transformers via <xpath-transformer/> element. Simple XPath transformation @@ -347,7 +347,7 @@ 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. + the simple XPath Expression specified in the xpath-expression attribute. XPath also has capability to perform simple conversion of extracted elements @@ -358,8 +358,8 @@ 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. + You can configure the desired type by simply using evaluation-type + attribute of the <xpath-transformer/> element. @@ -374,7 +374,7 @@ 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: + reference to a NodeMapper simply use node-mapper attribute: ]]> @@ -420,7 +420,7 @@ You can also combine Spring Expression Language (SpEL) expressions with XPath expression and configure - them using expression attribute: + 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. @@ -432,7 +432,7 @@ 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 + <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 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 + 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.