diff --git a/spring-integration-reference/src/configuration.xml b/spring-integration-reference/src/configuration.xml index 8deab04989..bc6a2902f4 100644 --- a/spring-integration-reference/src/configuration.xml +++ b/spring-integration-reference/src/configuration.xml @@ -67,22 +67,8 @@ The default channel type is Point to Point. To create a - Publish Subscribe channel, provide a value of true for the - 'publish-subscribe' attribute of the channel element: - <channel id="exampleChannel" publish-subscribe="true"/> - - - When the MessageBus detects and registers channels, it will establish a dispatcher for - each channel. The default dispatcher settings were previously displayed in - . To customize these settings for a particular channel, add - the 'dispatcher-policy' sub-element and provide one or more of the attributes shown below: - - -]]> + Publish Subscribe channel, use the "publish-subscribe-channel" element: + <publish-subscribe-channel id="exampleChannel"/> To create a Datatype Channel that only @@ -112,6 +98,15 @@ <queue-channel id="exampleChannel" capacity="25"/> +
+ The <publish-subscribe-channel/> element + + To create a PublishSubscribeChannel, use the "publish-subscribe-channel" element. + By 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="exampleChannel" task-executor="someTaskExecutor"/> + +
The <priority-channel/> element @@ -166,34 +161,33 @@
Configuring Message Endpoints - Each of the three endpoint types (source, target, and handler) has its own element in the namespace. + Each of the endpoint types (channel-adapter, service-activator, etc) has its own element in the namespace. -
- The <source-endpoint/> element +
+ The inbound <channel-adapter/> element with a MessageSource - A SourceEndpoint connects an implementation of the Source - interface to a MessageChannel. The <source-endpoint/> therefore requires - these two references as well as the scheduling information so that the MessageBus can - manage the message-receiving tasks. - + A "channel-adapter" element can connect any implementation of the MessageSource + interface to a MessageChannel. When the MessageBus + registers the endpoint, it will activate the subscription by assigning the endpoint to the input channel's dispatcher. + The dispatcher is capable of handling multiple endpoint subscriptions for its channel and delegates to a scheduler + for managing the tasks that pull messages from the source and push them to the channel. To configure the polling + period for an individual channel-adapter's schedule, provide a 'schedule' sub-element with the 'period' in + milliseconds: + -]]> +]]>
-
- The <target-endpoint/> element +
+ The outbound <channel-adapter/> with a MessageTarget - A TargetEndpoint connects a MessageChannel to an implementation - of the Target interface. The <target-endpoint/> requires these two references. - ]]> - When the MessageBus registers the endpoint, it will activate the subscription - by assigning the endpoint to the input channel's dispatcher. The dispatcher is capable of handling multiple - endpoint subscriptions for its channel and delegates to a scheduler for managing the tasks that pull messages - from the channel and push them to the endpoints. To configure the polling period for an individual endpoint's - schedule, provide a 'schedule' sub-element with the 'period' in milliseconds: - + A "channel-adapter" element can also connect a MessageChannel to any implementation + of the MessageTarget interface. + ]]> + Again, it is possible to provide a schedule: + ]]>]]>]]> +]]> @@ -203,31 +197,27 @@ default schedule, and any 'schedule' element configured for those endpoints will be ignored. - - The <target-endpoint/> accepts additional attributes and child elements, but since these configuration - options are also available for the <handler-endpoint/> element, they will be discussed below. -
-
- The <handler-endpoint/> element +
+ The <service-activator/> element - To create a Handler Endpoint instance, use the 'handler-endpoint' element with the 'input-channel' and - 'handler' attributes: - <handler-endpoint input-channel="exampleChannel" handler="exampleHandler"/> + 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" is an actual implementation of the MessageHandler interface as described in . To delegate to an arbitrary method of any object, simply add the "method" attribute. - <handler-endpoint input-channel="exampleChannel" handler="somePojo" method="someMethod"/> + <service-activator input-channel="exampleChannel" ref="somePojo" method="someMethod"/> In either case (MessageHandler or arbitrary object/method), when the handling 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: - <handler-endpoint input-channel="exampleChannel" output-channel="replyChannel" - handler="somePojo" method="someMethod"/> + <service-activator input-channel="exampleChannel" output-channel="replyChannel" + ref="somePojo" method="someMethod"/> If no "output-channel" is available, it will next check the message header's 'returnAddress' property. 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 @@ -236,36 +226,44 @@ To reverse the order so that the 'returnAddress' is given priority over the endpoint's "output-channel", then provide the "return-address-overrides" attribute with a value of 'true': - <handler-endpoint input-channel="exampleChannel" output-channel="replyChannel" - handler="somePojo" method="someMethod" return-address-overrides="true"/> + <service-activator input-channel="exampleChannel" output-channel="replyChannel" + ref="somePojo" method="someMethod" return-address-overrides="true"/> If neither is available, then a MessageHandlingException will be thrown.
- Handler and Target Endpoints also support MessageSelectors as described in + Message Endpoints also support MessageSelectors as described in . To configure a selector with namespace support, simply add the "selector" attribute to the endpoint definition and reference an implementation of the MessageSelector interface. - ]]> - Another important configuration option for handler and target endpoints is the concurrency policy. Each - endpoint is capable of managing a thread pool for its handler or target, and the values you provide for that - pool's core and max size can make a substantial difference in how the handler or target performs under load. + Another important configuration option for message endpoints is the concurrency interceptor. Each + endpoint is capable of managing a thread pool, and the concurrency settings you provide for that + pool's core and max size can make a substantial difference in how the endpoint performs under load. These settings are available per-endpoint since the performance characteristics of an endpoint's handler or target is one of the major factors to consider (the other major factor being the expected volume on the channel to which the endpoint subscribes). To enable concurrency for an endpoint that is configured with the - XML namespace support, provide the 'concurrency' sub-element and one or more of the properties shown below: - - ]]>]]>]]> + XML namespace support, provide the 'concurrency-interceptor' element within the 'interceptors' sub-element + and then provide one or more of the properties shown below: + + + ]]>]]> +]]> Recall the default concurrency policy values as listed in . If no concurrency settings are provided (i.e. a null ConcurrencyPolicy), the endpoint's handler or target will be invoked in the caller's thread. Note that the "caller" is usually the dispatcher except in the case of a DirectChannel (see for more detail). + + Another option for the concurrency-interceptor is to provide the "task-executor" attribute + with a reference to any implementation of Spring's TaskExecutor + interface. + For the concurrency settings, the default queue capacity of 0 triggers the creation of a @@ -295,11 +293,11 @@ and the 'message-bus' element accepts a reference with its 'error-channel' attribute: -]]> +]]> When exceptions occur in a concurrent endpoint's execution of its MessageHandler callback, those exceptions will be wrapped in ErrorMessages and sent to the Message Bus' 'errorChannel' by default. To enable global error handling, simply register a handler on that channel. For - example, you can configure Spring Integration's PayloadTypeRouter as the handler of + example, you can configure Spring Integration's RootCauseErrorMessageRouter as the handler of an endpoint that is subscribed to the 'errorChannel'. That router can then spread the error messages across multiple channels based on Exception type. However, since most of the errors will already have been wrapped in MessageDeliveryException or MessageHandlingException, @@ -342,7 +340,8 @@ Configuring Adapters The most convenient way to configure Source and Target adapters is by using the namespace support. The - following examples demonstrate the namespace-based configuration of several sources and targets: + following examples demonstrate the namespace-based configuration of several source, target, gateway, + and handler adapters: @@ -352,20 +351,20 @@ - + - + - + - + - + - In the examples above, notice that simple implementations of the Source - and Target interfaces do not accept any 'channel' references. To - connect such sources and targets to a channel, register them within an endpoint. For example, here + In the examples above, notice that simple implementations of the MessageSource + and MessageTarget interfaces do not accept any 'channel' references. To + connect such sources and targets to a channel, register them within a 'channel-adapter'. For example, here is a File source with an endpoint whose polling will be scheduled to execute every 30 seconds by the MessageBus. - + - + ]]> - Likewise, here is an example of a JMS target that is registered with a target-endpoint whose Messages + Likewise, here is an example of a JMS target that is registered within a 'channel-adapter' and whose Messages will be received from the "exampleChannel" that is polled every 500 milliseconds. - + - + ]]>