diff --git a/spring-integration-reference/src/adapters.xml b/spring-integration-reference/src/adapters.xml index a89f63f528..a1771f2ed0 100644 --- a/spring-integration-reference/src/adapters.xml +++ b/spring-integration-reference/src/adapters.xml @@ -6,14 +6,25 @@
Introduction - Channel Adapters are the components responsible for interacting with external systems or other components that - are external to the messaging system. As the name implies, the interaction consists of adapting the external - system or component to send-to and/or receive-from a MessageChannel. Within - Spring Integration, there is a distinction between source adapters and target - adapters. In the 1.0 Milestone 3 release, Spring Integration includes source and target adapters - for JMS, RMI, Files, Streams, Spring's HttpInvoker and Spring ApplicationEvents. A source adapter for FTP is + 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. + + Adapters that allow the 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. + All of these adapters are discussed in this section. However, namespace support is provided for many of them and is typically the most convenient option for configuration. For examples, see @@ -24,48 +35,39 @@
JMS Adapters - Spring Integration provides two adapters for accepting JMS messages: - JmsPollingSourceAdapter and JmsMessageDrivenSourceAdapter. - The former uses Spring's JmsTemplate to receive based on a polling period. The latter - configures and delegates to an instance of Spring's DefaultMessageListenerContainer. + Spring Integration provides two adapters for accepting JMS messages (as mentioned above): + JmsSource and JmsGateway. The former uses Spring's + JmsTemplate to receive based on a polling period. The latter configures and delegates to + an instance of Spring's DefaultMessageListenerContainer. - The JmsPollingSourceAdapter 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 JmsPollingSourceAdapter also requires a 'channel' property that should be - a reference to a MessageChannel instance. The adapter accepts additional - properties such as: period, initialDelay, maxMessagesPerTask, and sendTimeout. The following example defines a - JMS source adapter that polls every 5 seconds and then sends to the "exampleChannel": - + 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 + MessageChannel instance. The following example defines a JMS source with + a JmsTemplate as a constructor-argument. + - - ]]> - In most cases, Spring Integration's message-driven JMS adapter is more appropriate since it delegates to a - MessageListener container and supports dynamically adjusting concurrent - consumers. The JmsMessageDrivenSourceAdapter requires references to a - MessageChannel, a ConnectionFactory, and a - Destination (or 'destinationName'). The following example defines a JMS - message-driven source adapter that receives from the JMS queue called "exampleQueue" and then sends to - the Spring Integration channel named "exampleChannel": - + In most cases, Spring Integration's message-driven JmsGateway is more appropriate since it + delegates to a MessageListener container, supports dynamically adjusting + concurrent consumers, and can also handle replies. The JmsGateway requires references to + a ConnectionFactory, and a Destination (or + 'destinationName'). The following example defines a JmsGateway that receives from the JMS + queue called "exampleQueue". Note that the 'expectReply' property has been set to 'true' (it is 'false' by + default): + - + ]]> - For both source adapter types, Spring's MessageConverter strategy is used to - convert the JMS message into a plain Java object, and then Spring Integration's - MessageMapper strategy is used to convert from the plain object to a - Message. - - - The JmsTargetAdapter is a MessageHandler implementation - that is capable of mapping Spring Integration Messages to JMS messages and then + The JmsTarget implements the Target interface + and is capable of mapping Spring Integration Messages to JMS messages and then sending to a JMS destination. It requires either a 'jmsTemplate' reference or both 'connectionFactory' and 'destination' references (again, the 'destinationName' may be provided in place of the 'destination). In , you will see how to configure a JMS target adapter with Spring @@ -116,13 +118,13 @@ RmiTargetAdapter rmiTargetAdapter = new RmiTargetAdapter(url);
File Adapters - The FileSourceAdapter extends the generic PollingSourceAdapter - (just as the polling JMS adapter does). It requires the following constructor arguments: - public FileSourceAdapter(File directory, MessageChannel channel, int period) - Optional properties include 'initialDelay' and 'maxMessagesPerTask'. + 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. - The FileTargetAdapter constructor only requires the 'directory' argument. The target + The FileTarget constructor also requires the 'directory' argument. The target adapter also accepts an implementation of the FileNameGenerator strategy that defines the following method: String generateFileName(Message message) @@ -130,9 +132,9 @@ RmiTargetAdapter rmiTargetAdapter = new RmiTargetAdapter(url);
FTP Adapters - To poll a directory with FTP, configure an instance of FtpSourceAdapter. The adapter - expects a number of properties for connecting to the FTP server (as shown below) as well as the - 'channel' and the 'period' for polling. For example, the following adapter would poll every 30 seconds: + To poll a directory with FTP, configure an instance of FtpSource and then connect + it to a channel by configuring a SourceEndpoint. The FtpSource + expects a number of properties for connecting to the FTP server as shown below. @@ -140,8 +142,6 @@ RmiTargetAdapter rmiTargetAdapter = new RmiTargetAdapter(url); - - ]]>
@@ -149,7 +149,7 @@ RmiTargetAdapter rmiTargetAdapter = new RmiTargetAdapter(url); Mail Adapters Spring Integration currently provides support for outbound email only with the - MailTargetAdapter. This adapter delegates to a configured instance of Spring's + MailTarget. This adapter delegates to a configured instance of Spring's JavaMailSender, and its various mapping strategies use Spring's MailMessage abstraction. By default text-based mails are created when the handled message has a String-based payload. If the message payload is a byte array, then that will @@ -194,10 +194,10 @@ MailAttributeKeys.REPLY_TO marshallingAdapter = new MarshallingWebServiceTargetAdapter(uri, marshaller); - As with the other target adapters, this can then be referenced from a MessageEndpoint - that is subscribed to a channel. The endpoint is then responsible for passing the response to the proper - channel. It will first check for a returnAddress on the original message's header, and it - will fallback to the endpoint's own default output channel. + 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. For more detail on the inner workings, see the Spring Web Services reference guide's chapter covering @@ -209,21 +209,22 @@ marshallingAdapter = new MarshallingWebServiceTargetAdapter(uri, marshaller);
Stream Adapters - Spring Integration also provides adapters for streams. Both ByteStreamSourceAdapter and - CharacterStreamSourceAdapter extend the PolllingSourceAdapter so - that 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 - ByteStreamSourceAdapter also accepts the 'bytesPerMessage' property to determine how many - bytes it will attempt to read into each Message. + 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, + 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' + property to determine how many bytes it will attempt to read into each Message. - For target streams, there are also two implementations: ByteStreamTargetAdapter and - CharacterStreamTargetAdapter. Each requires a single constructor argument - + For target streams, there are also two implementations: ByteStreamTarget and + 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 MessageHandler interface, they can be referenced from an - endpoint configuration as will be described in more detail in . + ultimately implement the Target interface, they can be referenced from a + TargetEndpoint configuration as will be described in more detail in + .
@@ -231,18 +232,17 @@ 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 ApplicationEventSourceAdapter (as with all source adapters, if a - MessageBus is defined, it will automatically detect the event source adapter). The - ApplicationEventSourceAdapter 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. + Integration's ApplicationEventSource (as with all source implementations, this can then + be configured within a SourceEndpoint 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. To send Spring ApplicationEvents, register an instance of the - ApplicationEventTargetAdapter class as the handler of an endpoint (such configuration - will be described in detail in ). This adapter implements Spring's - ApplicationEventPublisherAware interface and thus acts as a bridge between + ApplicationEventTarget class as the 'target' of a TargetEndpoint + (such configuration will be described in detail in ). This target also implements + Spring's ApplicationEventPublisherAware interface and thus acts as a bridge between Spring Integration Messages and ApplicationEvents.
diff --git a/spring-integration-reference/src/samples.xml b/spring-integration-reference/src/samples.xml index d81083f98f..42932e391f 100644 --- a/spring-integration-reference/src/samples.xml +++ b/spring-integration-reference/src/samples.xml @@ -89,8 +89,8 @@ public class DrinkRouter { When you run cafeDemo, you will see that all 100 cold drinks are prepared in roughly the same amount of time as - only 70 of the hot drinks. This is to be expected based on their respective delays of 700 and 1000 milliseconds. + only 50 of the hot drinks. This is to be expected based on their respective delays of 1000 and 2000 milliseconds. However, by configuring the endpoint concurrency, you can dramatically change the results. For example, on my - machine, the following single modification causes all 100 hot drinks to be prepared before the 4th cold drink is + machine, the following single modification causes all 100 hot drinks to be prepared before the 5th cold drink is ready: @@ -174,8 +174,8 @@ public class Barista { In addition to experimenting with the 'concurrency' settings, you can also try adding the 'schedule' sub-element as described in . Additionally, you can experiment with the channel's configuration, such as adding a 'dispatcher-policy' as described in . If you - want to explore the sample in more detail, the source JAR is available in the "dist" directory: - 'spring-integration-samples-sources-1.0.0.M3.jar'. + want to explore the sample in more detail, the source JAR is available in the "src" directory: + 'org.springframework.integration.samples-sources-1.0.0.M4.jar'.
\ No newline at end of file