From f80e3fe14b8882a07a1d53a8cddfe82abdc51315 Mon Sep 17 00:00:00 2001
From: Oleg Zhurakousky <ozhurakousky@vmware.com>
Date: Thu, 18 Nov 2010 19:12:40 -0500
Subject: [PATCH] INT-1552 removed MapBasedChannelResolver in teh
 HeaderValueRouter section, added paragraph on
 'ignore-channel-name-resolution-failures' attribute

---
 docs/src/reference/docbook/router.xml | 53 ++++++++++++---------------
 1 file changed, 23 insertions(+), 30 deletions(-)

diff --git a/docs/src/reference/docbook/router.xml b/docs/src/reference/docbook/router.xml
index cfaa8b91d4..656cc0e971 100644
--- a/docs/src/reference/docbook/router.xml
+++ b/docs/src/reference/docbook/router.xml
@@ -42,7 +42,7 @@
       <title>HeaderValueRouter</title>
       <para>
         A <classname>HeaderValueRouter</classname> will send Messages to the channel based on the individual header value mappings.
-        When <code>HeaderValueRouter</code> is created it is initialized with the <emphasis>name</emphasis> of the header to be evaluated, using <code>constructor-arg</code>.
+        When <code>HeaderValueRouter</code> is created it is initialized with the <emphasis>name</emphasis> of the header to be evaluated.
         The <emphasis>value</emphasis> of the header could be one of two things:</para>
       <para>
         1. Arbitrary value
@@ -51,47 +51,37 @@
         2. Channel name
      </para>
      <para>
-        If arbitrary value, then a <code>channelResolver</code> should be provided to map <emphasis>header values</emphasis> to <emphasis>channel names</emphasis>.
-    The example below uses <code>MapBasedChannelResolver</code> to set up a map of header values to channel names.
-<programlisting language="xml"><![CDATA[ <bean id="myHeaderValueRouter"
-    class="org.springframework.integration.router.HeaderValueRouter">
-  <constructor-arg value="someHeaderName" />
-  <property name="channelResolver">
-    <bean class="org.springframework.integration.channel.MapBasedChannelResolver">
-      <property name="channelMap">
-        <map>
-          <entry key="someHeaderValue" value-ref="channelA" />
-          <entry key="someOtherHeaderValue" value-ref="channelB" />
-        </map>
-      </property>
-    </bean>
-  </property>
-</bean>
-]]></programlisting>
-        If <code>channelResolver</code> is not specified, then the <emphasis>header value</emphasis> will be treated as a <emphasis>channel name</emphasis>
-        making configuration much simpler, where no <code>channelResolver</code> needs to be specified.
-<programlisting language="xml"><![CDATA[
-<bean id="myHeaderValueRouter"
-  class="org.springframework.integration.router.HeaderValueRouter">
-  <constructor-arg value="someHeaderName" />
-</bean>
-]]></programlisting>
+      If arbitrary then additional mapping of these header values to channel names is required, otherwise no additional configuration is needed.
       </para>
       <para>
-      Similar to the <classname>PayloadTypeRouter</classname>, configuration of <classname>HeaderValueRouter</classname> is also supported via namespace support provided by Spring Integration (see <xref linkend="configuration-namespace"/>).
-      The example below demonstrates two types of namespace-based configuration of <classname>HeaderValueRouter</classname> which are equivalent to the ones above using Spring Integration namespace support:
+      Similar to the <classname>PayloadTypeRouter</classname>, configuration of <classname>HeaderValueRouter</classname> is 
+      also supported with the simple namespace-based XML configuration.
+      The example below demonstrates two types of namespace-based configuration of <classname>HeaderValueRouter</classname>.
       </para>
-      <para>1. Configuration where mapping of header values to channels is required</para>
+      <para><emphasis>1. Configuration where mapping of header values to channels is required</emphasis> </para>
       <para>
       <programlisting language="xml"><![CDATA[<header-value-router input-channel="routingChannel" header-name="testHeader">
   <mapping value="someHeaderValue" channel="channelA" />
   <mapping value="someOtherHeaderValue" channel="channelB" />
 </header-value-router>]]></programlisting>
   </para>
-  <para>2. Configuration where mapping of header values is not required if header values themselves represent the channel names</para>
+  <para>
+  Obviously during the resolution process this router may encounter resolution failures, thus resulting in 
+  exception. If you want to suppress such resolution failures and send all messages to the 
+  default output channel (i.e., identified with <code>default-output-channel</code> attribute) you may do so by setting 
+  <code>ignore-channel-name-resolution-failures</code> to true. This particular attribute may sound confusing when compared with 
+  the <code>default-output-channel</code>. So just to clarify, the <code>default-output-channel</code> handles messages where routing 
+  information can not be determined. However, in the above scenario route has determined successfully but the 
+  resolution of that route failed and that is why we need an extra attribute to let Spring Integration know that it is 
+  OK to suppress resolution failures and treat such route as undetermined thus routing messages to the <code>default-output-channel</code>
+  </para>
+  
+  <para> <emphasis>2. Configuration where mapping of header values to channel names 
+  is not required since header values themselves represent channel names</emphasis> </para>
       <para>
       <programlisting language="xml"><![CDATA[<header-value-router input-channel="routingChannel" header-name="testHeader"/>]]></programlisting>
   </para>
+  
   <note>
       The two router implementations shown above share some common properties, such as "defaultOutputChannel" and "resolutionRequired".
       If "resolutionRequired" is set to "true", and the router is unable to determine a target channel (e.g. there is
@@ -99,6 +89,9 @@
       will be thrown.
     </note>
     </section>
+    
+    
+    
     <section id="router-implementations-recipientlistrouter">
       <title>RecipientListRouter</title>
       <para>