INT-2629 Extract Gateway Argument Mapping Strategy

https://jira.springsource.org/browse/INT-2629

Strategy for mapping gateway methods to map method arguments
to a message.

Default strategy works as today, but pluggable using attribute
'mapper' on <gateway/>.

A custom mapper should implement InboundMessageMapper<MethodArgsHolder>

where the MethodArgsHolder contains the Method object and the argument
values.

When using a custom mapper, the mapper is entirely responsible for
creating the Message - therefore 'payload-expression' attributes
and <header/> elements are not allowed.

INT-2629 Polishing - Javadocs

INT-2629 Polishing

- Introduce MethodArgsMessageMapper - higher level API for custom mapper.

INT-2629: Polishing docs

src/reference/docbook/gateway.xml

@@ -187,6 +187,43 @@ public interface Cafe {
     </para>
 
     </section>
+    <section id="gateway-mapping">
+      <title>Mapping Method Arguments to a Message</title>
+      <para>
+        Using the configuration techniques in the previous section allows control of how method arguments are mapped
+        to message elements (payload and header(s)). When no explicit configuration is used, certain conventions are
+        used to perform the mapping. In some cases, these conventions cannot determine which argument is the payload
+        and which should be mapped to headers.
+      </para>
+      <programlisting language="java"><![CDATA[
+public String send1(Object foo, Map bar);
+
+public String send2(Map foo, Map bar);
+      ]]></programlisting>
+      <para>
+        In the first case, the convention will map the first argument to the payload (as long as it is not a
+        <code>Map</code>) and the contents of the second become headers.
+      </para>
+      <para>
+        In the second case (or the first when the argument for parameter <code>foo</code> is a <code>Map</code>),
+        the framework cannot determine
+        which argument should be the payload; mapping will fail. This can generally be resolved using a
+        <code>payload-expression</code>, a <code>@Payload</code> annotation and/or a <code>@Headers</code>
+        annotation.
+      </para>
+      <para>
+        Alternatively, and whenever the conventions break down, you can take the entire responsibility for
+        mapping the method calls to messages. To do this, implement an
+        <classname>MethodArgsMessageMapper</classname> and provide it to the
+        <code>&lt;gateway/&gt;</code> using the <code>mapper</code> attribute. The mapper maps a
+        <classname>MethodArgsHolder</classname>, which is a simple class wrapping the <classname>java.reflect.Method</classname>
+        instance and an <code>Object[]</code> containing the arguments. When providing a custom mapper,
+        the <code>default-payload-expression</code> attribute and <code>&lt;default-header/&gt;</code> elements
+        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>
+    </section>
+
     <section id="gateway-calling-no-argument-methods">
       <title>Invoking No-Argument Methods</title>
       <para>

src/reference/docbook/whats-new.xml

@@ -163,6 +163,10 @@
 						It is now possible to set common headers across all gateway methods, and more options
 						are provided for adding, to the message, information about which method was invoked.
 					</listitem>
+					<listitem>
+						It is now possible to entirely customize the way that gateway method calls are mapped
+						to messages.
+					</listitem>
 				</itemizedlist>
 			</para>
 			<para>