From 3e9c6545e0cbca0e2db27c04e6e6842ab0bfe798 Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Fri, 3 Sep 2010 15:52:13 +0000 Subject: [PATCH] edits in gateway doc --- src/docbkx/gateway.xml | 53 +++++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 24 deletions(-) diff --git a/src/docbkx/gateway.xml b/src/docbkx/gateway.xml index 39448c9468..178d16db7d 100644 --- a/src/docbkx/gateway.xml +++ b/src/docbkx/gateway.xml @@ -55,13 +55,13 @@ You can also provide individual headers per method invocation via XML. - This could be very useful if headers you want to set are static in nature and you don't want - to embed them in the gateway's method signature via @Header annotation. - For example; in the Loan Broker example we want to influence how aggregation of the Loan quotes + This could be very useful if the headers you want to set are static in nature and you don't want + to embed them in the gateway's method signature via @Header annotations. + For example, in the Loan Broker example we want to influence how aggregation of the Loan quotes will be done based on what type of request was initiated (single quote or all quotes). Determining the - type of the request by evaluating what gateway's method was invoked, although possible would + type of the request by evaluating what gateway method was invoked, although possible would violate the separation of concerns paradigm (method is a java artifact),  but expressing your - intention (meta information) via Message headers is natural to Messaging architecture. + intention (meta information) via Message headers is natural in a Messaging architecture. @@ -76,11 +76,11 @@ header based on the gateway's method. - As with anything else, Gateway invocation might result in error. - By default all error that have occurred downstream will be re-thrown as MessagingExeption (RuntimeException) - upon Gateway's method invocation. However there are times when you may want to treat Exception as a valid reply, - by mapping it to a Message. To accomplish this Gateway provides support for Exception mappers via exception-mapper - attribute. + As with anything else, Gateway invocation might result in errors. + By default any error that has occurred downstream will be re-thrown as a MessagingExeption (RuntimeException) + upon the Gateway's method invocation. However there are times when you may want to treat an Exception as a valid reply, + by mapping it to a Message. To accomplish this our Gateway provides support for Exception mappers via the + exception-mapper attribute. foo.bar.SampleExceptionMapper is the implementation of - org.springframework.integration.message.InboundMessageMapper which only defines one method toMessage(Object object). + org.springframework.integration.message.InboundMessageMapper which only defines one method: toMessage(Object object). { public Message toMessage(Throwable object) throws Exception { MessageHandlingException ex = (MessageHandlingException) object; @@ -108,19 +108,21 @@
Asynchronous Gateway - As a pattern Messaging Gateway is a very nice way to hide you from messaging-specific code while still exposing full capabilities of the - messaging system. And GatewayProxyFactoryBean provides a convenient way to expose Proxy over the service-interface thus giving you a POJO-based access - to a messaging system.  But when gateway is exposed via simple POJO method which returns value it does imply that for each Request message (method is invoked) - there must be a Reply message (method has returned). Since Messaging systems naturally are asynchronous you may not always able to - guarantee the contract where "for each request there will always be be a reply".  - With Spring Integration 2.0 we are introducing an Asynchronous Gateway which is a convenient way to initiate flows where you may not know - if reply is coming or how long will it take for it to come. + As a pattern the Messaging Gateway is a very nice way to hide messaging-specific code while still exposing the full capabilities of the + messaging system. And GatewayProxyFactoryBean provides a convenient way to expose a Proxy over a service-interface + thus giving you a POJO-based access to a messaging system (based on objects in your own domain, or primitives/Strings, etc).  But when a + gateway is exposed via simple POJO methods which return values it does imply that for each Request message (generated when the method is invoked) + there must be a Reply message (generated when the method has returned). Since Messaging systems naturally are asynchronous you may not always be + able to guarantee the contract where "for each request there will always be be a reply".  + With Spring Integration 2.0 we are introducing support for an Asynchronous Gateway which is a convenient way to initiate + flows where you may not know if a reply is expected or how long will it take for it to arrive. - A natural way to handle these types of scenarios in Java would be java.util.concurrent.Futures and that is exactly what Spring Integration uses to create an Asynchronous Gateway. + A natural way to handle these types of scenarios in Java would be relying upon java.util.concurrent.Future instances, and + that is exactly what Spring Integration uses to support an Asynchronous Gateway. - From the XML configuration, there is nothing different and you still define Asynchronous Gateway the same way as regular Gateway + From the XML configuration, there is nothing different and you still define Asynchronous Gateway the same way as a regular Gateway. ]]> @@ -131,14 +133,17 @@ } - As you can see from the example above the return type for the gateway method is Future. When GatewayProxyFactoryBean sees that the - return type of the gateway method is Future it immediately switches to the async mode by utilizing AsyncTaskExecutor - That is all. The call to a method always returns immediately with Future encapsulating  the interaction with the framework. + As you can see from the example above the return type for the gateway method is Future. When + GatewayProxyFactoryBean sees that the + return type of the gateway method is Future, it immediately switches to the async mode by utilizing + an AsyncTaskExecutor. That is all. The call to a method always returns immediately with Future + encapsulating  the interaction with the framework. Now you can interact with the Future at your own pace to get the result, timeout, get the exception etc... MathServiceGateway mathService = ac.getBean("mathService", MathServiceGateway.class); Future<Integer> result = mathService.multiplyByTwo(number); +// do something else here since the reply might take a moment int finalResult =  result.get(1000, TimeUnit.SECONDS); -For more detailed example please refer to async-gateway sample distributed with Spring Integration samples. +For a more detailed example, please refer to the async-gateway sample distributed within the Spring Integration samples.