diff --git a/spring-integration-reference/src/channel-adapter.xml b/spring-integration-reference/src/channel-adapter.xml new file mode 100644 index 0000000000..bd1d22e334 --- /dev/null +++ b/spring-integration-reference/src/channel-adapter.xml @@ -0,0 +1,59 @@ + + + + Channel Adapters + + Channel Adapters are Message Endpoints that enable connecting a single sender or receiver to a Message Channel. + Spring Integration provides a number of adapters out of the box to support various transports, such as JMS, File, + etc. Those will be discussed in upcoming chapters of this reference guide. However, this chapter focuses on the + simple but flexible Method-invoking Channel Adapter support. There is an inbound and outbound adapter, and each + may be configured with XML elements provided in the core namespace. + + +
+ The <inbound-channel-adapter> element + + An "inbound-channel-adapter" element can invoke any method on a Spring-managed Object and send a non-null return + value to a MessageChannel after converting it to a Message. + When the adapter's subscription is activated, a poller will attempt to receive messages from the source. The + poller will be scheduled with the TaskScheduler according to the provided + configuration. To configure the polling 'interval' or 'cronExpression' for an individual channel-adapter's + schedule, provide a 'poller' element with either an 'interval-trigger' (in milliseconds) or 'cron-trigger' + sub-element: + + + + + + + + + + +]]> + +
+ +
+ The <outbound-channel-adapter/> element + + An "outbound-channel-adapter" element can also connect a MessageChannel to any + method that should be invoked with the payload of any Message sent to that channel. + ]]> + If the channel being adapted is a PollableChannel, provide a poller sub-element: + + ]]> + + ]]>]]> + + + Any Channel Adapter can be created without a "channel" reference in which case it will implicitly create an + instance of DirectChannel. The created channel's name will match the "id" attribute + of the <inbound-channel-adapter/> or <outbound-channel-adapter>l; element. Therefore, if the "channel" + is not provided, the "id" is required. + +
+ + \ No newline at end of file diff --git a/spring-integration-reference/src/namespaces.xml b/spring-integration-reference/src/namespaces.xml index 1b66bf8ff9..aef70d3b46 100644 --- a/spring-integration-reference/src/namespaces.xml +++ b/spring-integration-reference/src/namespaces.xml @@ -84,197 +84,47 @@ main thing to recognize is the consistency of the naming for each namespace URI and schema location. -
- Configuring Message Endpoints - - Each of the endpoint types (channel-adapter, service-activator, etc) has its own element in the namespace. - -
- The inbound <channel-adapter/> element with a MessageSource - - 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 and if necessary create a poller for the endpoint. - The Message Bus delegates to a TaskScheduler for scheduling the poller based - on its schedule. To configure the polling 'period' or 'cronExpression' for an individual channel-adapter's - schedule, provide a 'poller' sub-element with the 'period' (in milliseconds) or 'cron' attribute: - - - - - - -]]> - -
-
- The outbound <channel-adapter/> with a MessageTarget - - A "channel-adapter" element can also connect a MessageChannel to any implementation - of the MessageTarget interface. - ]]> - Again, it is possible to provide a poller: - - ]]>]]>]]> - -
-
- The <service-activator/> element - - To create a Service Activator, use the 'service-activator' element with the 'input-channel' and - 'ref' attributes: - <service-activator input-channel="exampleChannel" ref="exampleHandler"/> - - - The configuration above assumes that "exampleHandler" either contains a single method annotated with the - @ServiceActivator annotation or that it contains a single public method period. To delegate to an explicitlye - defined method of any object, simply add the "method" attribute. - <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 the NEXT_TARGET header contains - a non-null value, next it will check if an "output-channel" was provided in the endpoint configuration: - <service-activator input-channel="exampleChannel" output-channel="replyChannel" - ref="somePojo" method="someMethod"/> - If no "output-channel" is available, it will finally check the message header's RETURN_ADDRESS - property. If that value is available, it will then check its type. If it is a MessageTarget, - the reply message will be sent to that target. If it is a String, then the endpoint will - attempt to resolve the channel by performing a lookup in the ChannelRegistry. - If the target cannot be resolved, then a MessageHandlingException will be thrown. - -
- - Message Endpoints also support MessageSelectors. To configure a selector with - namespace support, simply add the "selector" attribute to the endpoint definition and reference an - implementation of the MessageSelector interface. - ]]> - - - Spring Integration also provides transaction support for the pollers so that each receive-and-forward - operation can be performed as an atomic unit-of-work. To configure transactions for a poller, simply - add the <transactional/> sub-element. The attributes for this element should be familiar to anyone - who has experience with Spring's Transaction management: - - - - -]]> - - - Spring Integration also provides support for executing the pollers with a - TaskExceutor. This enables concurrency for an endpoint or group of - endpoints. As a convenience, there is also namespace support for creating a simple thread pool executor. - The <pool-executor/> element defines attributes for common concurrency settings such as core-size, - max-size, and queue-capacity. Configuring a thread-pooling executor can make a substantial difference in - how the endpoint performs under load. These settings are available per-endpoint since the performance - characteristics of an endpoint's handler or 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 'task-executor' reference on its - <poller/> element and then provide one or more of the properties shown below: - - - - -]]> - If no 'task-executor' is provided, the endpoint's handler or target will be invoked in the caller's thread. - Note that the "caller" is usually the MessageBus' task scheduler except in the case of a subscribable channel. - Also, keep in mind that you the 'task-executor' attribute can provide a reference to any implementation of - Spring's TaskExecutor interface. - -
-
- Configuring the Message Bus - - The Message Bus plays a central role, but its configuration is quite simple since it is primarily concerned - with managing internal details based on the configuration of channels and endpoints. The bus is aware of its - host application context, and therefore is also capable of auto-detecting the channels and endpoints. - The Message Bus can be configured with a single empty element: - <message-bus/> - - - The Message Bus provides default error handling for its components in the form of a configurable error channel, - and it will first check for a channel bean named 'errorChannel' within the context: - + Configuring the Message Bus + + The Message Bus plays a central role, but its configuration is quite simple since it is primarily concerned + with managing internal details based on the configuration of channels and endpoints. The bus is aware of its + host application context, and therefore is also capable of auto-detecting the channels and endpoints. + The Message Bus can be configured with a single empty element: + <message-bus/> + + + The Message Bus provides default error handling for its components in the form of a configurable error channel, + and it will first check for a channel bean named 'errorChannel' within the context: + ]]> - When exceptions occur in a scheduled poller task's execution, those exceptions will be wrapped in - ErrorMessages and sent to the 'errorChannel' by default. To enable global error - handling, simply register a handler on that channel. For 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, - the RootCauseErrorMessageRouter is typically a better option. - - - The 'message-bus' element accepts several more optional attributes. First, you can control whether the - MessageBus will be started automatically (the default) or will require explicit startup - by invoking its start() method (MessageBus implements - Spring's Lifecycle interface): - ]]> - - - Another configurable property is the size of the default dispatcher thread pool. The dispatcher threads are - responsible for polling channels and then passing the messages to handlers. - ]]> - When the endpoints are concurrency-enabled as described in the previous section, the invocation of the handling - methods will happen within the handler thread pool and not the dispatcher pool. However, when no task-executor - is provided to an endpoint's poller, then it will be invoked in the dispatcher's thread (with the exception of - subscribable channels). - -
- -
- 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 source, target, gateway, - and handler adapters: - - - -]]> - - - 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. - - - - - -]]> + When exceptions occur in a scheduled poller task's execution, those exceptions will be wrapped in + ErrorMessages and sent to the 'errorChannel' by default. To enable global error + handling, simply register a handler on that channel. For example, you can configure Spring Integration's + ErrorMessageExceptionTypeRouter 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, + the ErrorMessageExceptionTypeRouter is typically a better option. - - - - - - Any Channel Adapter can be created without a "channel" reference in which case it will implicitly create an - instance of DirectChannel. The created channel's name will match the "id" attribute - of the <channel-adapter/> element. Therefore, if the "channel" is not provided, the "id" is required. - -
- - - - + + The 'message-bus' element accepts several more optional attributes. First, you can control whether the + MessageBus will be started automatically (the default) or will require explicit startup + by invoking its start() method (MessageBus implements + Spring's Lifecycle interface): + ]]> + + + Another configurable property is the reference to a TaskScheduler implementation. + If not provided, a default will be created. The scheduler is responsible for managing the pollers. + ]]> + When the endpoints are concurrency-enabled with their own 'taskExecutor' reference, the invocation of the handling + methods will happen within that executor's thread pool and not the main scheduler pool. However, when no + task-executor is provided for an endpoint's poller, then it will be invoked in the dispatcher's thread + (with the exception of subscribable channels where the subscribers may be invoked directly). + +
Annotations diff --git a/spring-integration-reference/src/service-activator.xml b/spring-integration-reference/src/service-activator.xml new file mode 100644 index 0000000000..11f7e5f09a --- /dev/null +++ b/spring-integration-reference/src/service-activator.xml @@ -0,0 +1,45 @@ + + + + Service Activator + +
+ Introduction + + The Service Activator is the endpoint type for connecting any Spring-managed Object to an input channel so that + it may play the role of a service. If the service produces output, it may also be connected to an output channel. + Alternatively, an output producing service may be located at the end of a processing pipeline or message flow in + which case, the inbound Message's "replyChannel" header can be used. This is the default behavior if no output + channel is defined, and as with most of the configuration options you'll see here, the same behavior actually + applies for most of the other components we have seen. + +
+ +
+ The <service-activator/> Element + + To create a Service Activator, use the 'service-activator' element with the 'input-channel' and 'ref' attributes: + <service-activator input-channel="exampleChannel" ref="exampleHandler"/> + + + The configuration above assumes that "exampleHandler" either contains a single method annotated with the + @ServiceActivator annotation or that it contains only one public method at all. To delegate to an explicitly + defined method of any object, simply add the "method" attribute. + <service-activator input-channel="exampleChannel" ref="somePojo" method="someMethod"/> + + + In either case, when the service method returns a non-null value, the endpoint will attempt to send the reply + message to an appropriate reply channel. To determine the reply channel, it will first check if an + "output-channel" was provided in the endpoint configuration: + <service-activator input-channel="exampleChannel" output-channel="replyChannel" + ref="somePojo" method="someMethod"/> + If no "output-channel" is available, it will then check the Message's RETURN_ADDRESS header + value. If that value is available, it will then check its type. If it is a + MessageChannel, the reply message will be sent to that channel. If it is a + String, then the endpoint will attempt to resolve the channel name to a channel instance. + If the channel cannot be resolved, then a ChannelResolutionException will be thrown. + +
+ + \ No newline at end of file diff --git a/spring-integration-reference/src/spring-integration-reference.xml b/spring-integration-reference/src/spring-integration-reference.xml index ff76591092..6bcdc3161a 100644 --- a/spring-integration-reference/src/spring-integration-reference.xml +++ b/spring-integration-reference/src/spring-integration-reference.xml @@ -44,6 +44,8 @@ + +