From 19b4557d630126c2d46ca778abf41825c55ff959 Mon Sep 17 00:00:00 2001
From: Mark Fisher <markfisher@vmware.com>
Date: Fri, 14 Nov 2008 02:08:45 +0000
Subject: [PATCH] Added documentation for SimpleMessagingGateway and
 GatewayProxyFactoryBean (INT-458).

---
 spring-integration-reference/src/gateway.xml  | 49 +++++++++++++++++++
 .../src/spring-integration-reference.xml      |  1 +
 2 files changed, 50 insertions(+)
 create mode 100644 spring-integration-reference/src/gateway.xml

diff --git a/spring-integration-reference/src/gateway.xml b/spring-integration-reference/src/gateway.xml
new file mode 100644
index 0000000000..b96421dd60
--- /dev/null
+++ b/spring-integration-reference/src/gateway.xml
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="gateway">
+  <title>Inbound Messaging Gateways</title>
+
+  <section id="gateway-simple">
+    <title>SimpleMessagingGateway</title>
+    <para>
+      Even though the <classname>MessageChannelTemplate</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"><![CDATA[ public void send(Object object) { ... }
+
+ public Object receive() { ... }
+
+ public Object sendAndReceive(Object object) { ... }
+
+ Message<?> sendAndReceiveMessage(Object object);]]></programlisting>
+      It enables configuration of a request and/or reply channel and delegates to instances of the
+      <interfacename>InboundMessageMapper</interfacename> and <interfacename>OutboundMessageMapper</interfacename>
+      strategy interfaces.
+      <programlisting language="java"> SimpleMessagingGateway gateway = new SimpleMessagingGateway(inboundMapper, outboundMapper);
+ gateway.setRequestChannel(requestChannel);
+ gateway.setReplyChannel(replyChannel);
+ Object result = gateway.sendAndReceive("test");</programlisting>
+    </para>
+  </section>
+
+  <section id="gateway-proxy">
+    <title>GatewayProxyFactoryBean</title>
+    <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"
+         default-request-channel="requestChannel"
+         default-reply-channel="replyChannel"/>]]></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. The general
+      approach is similar to that of Spring Remoting (RMI, HttpInvoker, etc.). See the "Samples" Appendix for
+      an example that uses this "gateway" element.
+	</para>
+  </section>
+
+</chapter>
\ No newline at end of file
diff --git a/spring-integration-reference/src/spring-integration-reference.xml b/spring-integration-reference/src/spring-integration-reference.xml
index 00c00afbe5..fe031c0ee1 100644
--- a/spring-integration-reference/src/spring-integration-reference.xml
+++ b/spring-integration-reference/src/spring-integration-reference.xml
@@ -52,6 +52,7 @@
   <xi:include href="./splitter.xml"/>
   <xi:include href="./aggregator.xml"/>
   <xi:include href="./resequencer.xml"/>
+  <xi:include href="./gateway.xml"/>
   <xi:include href="./file.xml"/> 
   <xi:include href="./jms.xml"/>
   <xi:include href="./ws.xml"/>