diff --git a/spring-integration-reference/src/core-api.xml b/spring-integration-reference/src/core-api.xml index 98f09c37da..a3c557f755 100644 --- a/spring-integration-reference/src/core-api.xml +++ b/spring-integration-reference/src/core-api.xml @@ -14,7 +14,9 @@ Object getId(); MessageHeader getHeader(); T getPayload(); + void setPayload(T payload); boolean isExpired(); + void copyHeader(MessageHeader header, boolean overwriteExistingValues); } And the header provides the following properties: @@ -75,8 +77,9 @@ new GenericMessage<T>(T payload); new GenericMessage<T>(T payload, MessageHeader headerToCopy) When no id is provided, a random unique id will be generated. The constructor that accepts a - MessageHeader will copy properties, attributes, and any 'returnAddress' from the - provided header. There are also two convenient subclasses available currently: + MessageHeader will copy properties and attributes as well as the + 'returnAddress', 'sequenceNumber', and 'sequenceSize' properties from the provided header. + There are also two convenient subclasses available currently: StringMessage and ErrorMessage. The latter accepts any Throwable object as its payload. @@ -103,11 +106,11 @@ new GenericMessage<T>(T payload, MessageHeader headerToCopy)
- Source + MessageSource - The Source interface defines a single method for receiving + The MessageSource interface defines a single method for receiving Message objects. - public interface Source<T> { + public interface MessageSource<T> { Message<T> receive(); } Spring Integration also provides a MethodInvokingSource implementation that serves as an @@ -115,32 +118,32 @@ new GenericMessage<T>(T payload, MessageHeader headerToCopy)MethodInvokingSource, provide the Object reference and the method name. MethodInvokingSource source = new MethodInvokingSource(); source.setObject(new SourceObject()); -source.setMethod("sourceMethod"); +source.setMethodName("sourceMethod"); Message<?> result = source.receive(); It is generally more common to configure a MethodInvokingSource in XML by providing a - bean reference. - ]]> + bean reference in the "source" attribute of a <channel-adapter> element. + ]]>
- Target + MessageTarget - The Target interface defines a single method for sending + The MessageTarget interface defines a single method for sending Message objects. - public interface Target { + public interface MessageTarget { boolean send(Message<?> message); } - As with the Source, Spring Integration also provides a + As with the MessageSource, Spring Integration also provides a MethodInvokingTarget adapter class. MethodInvokingTarget target = new MethodInvokingTarget(); target.setObject(new TargetObject()); target.setMethodName("targetMethod"); target.afterPropertiesSet(); target.send(new StringMessage("test")); - Likewise, the corresponding XML configuration is very similar to that of - MethodInvokingSource. - ]]> + When creating a Channel Adapter for this target, the corresponding XML configuration + is very similar to that of MethodInvokingSource. + ]]>
@@ -153,7 +156,6 @@ target.send(new StringMessage("test")); Spring Integration provides several different implementations of the MessageChannel interface. Each is briefly described in the sections below. +
+ PublishSubscribeChannel + + The PublishSubscribeChannel implementation broadcasts any Message + sent to it to all of its subscribed consumers. This is most often used for sending + Event Messages whose primary role is notification as opposed to + Document Messages which are generally intended to be processed by + a single consumer. Note that the PublishSubscribeChannel is + intended for sending only. Since it broadcasts to its subscribers directly when its + send(Message) method is invoked, consumers cannot receive + Messages by invoking receive(). Instead, any subscriber must + be a MessageTarget itself, and the subscriber's + send(Message) method will be invoked in turn. + +
QueueChannel - The QueueChannel implementation wraps a queue. It provides a no-argument constructor + The QueueChannel implementation wraps a queue. Unlike, the + PublishSubscribeChannel, the QueueChannel has + point-to-point semantics. In other words, even if the channel has multiple consumers, only + one of them should receive any Message sent to that channel. It provides a no-argument constructor (that uses a default capacity of 100) as well as a constructor that accepts the queue capacity: public QueueChannel(int capacity) A channel that has not reached its capacity limit will store messages in its internal queue, and the @@ -219,14 +239,17 @@ target.send(new StringMessage("test"));
DirectChannel - The DirectChannel is significantly different than the channel implementations described - thus far. It's primary purpose is to enable a single thread to perform the operations on "both sides" of the - channel. For example, if a HandlerEndpoint is subscribed to a - DirectChannel, then sending a Message to that channel will trigger invocation of the - handler directly in the sender's thread. The key motivation for providing a channel - implementation with this behavior is to support transactions. If the send call is invoked within the scope of a - transaction, then the outcome of the handler invocation can play a role in determining the ultimate result of - that transaction (commit or rollback). + The DirectChannel has point-to-point semantics, but otherwise is more similar + to the PublishSubscribeChannel than any of the queue-based channel implementations + described above. In other words, it also dispatches Messages directly but only to a single receiver. Its + primary purpose is to enable a single thread to perform the operations on "both sides" of the channel. For + example, if a receiving target is subscribed to a DirectChannel, then sending a + Message to that channel will trigger invocation of that target's send(Message) + method directly in the sender's thread. The key motivation for providing a channel + implementation with this behavior is to support transactions that must span across the channel while still + benefiting from the abstraction and loose coupling that the channel provides. If the send call is invoked + within the scope of a transaction, then the outcome of the target's invocation can play a role in determining + the ultimate result of that transaction (commit or rollback).
@@ -307,155 +330,59 @@ target.send(new StringMessage("test")); Message, but how do the messages get passed from the channel to the handler? As mentioned earlier, the MessageBus provides a runtime form of inversion of control, and one of the primary responsibilities that it assumes is connecting the channels to the handlers. It also connects - Sources and Targets to channels, and it manages the scheduling of pollers and dispatchers. + MessageSources and MessageTargets to channels, and it manages the scheduling of pollers and dispatchers. The MessageBus is an example of a mediator. It performs a number of roles - mostly by delegating to other strategies. One of its main responsibilities is to manage registration of the - MessageChannels and MessageHandlers. It provides - the following methods: - public void registerChannel(String name, MessageChannel channel) + MessageChannels and endpoints, such as Channel Adapters + and Service Activators. It recognizes any of these instances that have been defined + within its ApplicationContext. + + + The message bus handles several of the concerns so that the channels, sources, targets, and Message-handling + objects can be as simple as possible. These responsibilities include the lifecycle management of + message endpoints, the activation of subscriptions, and the scheduling of dispatchers (including + the configuration of thread pools). The bus coordinates all of that behavior based upon the metadata provided + in bean definitions. Furthermore, those bean definitions may be provided via XML and/or annotations + (we will look at examples of both configuration options shortly). + + + The bus creates and schedules triggers for all of its registered endpoints. When an endpoint + receives a trigger event, it will poll the MessageSource that + was provided in its metadata. For example, a Channel Adapter will poll the + referenced "source", and a Service Activator will poll the referenced + "input-channel". + +
-public void registerHandler(String name, MessageHandler handler, - Subscription subscription) - -public void registerHandler(String name, MessageHandler handler, - Subscription subscription, - ConcurrencyPolicy concurrencyPolicy) - As those method signatures reveal, the message bus is handling several of the concerns here so that the channel - and handler objects can be as simple as possible. These responsibilities include the creation and lifecycle - management of message dispatchers, the activation of handler subscriptions, and the configuration of thread - pools. The bus coordinates all of that behavior based upon the metadata provided via these registration methods, - and typically developers will not even use this API directly since the metadata can be provided in XML and/or - annotations. We will briefly take a look at each of those metadata objects. +
+ MessageEndpoint + + As described in , there are different types of Message Endpoint, such + as the Channel Adapter (inbound or outbound) and the Service Activator. + Spring Integration provides many other components that are also endpoints, such as Routers, + Splitters, and Aggregators. Each endpoint may provide its own specific metadata so that the + MessageBus can manage its connection to a channel and its polling schedule. - The bus creates and manages dispatchers that pull messages from a channel in order to push those messages to - handlers subscribed to that channel. Each channel has a DispatcherPolicy that contains - metadata for configuring those dispatchers: -
- Properties of the DispatcherPolicy - - - - - Property Name - Default Value - Description - - - - - publishSubscribe - false - whether the dispatcher should attempt to publish to all of its handlers (rather than just one) - - - maxMessagesPerTask - 1 - maximum number of messages to retrieve per poll - - - receiveTimeout - 1000 (milliseconds) - how long to block on the receive call (0 for no blocking, -1 for indefinite block) - - - rejectionLimit - 5 - maximum number of attempts to invoke handlers (e.g. no threads available) - - - retryInterval - 1000 (milliseconds) - amount of time to wait between successive attempts to invoke handlers - - - shouldFailOnRejectionLimit - true - whether to throw a MessageDeliveryException if the 'rejectionLimit' is - reached - if this is set to 'false', then such undeliverable messages would be dropped silently - - - -
+ The scheduling metadata is provided as an implementation of the Schedule interface. + This is an abstraction designed to allow extensibility of schedulers for messaging tasks. Currently, there is a + single implementation named PollingSchedule and the endpoint may set the + period property. The polling period may differ depending on the type of MessageSource + (e.g. file-system vs. JMS). - The bus registers handlers with a channel's dispatcher based upon the Subscription - metadata provided to the registerHandler() method. - - Properties of the Subscription - - - - - Property Name - Description - - - - - channel - the channel instance to subscribe to (an object reference) - - - channelName - the name of the channel to subscribe to - only used as a fallback if 'channel' is null - - - schedule - the scheduling metadata (see below) - - - -
- The scheduling metadata is provided as an implementation of the Schedule - interface. This is an abstraction designed to allow extensibility of schedulers for messaging tasks. Currently, - there is a single implementation named PollingSchedule that provides the following - properties: - - Properties of the PollingSchedule - - - - - Property Name - Default Value - Description - - - - - period - N/A - the delay interval between each poll - - - initialDelay - 0 - the delay prior to the first poll - - - timeUnit - TimeUnit.MILLISECONDS - time unit for 'period' and 'initialDelay' - - - fixedRate - false - 'false' indicates fixed-delay (no backlog) - - - -
- The PollingSchedule constructor requires the 'period' value. - - - The ConcurrencyPolicy is an optional parameter to provide when registering a handler. - When the MessageBus registers a handler, it will use these properties to configure - that handler's thread pool. These parameters are configurable on a per-handler basis since handlers may have - different performance characteristics and may have different expectations with regard to the volume of - throughput. The following table lists the available properties and their default values: + While the MessageBus manages the scheduling of the trigger invocation threads, it may be necessary + to have concurrent threads for the endpoint's processing of each receive-and-handle unit of work. + Spring Integration provides an endpoint interceptor called ConcurrencyInterceptor + for this very purpose. The interceptor's configuration is provided by the + ConcurrencyPolicy metadata object. When the MessageBus + activates an endpoint that has been defined with a ConcurrencyInterceptor, it will use these properties to + configure that endpoint's thread pool. These interceptors are configurable on a per-endpoint basis since + different endpoint handlers may have different performance characteristics and may have different + expectations with regard to the volume of throughput. The following table lists the available properties + of the ConcurrencyPolicy and their default values: Properties of the ConcurrencyPolicy @@ -492,49 +419,28 @@ public void registerHandler(String name, MessageHandler handler,
- - -
- MessageEndpoint - As described in , there are three implementations of the - MessageEndpoint interface: SourceEndpoint, - TargetEndpoint, and HandlerEndpoint. These endpoints provide the - metadata necessary for the MessageBus to manage Sources, - Targets, and MessageHandlers respectively. - - - For a SourceEndpoint, the MessageBus schedules a task for - polling the Source based on the provided schedule. - - - When a Target or MessageHandler is registered with - the MessageBus, the bus assigns it to a dispatcher that polls a - MessageChannel based on the provided schedule. Targets and handlers may also - provide concurrency settings in which case a thread pool will be created for asynchronous processing of messages. - - - Rather than programming to the API directly, it is simpler and more common to register sources, targets, and - handlers with either XML or annotation-based metadata. Then, the message endpoint is an internal responsibility - of the bus. The configuration options are discussed in detail in . + The details of configuring this and other metadata for each endpoint will be discussed in detail in + .
MessageSelector - As described above, when a MessageHandler is registered with the message bus, it - is hosted by an endpoint and thereby subscribed to a channel. Often it is necessary to provide additional - dynamic logic to determine what messages the handler should receive. The - MessageSelector strategy interface fulfills that role. + As described above, each endpoint is registered with the message bus and is thereby subscribed + to a channel. Often it is necessary to provide additional dynamic logic to + determine what messages the endpoint should receive. The MessageSelector + strategy interface fulfills that role. message); }]]> - A MessageEndpoint can be configured with zero or more selectors, and will only - receive messages that are accepted by each selector. Even though the interface is simple to implement, a couple - common selector implementations are provided. For example, the PayloadTypeSelector - provides similar functionality to Datatype Channels (as described in ) - except that in this case the type-matching can be done by the endpoint rather than the channel. + A MessageEndpoint can be configured with a selector (or selector-chain) + and will only receive messages that are accepted by each selector. Even though the interface is simple + to implement, a couple common selector implementations are provided. For example, the + PayloadTypeSelector provides similar functionality to Datatype Channels + (as described in ) except that in this case the type-matching can be done + by the endpoint rather than the channel. (123))); @@ -549,7 +455,7 @@ assertFalse(selector.accept(new GenericMessage(someObject))); and Message Router provide proactive routing. However, selectors accommodate additional uses. For example, the MessageChannel's 'purge' method accepts a selector: channel.purge(someSelector); - There is even a ChannelPurger utility class whose purge operation is a good candidate for + There is a ChannelPurger utility class whose purge operation is a good candidate for Spring's JMX support: ChannelPurger purger = new ChannelPurger(new ExampleMessageSelector(), channel); purger.purge(); diff --git a/spring-integration-reference/src/overview.xml b/spring-integration-reference/src/overview.xml index 6771027bd1..9e58ef3f63 100644 --- a/spring-integration-reference/src/overview.xml +++ b/spring-integration-reference/src/overview.xml @@ -120,44 +120,50 @@ To facilitate the conversion of Objects to Messages, Spring Integration also defines a strategy interface for creating Messages called MessageCreator. While it is relatively easy to - implement Source directly, an adapter is also available for invoking arbitrary methods on plain Objects. Also, - several Source implementations are already available within the Spring Integration Adapters module. For a - detailed discussion of the various adapters, see . + implement Spring Integration's MessageSource interface directly, an adapter + is also available for invoking arbitrary methods on plain Objects. Also, several + MessageSource implementations are already available within the Spring + Integration Adapters module. For a detailed discussion of the various adapters, see .
Message Target - Just as a Source enables Message reception, a Target handles the responsibility of sending Messages. As with - a Source, a Target can act as an adapter that converts Messages into the Objects expected by some other system. + Just as a MessageSource enables Message reception, a + MessageTarget handles the responsibility of sending Messages. As with the + MessageSource, a MessageTarget can act as an + adapter that converts Messages into the Objects expected by some other system. Spring Integration provides a strategy interface for mapping Messages to Objects called - MessaegMapper. The Target interface may be implemented directly, but an adapter - is also available for invoking arbitrary methods on plain Objects (delegating to the Message-mapping strategy - in the process). As with Sources, several Target implementations are already available within the Spring - Integration Adapters module as discussed in . + MessageMapper. The MessageTarget interface may be implemented directly, but + an adapter is also available for invoking arbitrary methods on plain Objects (delegating to a + MessageMapper strategy in the process). As with MessageSources, several + MessageTarget implementations are already available within the Spring Integration Adapters module as + discussed in .
Message Handler - As described above, the Source and Target components support conversion between Objects and Messages so that - application code and/or external systems can be connected to a Spring Integration application rather easily. - However, both Source and Target are unidirectional while the application code or external system to be invoked - may provide a return value. The Message Handler interface supports these request-reply scenarios. + As described above, the MessageSource and MessageTarget components support conversion between Objects and + Messages so that application code and/or external systems can be connected to a Spring Integration application + rather easily. However, both MessageSource and MessageTarget are unidirectional while the application code or + external system to be invoked may provide a return value. The MessageHandler + interface supports these request-reply scenarios. - As with the Source and Target, Spring Integration also provides an adapter that itself implements the Message - Handler interface while supporting the invocation of arbitrary methods on plain Objects. The adapter relies - upon the message-creating and message-mapping strategies to handle the bidirectional Object/Message conversion. - For more information about the Message Handler, see . + As with the MessageSource and MessageTarget, Spring Integration also provides an adapter that itself implements + the MessageHandler interface while supporting the invocation of arbitrary methods + on plain Objects. The adapter relies upon the message-creating and message-mapping strategies to handle the + bidirectional Object/Message conversion. For more information about the Message Handler, see + .
@@ -165,27 +171,27 @@ A Message Channel represents the "pipe" of a pipes-and-filters architecture. Producers send Messages to a channel, and consumers receive Messages from a channel. By providing both send and receive operations, a - Message Channel basically combines the roles of Source and Target. + Message Channel basically combines the roles of MessageSource and MessageTarget. - Spring Integration provides a number of different channel implementations: QueueChannel, PriorityChannel, - RendezvousChannel, DirectChannel, and ThreadLocalChannel. These are described in detail in - . + Spring Integration provides a number of different channel implementations: PublishSubscribeChannel, + QueueChannel, PriorityChannel, RendezvousChannel, DirectChannel, and ThreadLocalChannel. These are described + in detail in .
Message Endpoint - Thus far, the component diagrams show Consumers, Producers, and Requesters invoking the Source, Target, and - Message Handlers respectively. However, one of the primary goals of Spring Integration is to simplify the - development of enterprise integration solutions through inversion of control. This means - that you should not have to implement such Producers, Consumers, and Requesters directly. Instead, you should - be able to focus on your domain logic with an implementation based on plain Objects. Then, by providing - declarative configuration, you can "connect" your application code to the messaging infrastructure provided by - Spring Integration. The components responsible for these connections are Message Endpoints. + Thus far, the component diagrams show consumers, producers, and requesters invoking the MessageSource, + MessageTarget, and MessageHandlers respectively. However, one of the primary goals of Spring Integration is to + simplify the development of enterprise integration solutions through inversion of control. + This means that you should not have to implement such consumers, producers, and requesters directly. Instead, + you should be able to focus on your domain logic with an implementation based on plain Objects. Then, by + providing declarative configuration, you can "connect" your application code to the messaging infrastructure + provided by Spring Integration. The components responsible for these connections are Message Endpoints. A Message Endpoint represents the "filter" of a pipes-and-filters architecture. As mentioned above, the @@ -194,47 +200,60 @@ the Message Channels. This is similar to the role of a Controller in the MVC paradigm. Just as a Controller handles HTTP requests, the Message Endpoint handles Messages. Just as Controllers are mapped to URL patterns, Message Endpoints are mapped to Message Channels. The goal is the same in both cases: isolate application code - from the infrastructure. Spring Integration provides three types of endpoints - one for each of the component - types described above: Source Endpoint, Target Endpoint, and Handler Endpoint. + from the infrastructure. Spring Integration provides Message Endpoints for connecting each of the component + types described above.
- Source Endpoint + Channel Adapter - A Source Endpoint connects any Source implementation to a Message Channel. The invocation of the Source's - receive operation is controlled by scheduling information provided within the Source Endpoint's - configuration. Any time the receive operation returns a non-null Message, it is sent to the channel. + A Channel Adapter is an endpoint that connects either a MessageSource or a MessageTarget to a + MessageChannel. If a MessageSource is being adapted, then the adapter is responsible for receiving + Messages from the MessageSource and sending them to the MessageChannel. If a Message Target is being + adapted, then the adapter is responsible for receiving Messages from the MessageChannel and sending + them to the MessageTarget. + + + When a Channel Adapter is used to connect a MessageSource implementation to a Message Channel, + the invocation of the MessageSource's receive operation may be controlled by scheduling information + provided within the Channel Adapter's configuration. Any time the receive operation returns a non-null + Message, it is sent to the MessageChannel. + An inbound "Channel Adapter" endpoint connects a MessageSource to a MessageChannel -
-
- Target Endpoint - A Target Endpoint connects a Message Channel to any Target implementation. The invocation of the Message - Channel's receive operation is controlled by scheduling information provided within the Target Endpoint's - configuration. Any time a non-null Message is received from the channel, it is sent to the Target. + When a Channel Adapter is used to connect a MessageTarget implementation to a Message Channel, + the invocation of the MessageChannel's receive operation may be controlled by scheduling information + provided within the Channel Adapter's configuration. Any time a non-null Message is received from the + MessageChannel, it is sent to the MessageTarget. + An outbound "Channel Adapter" endpoint connects a MessageChannel to a MessageTarget
- Handler Endpoint + Service Activator - Since Message Handler's are capable of returning reply Messages, the Handler Endpoint has some additional - responsibilities. The general behavior is the same as the Target Endpoint, but the Handler Endpoint must - make a distinction between "input-channel" and "output-channel". Whenever the Message Handler does return - a reply Message, that Message is sent to the output channel. If no output channel has been configured, then - the reply will be sent to the channel specified as the Message header's "return address" if available. + When the Object to be invoked is capable of returning a value, another type of endpoint is + needed to accommodate the additional responsibilities of the request/reply + interaction. The general behavior is similar to a Channel Adapter, but this type of endpoint - + the Service Activator - must make a distinction between the "input-channel" and the "output-channel". + Whenever the Message-handling Object does return a reply Message, that Message is sent to the output + channel. If no output channel has been configured, then the reply will be sent to the channel + specified in the MessageHeader's "return address" if available. + + A request-reply "Service Activator" endpoint connects a MessageHandler to input and output MessageChannels. +
@@ -242,10 +261,11 @@
Message Router - A Message Router is a particular type of MessageHandler that is capable of - receiving a Message and then deciding what channel or channels should receive the Message next. Typically the - decision is based upon the Message's content and/or metadata. A Message Router is often used as a dynamic - alternative to configuring the input and output channels for an endpoint. + A Message Router is a particular type of Message Endpoint that is capable of receiving a Message from + a MessageChannel and then deciding what channel or channels should receive the Message next (if any). + Typically the decision is based upon the Message's content and/or metadata available in the MessageHeader. + A Message Router is often used as a dynamic alternative to a statically configured output channel on + a Service Activator or other Message-handling endpoint.