From 45c3066eb916981cb89eb23fc8c7365b00d9f354 Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Wed, 20 Aug 2008 02:31:07 +0000 Subject: [PATCH] Updated Message Endpoint, MessageExchangeTemplate, and Messaging Gateway sections. --- spring-integration-reference/src/core-api.xml | 131 ++++++++---------- 1 file changed, 60 insertions(+), 71 deletions(-) diff --git a/spring-integration-reference/src/core-api.xml b/spring-integration-reference/src/core-api.xml index 2121b0f060..e809339f97 100644 --- a/spring-integration-reference/src/core-api.xml +++ b/spring-integration-reference/src/core-api.xml @@ -469,65 +469,23 @@ boolean unsubscribe(MessageTarget target); 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. + MessageBus can manage its connection to channels and its poller (if necessary). 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 + This is an abstraction designed to allow extensibility of schedulers for messaging tasks. Currently, there are two + implementations: PollingSchedule and CronSchedule. The former has + a period property, and the latter has a cronExpression. The polling + schedule may be configured based on throughput expectations and/or the type of MessageSource (e.g. file-system vs. JMS). - 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 - - - - - Property Name - Default Value - Description - - - - - coreSize - 1 - the core size of the thread pool - - - maxSize - 10 - the maximum size the thread pool can reach when under demand - - - queueCapacity - 0 - capacity of the queue which defers an increase of the pool size - - - keepAliveSeconds - 60 - how long added threads (beyond core size) should remain idle before being removed from the pool - - - -
- - - The details of configuring this and other metadata for each endpoint will be discussed in detail in - . + While the MessageBus manages the scheduling of the pollers, it is often beneficial to have multiple task + executors with different concurrency settings for an endpoint or group of endpoints. This provides more control + over the number of threads available for each receive-and-handle unit of work and depending on the type of + task executor, may also enable dynamic adjustments. When the MessageBus + activates an endpoint, it will create and schedule the poller for that endpoint based on the endpoint's + configuration. This will be described in more detail in . @@ -539,7 +497,9 @@ boolean unsubscribe(MessageTarget target); determine what messages the endpoint should receive. The MessageSelector strategy interface fulfills that role. message); + }]]> 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 @@ -550,8 +510,7 @@ boolean unsubscribe(MessageTarget target); (123))); -assertFalse(selector.accept(new GenericMessage(someObject))); -]]> +assertFalse(selector.accept(new GenericMessage(someObject)));]]> Another simple but useful MessageSelector provided out-of-the-box is the UnexpiredMessageSelector. As the name suggests, it only accepts messages that have not yet expired. @@ -559,7 +518,7 @@ assertFalse(selector.accept(new GenericMessage(someObject))); Essentially, using a selector provides reactive routing whereas the Datatype Channel and Message Router provide proactive routing. However, selectors accommodate additional - uses. For example, the MessageChannel's 'purge' method accepts a selector: + uses. For example, a PollableChannel's 'purge' method accepts a selector: channel.purge(someSelector); There is a ChannelPurger utility class whose purge operation is a good candidate for Spring's JMX support: @@ -576,35 +535,64 @@ channel.addInterceptor(interceptor); -
- RequestReplyTemplate +
+ MessageExchangeTemplate Whereas the MessageHandler interface provides the foundation for many of the components that enable non-invasive invocation of your application code from the messaging system, sometimes it is necessary to invoke the messaging system from your application - code. Spring Integration provides a RequestReplyTemplate that supports a - variety of request-reply scenarios. For example, it is possible to send a request and wait for a reply. - RequestReplyTemplate template = new RequestReplyTemplate(requestChannel); -Message reply = template.request(new StringMessage("test")); - In that example, a temporary anonymous channel would be used internally by the template. However, the - 'replyChannel' may be configured explicitly in which case the template will manage the reply correlation. - RequestReplyTemplate template = new RequestReplyTemplate(requestChannel); -template.setReplyChannel(replyChannel); -Message reply = template.request(new StringMessage("test")); + code. Spring Integration provides a MessageExchangeTemplate that supports a + variety of message-exchanges, including request/reply scenarios. For example, it is possible to send a request + and wait for a reply. + MessageExchangeTemplate template = new MessageExchangeTemplate(); +Message reply = template.sendAndReceive(new StringMessage("test"), someChannel); + In that example, a temporary anonymous channel would be created internally by the template. The + 'sendTimeout' and 'receiveTimeout' properties may also be set on the template, and other exchange + types are also supported. + message, final MessageTarget target) { ... } + +public Message sendAndReceive(final Message request, final MessageTarget target) { .. } + +public Message receive(final PollableSource source) { ... } + +public boolean receiveAndForward(final PollableSource source, final MessageTarget target) { ... }]]> + + + Additionally, a 'transactionManager' can be configured on a MessageExchangeTemplate as well as the various + transaction attributes: + template.setTransactionManager(transactionManager); +template.setPropagationBehaviorName(propagationBehavior); +template.setIsolationLevelName(isolationLevel); +template.setTransactionTimeout(transactionTimeout); +template.setTransactionReadOnly(readOnly); +template.setReceiveTimeout(receiveTimeout); +template.setSendTimeout(sendTimeout); + Finally, there is a also an asynchronous version called AsyncMessageExchangeTemplate + whose constructor accepts a TaskExecutor, and whose Message-returning methods + return an AsyncMessage. That is essentially a wrapper for any Message that also + implements Future<Message<T>>: + AsyncMessageExchangeTemplate template = new AsyncMessageExchangeTemplate(taskExecutor); +Message reply = template.sendAndReceive(new StringMessage("test"), someChannel); +// do some work in the meantime +reply.getPayload(); // blocks if still waiting for actual reply +
MessagingGateway - Even though the RequestReplyTemplate is fairly straightforward, it does not hide the + Even though the MessageExchangeTemplate is fairly straightforward, it does not hide the details of messaging from your application code. To support working with plain Objects instead of messages, Spring Integration provides SimpleMessagingGateway with the following methods: public void send(Object object) { ... } + public Object receive() { ... } + public Object sendAndReceive(Object object) { ... } - - It enables configuration of a request and/or reply channel and delegates to the + +public void receiveAndForward() { ... } + It enables configuration of a request and/or reply channel and delegates to an instance of the MessageMapper and MessageCreator strategy interfaces. SimpleMessagingGateway gateway = new SimpleMessagingGateway(); @@ -628,7 +616,8 @@ Object result = gateway.sendAndReceive("test"); message-creator="messageCreator" message-mapper="messageMapper"/>]]> Then, the "fooService" can be injected into other beans, and the code that invokes the methods on that - proxied instance of the FooService interface has no awareness of the Spring Integration API. + proxied instance of the FooService interface has no awareness of the Spring Integration API. The general + approach is similar to that of Spring Remoting (RMI, HttpInvoker, etc.).
\ No newline at end of file