From 4180e8b4f2340fb93f5337b2a999cc0b59a68fd6 Mon Sep 17 00:00:00 2001
From: Artem Bilan <abilan@gopivotal.com>
Date: Tue, 22 Apr 2014 15:04:55 +0300
Subject: [PATCH] INT-2464: Add Mapping Method Args Examples to Docs

JIRA: https://jira.spring.io/browse/INT-2464

INT-2464 Doc Polishing
---
 src/reference/docbook/gateway.xml | 65 +++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/src/reference/docbook/gateway.xml b/src/reference/docbook/gateway.xml
index 192447dbd0..7148110d93 100644
--- a/src/reference/docbook/gateway.xml
+++ b/src/reference/docbook/gateway.xml
@@ -222,6 +222,71 @@ public String send2(Map foo, Map bar);
         are not allowed on the gateway; similarly, the <code>payload-expression</code> attribute and
         <code>&lt;header/&gt;</code> elements are not allowed on any <code>&lt;method/&gt;</code> elements.
       </para>
+
+	  <para><emphasis role="bold">Mapping Method Arguments</emphasis></para>
+
+	  <para>
+		  Here are examples showing how method arguments can be mapped to the message
+		  (and some examples of invalid configuration):
+	  </para>
+	<programlisting language="java"><![CDATA[public interface MyGateway {
+
+    void payloadAndHeaderMapWithoutAnnotations(String s, Map<String, Object> map);
+
+    void payloadAndHeaderMapWithAnnotations(@Payload String s, @Headers Map<String, Object> map);
+
+    void headerValuesAndPayloadWithAnnotations(@Header("k1") String x, @Payload String s, @Header("k2") String y);
+
+    void mapOnly(Map<String, Object> map); // the payload is the map and no custom headers are added
+
+    void twoMapsAndOneAnnotatedWithPayload(@Payload Map<String, Object> payload, Map<String, Object> headers);
+
+    @Payload("#args[0] + #args[1] + '!'")
+    void payloadAnnotationAtMethodLevel(String a, String b);
+
+    @Payload("@someBean.exclaim(#args[0])")
+    void payloadAnnotationAtMethodLevelUsingBeanResolver(String s);
+
+    void payloadAnnotationWithExpression(@Payload("toUpperCase()") String s);
+
+    void payloadAnnotationWithExpressionUsingBeanResolver(@Payload("@someBean.sum(#this)") String s); // ]]><co id="gw-mapping-co-100"/><![CDATA[
+
+    // invalid
+    void twoMapsWithoutAnnotations(Map<String, Object> m1, Map<String, Object> m2);
+
+    // invalid
+    void twoPayloads(@Payload String s1, @Payload String s2);
+
+    // invalid
+    void payloadAndHeaderAnnotationsOnSameParameter(@Payload @Header("x") String s);
+
+    // invalid
+    void payloadAndHeadersAnnotationsOnSameParameter(@Payload @Headers Map<String, Object> map);
+
+}
+]]></programlisting>
+		<para>
+			<calloutlist>
+				<callout arearefs="gw-mapping-co-100">
+					<para>
+						Note that in this example, the SpEL variable <code>#this</code> refers to the argument - in this
+						case, the value of <code>'s'</code>.
+					</para>
+				</callout>
+			</calloutlist>
+		</para>
+		<para>
+			The XML equivalent looks a little different, since there is no <code>#this</code> context for the method argument,
+			but expressions can refer to method arguments using the <code>#args</code> variable:
+			<programlisting language="xml"><![CDATA[<int:gateway id="myGateway" service-interface="org.foo.bar.MyGateway">
+  <int:method name="send1" payload-expression="#args[0] + 'bar'"/>
+  <int:method name="send2" payload-expression="@someBean.sum(#args[0])"/>
+  <int:method name="send3" payload-expression="#method"/>
+  <int:method name="send4">
+    <int:header name="foo" expression="#args[2].toUpperCase()"/>
+  </int:method>
+</int:gateway>]]></programlisting>
+		</para>
     </section>
 
 	<section id="messaging-gateway-annotation">