From 144e93e89f883b8175f827592537b780b97de231 Mon Sep 17 00:00:00 2001
From: Mark Fisher <markfisher@vmware.com>
Date: Fri, 23 May 2008 04:31:33 +0000
Subject: [PATCH] Added RequestReplyTemplate and GatewayProxyFactoryBean
 coverage to the Reference Documentation.

---
 spring-integration-reference/src/core-api.xml | 56 +++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/spring-integration-reference/src/core-api.xml b/spring-integration-reference/src/core-api.xml
index 5b31bf9423..98f09c37da 100644
--- a/spring-integration-reference/src/core-api.xml
+++ b/spring-integration-reference/src/core-api.xml
@@ -563,4 +563,60 @@ purger.purge();</programlisting>
 channel.addInterceptor(interceptor);</programlisting>
     </para>
   </section>
+
+  <section id="api-requestreplytemplate">
+    <title>RequestReplyTemplate</title>
+    <para>
+      Whereas the <interfacename>MessageHandler</interfacename> interface provides the foundation for many of the
+      components that enable non-invasive invocation of your application code <emphasis>from the messaging
+      system</emphasis>, sometimes it is necessary to invoke the messaging system <emphasis>from your application
+      code</emphasis>. Spring Integration provides a <classname>RequestReplyTemplate</classname> that supports a
+      variety of request-reply scenarios. For example, it is possible to send a request and wait for a reply.
+      <programlisting language="java">RequestReplyTemplate template = new RequestReplyTemplate(requestChannel);
+Message reply = template.request(new StringMessage("test"));</programlisting>
+      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.
+      <programlisting language="java">RequestReplyTemplate template = new RequestReplyTemplate(requestChannel);
+template.setReplyChannel(replyChannel);
+Message reply = template.request(new StringMessage("test"));</programlisting>
+    </para>
+  </section>
+
+  <section id="api-gateway">
+    <title>MessagingGateway</title>
+    <para>
+      Even though the <classname>RequestReplyTemplate</classname> 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 <classname>SimpleMessagingGateway</classname> with the following methods:
+      <programlisting language="java">public void send(Object object) { ... }
+public Object receive() { ... }
+public Object sendAndReceive(Object object) { ... }
+</programlisting>
+      It enables configuration of a request and/or reply channel and delegates to the
+      <interfacename>MessageMapper</interfacename> and <interfacename>MessageCreator</interfacename> strategy
+      interfaces.
+      <programlisting language="java">SimpleMessagingGateway gateway = new SimpleMessagingGateway();
+gateway.setRequestChannel(requestChannel);
+gateway.setReplyChannel(replyChannel);
+gateway.setMessageCreator(messageCreator);
+gateway.setMessageMapper(messageMapper);
+Object result = gateway.sendAndReceive("test");
+</programlisting>
+    </para>
+    <para>
+      Working with Objects instead of Messages is an improvement. However, it would be even better to have no
+      dependency on the Spring Integration API at all - including the gateway class. For that reason, Spring
+      Integration also provides a <classname>GatewayProxyFactoryBean</classname> that generates a proxy for
+      any interface and internally invokes the gateway methods shown above. Namespace support is also
+      provided as demonstrated by the following example.
+      <programlisting language="xml"><![CDATA[<gateway id="fooService"
+         service-interface="org.example.FooService"
+         request-channel="requestChannel"
+         reply-channel="replyChannel"
+         message-creator="messageCreator"
+         message-mapper="messageMapper"/>]]></programlisting>
+      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.
+    </para>
+  </section>
 </chapter>
\ No newline at end of file