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 payload-expression attribute and
<header/> elements are not allowed on any <method/> elements.
+
+ Mapping Method Arguments
+
+
+ Here are examples showing how method arguments can be mapped to the message
+ (and some examples of invalid configuration):
+
+ map);
+
+ void payloadAndHeaderMapWithAnnotations(@Payload String s, @Headers Map map);
+
+ void headerValuesAndPayloadWithAnnotations(@Header("k1") String x, @Payload String s, @Header("k2") String y);
+
+ void mapOnly(Map map); // the payload is the map and no custom headers are added
+
+ void twoMapsAndOneAnnotatedWithPayload(@Payload Map payload, Map 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); // ]]> m1, Map m2);
+
+ // invalid
+ void twoPayloads(@Payload String s1, @Payload String s2);
+
+ // invalid
+ void payloadAndHeaderAnnotationsOnSameParameter(@Payload @Header("x") String s);
+
+ // invalid
+ void payloadAndHeadersAnnotationsOnSameParameter(@Payload @Headers Map map);
+
+}
+]]>
+
+
+
+
+ Note that in this example, the SpEL variable #this refers to the argument - in this
+ case, the value of 's'.
+
+
+
+
+
+ The XML equivalent looks a little different, since there is no #this context for the method argument,
+ but expressions can refer to method arguments using the #args variable:
+
+
+
+
+
+
+
+]]>
+