From 58eda9089b28f7ddb457a09c17c503437653c515 Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Tue, 8 Jul 2008 04:31:11 +0000 Subject: [PATCH] Updated adapters documentation. --- spring-integration-reference/src/adapters.xml | 101 ++++++++++-------- 1 file changed, 55 insertions(+), 46 deletions(-) diff --git a/spring-integration-reference/src/adapters.xml b/spring-integration-reference/src/adapters.xml index a1771f2ed0..e5b7226999 100644 --- a/spring-integration-reference/src/adapters.xml +++ b/spring-integration-reference/src/adapters.xml @@ -6,24 +6,33 @@
Introduction - Spring Integration provides a number of implementations of the Source and - Target interfaces that serve as adapters for interacting with external - systems or components that are not part of the messaging system. Configuring these source and target - implementations within SourceEndpoints and TargetEndpoints - provides an implementation of the Channel Adapter pattern. Essentially, the external - system or component sends-to and/or receives-from a MessageChannel. In the - 1.0 Milestone 4 release, Spring Integration includes source and target implementations for JMS, RMI, - Files, Streams, Spring's HttpInvoker and Spring ApplicationEvents. A source adapter for FTP is - also available as well as target adapters for sending e-mail and invoking Web Services. + Spring Integration provides a number of implementations of the MessageSource + and MessageTarget interfaces that serve as adapters for interacting with + external systems or components that are not part of the messaging system. These source and target + implementations can be configured within the same channel-adapter element that we + have already discussed. Essentially, the external system or component sends-to and/or receives-from a + MessageChannel. In the 1.0 Milestone 5 release, Spring Integration includes + source and target implementations for JMS, Files, Streams, and Spring ApplicationEvents. A source adapter + for FTP is also available. - Adapters that allow the external system to perform request-reply operations across Spring Integration + Adapters that allow an external system to perform request-reply operations across Spring Integration MessageChannels are actually examples of the Messaging Gateway - pattern. Therefore, those implementations are typically called "gateways". For example, Spring Integration - provides a JmsSource that is polled by the bus-managed - scheduler, but it also provides a JmsGateway. The gateway differs from the source in - that it is an event-driven consumer rather than a polling consumer, - and it is capable of waiting for reply messages. + pattern. Therefore, those implementations are typically called "gateways" (whereas "source" and "target" + are in-only and out-only interactions respectively). For example, Spring Integration provides a + JmsSource that is polled by the bus-managed scheduler, but + also provides a JmsGateway. The gateway differs from the source in that it is an + event-driven consumer rather than a polling consumer, + and it is capable of waiting for reply messages. Spring Integration also provides gateways for RMI and + Spring's HttpInvoker. + + + Finally, adapters that enable interaction with external systems by invoking them for + request/reply interactions (the response is sent back on a Message Channel) are typically called + handlers in Spring Integration, since they implement the + MessageHandler interface. Basically, these types of adapters can be + configured exactly like any POJO with the <service-activator> element. Spring Integration provides + RMI, HttpInvoker, and Web Service handler implementations. All of these adapters are discussed in this section. However, namespace support is provided for many of them @@ -44,7 +53,7 @@ The JmsSource requires a reference to either a single JmsTemplate instance or both ConnectionFactory and Destination (a 'destinationName' can be provided in place of the 'destination' reference). The JmsSource - can then be referenced from a SourceEndpoint that connects the source to a + can then be referenced from a "channel-adapter" element that connects the source to a MessageChannel instance. The following example defines a JMS source with a JmsTemplate as a constructor-argument. @@ -77,42 +86,42 @@
RMI Adapters - The RmiSourceAdapter is built upon Spring's RmiServiceExporter. + The RmiGateway is built upon Spring's RmiServiceExporter. However, since it is adapting a MessageChannel, there is no need to specify the serviceInterface. Likewise, the serviceName is automatically generated based on the channel name. Therefore, creating the adapter is as simple as providing a reference - to its channel: RmiSourceAdapter rmiSourceAdapter = new RmiSourceAdapter(channel); + to its channel: RmiGateway rmiGateway = new RmiGateway(channel); - The RmiTargetAdapter encapsulates the creation of a proxy that is capable of - communicating with an RmiSourceAdapter running in another process. Since the interface + The RmiHandler encapsulates the creation of a proxy that is capable of + communicating with an RmiGateway running in another process. Since the interface is already known, the only required information is the URL. The URL should include the host, port (default is '1099'), and 'serviceName'. The 'serviceName' must match that created by the - RmiSourceAdapter (the prefix is available as a constant). - String url = "http://somehost:1099/" + RmiSourceAdapter.SERVICE_NAME_PREFIX + "someChannel"; -RmiTargetAdapter rmiTargetAdapter = new RmiTargetAdapter(url); + RmiGateway (the prefix is available as a constant). + String url = "http://somehost:1099/" + RmiGateway.SERVICE_NAME_PREFIX + "someChannel"; +RmiHandler rmiHandler = new RmiHandler(url);
HttpInvoker Adapters - The source and target adapters for HttpInvoker are very similar to the RMI adapters. For a source, only the + The adapters for HttpInvoker are very similar to the RMI adapters. For a source, only the channel needs to be provided, and for a target, only the URL. If running in a Spring MVC environment, then - the HttpInvokerSourceAdapter simply needs to be defined and provided in a + the HttpInvokerGateway simply needs to be defined and provided in a HandlerMapping. For example, the following would be exposed at the path "http://somehost/path-mapped-to-dispatcher-servlet/httpInvokerAdapter" when a simple BeanNameUrlHandlerMapping strategy is enabled: + class="org.springframework.integration.adapter.httpinvoker.HttpInvokerGateway"> ]]> When not running in a Spring MVC application, simply define a servlet in 'web.xml' whose type is HttpRequestHandlerServlet and whose name matches the bean name of the source - adapter. As with the RmiTargetAdapter, the - HttpInvokerTargetAdapter only requires the URL that matches an instance of - HttpInvokerSourceAdapter running in a web application. + adapter. As with the RmiHandler, the + HttpInvokerHandler only requires the URL that matches an instance of + HttpInvokerGateway running in a web application.
@@ -121,7 +130,7 @@ RmiTargetAdapter rmiTargetAdapter = new RmiTargetAdapter(url); The FileSource requires the directory as a constructor argument: public FileSource(File directory) It can then be connected to a MessageChannel when referenced from - a SourceEndpoint. + a "channel-adapter" element. The FileTarget constructor also requires the 'directory' argument. The target @@ -133,10 +142,10 @@ RmiTargetAdapter rmiTargetAdapter = new RmiTargetAdapter(url); FTP Adapters To poll a directory with FTP, configure an instance of FtpSource and then connect - it to a channel by configuring a SourceEndpoint. The FtpSource + it to a channel by configuring a channel-adapter. The FtpSource expects a number of properties for connecting to the FTP server as shown below. + class="org.springframework.integration.adapter.ftp.FtpSource"> @@ -174,8 +183,8 @@ MailAttributeKeys.REPLY_TO A static implementation is also available out-of-the-box and may be useful for testing. However, when customizing, the properties would typically be generated dynamically based on the message itself. The following is an example of a configured mail adapter. - + ]]> @@ -185,19 +194,19 @@ MailAttributeKeys.REPLY_TO Web Service Adapters To invoke a Web Service upon sending a message to a channel, there are two options: - SimpleWebServiceTargetAdapter and - MarshallingWebServiceTargetAdapter. The former will accept either a + SimpleWebServiceHandler and + MarshallingWebServiceHandler. The former will accept either a String or javax.xml.transform.Source as the message payload. The latter provides support for any implementation of the Marshaller and Unmarshaller interfaces. Both require the URI of the Web Service to be - called.simpleAdapter = new SimpleWebServiceTargetAdapter(uri); + called.simpleHandler = new SimpleWebServiceHandler(uri); -marshallingAdapter = new MarshallingWebServiceTargetAdapter(uri, marshaller); +marshallingHandler = new MarshallingWebServiceHandler(uri, marshaller); - Either adapter can then be referenced from a HandlerEndpoint that is subscribed to a - MessageChannel. The endpoint is then responsible for passing the response to the - proper reply channel. It will first check for an "output-channel" on the endpoint itself and will fallback to a - returnAddress on the original message's header. + Either adapter can then be referenced from a service-activator element + that is subscribed to an input-channel. The endpoint is then responsible for passing the response to the + proper reply channel. It will first check for an "output-channel" on the service-activator and will + fallback to a returnAddress on the original message's header. For more detail on the inner workings, see the Spring Web Services reference guide's chapter covering @@ -211,7 +220,7 @@ marshallingAdapter = new MarshallingWebServiceTargetAdapter(uri, marshaller); Spring Integration also provides adapters for streams. Both ByteStreamSource and CharacterStreamSource implement the Source interface. By - configuring one of these within a SourceEndpoint, the polling period can be configured, + configuring one of these within a channel-adapter element, the polling period can be configured, and the Message Bus can automatically detect and schedule them. The byte stream version requires an InputStream, and the character stream version requires a Reader as the single constructor argument. The ByteStreamSource also accepts the 'bytesPerMessage' @@ -222,8 +231,8 @@ marshallingAdapter = new MarshallingWebServiceTargetAdapter(uri, marshaller); CharacterStreamTarget. Each requires a single constructor argument - OutputStream for byte streams or Writer for character streams, and each provides a second constructor that adds the optional 'bufferSize' property. Since both of these - ultimately implement the Target interface, they can be referenced from a - TargetEndpoint configuration as will be described in more detail in + ultimately implement the MessageTarget interface, they can be referenced from a + channel-adapter configuration as will be described in more detail in .
@@ -233,7 +242,7 @@ marshallingAdapter = new MarshallingWebServiceTargetAdapter(uri, marshaller); Spring ApplicationEvents can also be integrated as either a source or target for Spring Integration message channels. To receive the events and send to a channel, simply define an instance of Spring Integration's ApplicationEventSource (as with all source implementations, this can then - be configured within a SourceEndpoint and automatically detected by the message bus). The + be configured within a "channel-adapter" element and automatically detected by the message bus). The ApplicationEventSource also implements Spring's ApplicationListener interface. By default it will pass all received events as Spring Integration Messages. To limit based on the type of event, configure the list of event types that you want to receive with the 'eventTypes' property.