From 7f66b9bc52f40ff5aec7e638cb76802278e19f15 Mon Sep 17 00:00:00 2001
From: Gunnar Hillert <ghillert@vmware.com>
Date: Mon, 31 Oct 2011 18:07:26 -0400
Subject: [PATCH] Describe 'ignore-send-failures' attribute better

In the XSD schema and in the reference documentation: describe the 'ignore-send-failures'
attribute, which is used by routers, in much more detail.
---
 docs/src/reference/docbook/router.xml         | 46 ++++++++++++++++---
 .../config/xml/spring-integration-2.1.xsd     | 19 +++++---
 2 files changed, 52 insertions(+), 13 deletions(-)

diff --git a/docs/src/reference/docbook/router.xml b/docs/src/reference/docbook/router.xml
index e4bfe6b2d4..1bc5116a14 100644
--- a/docs/src/reference/docbook/router.xml
+++ b/docs/src/reference/docbook/router.xml
@@ -289,13 +289,45 @@
               </varlistentry>
               <varlistentry><term><emphasis role="bold">ignore-send-failures</emphasis></term>
                   <listitem>
-                  <para>
-                      If set to <emphasis>true</emphasis>, any failures that
-                      occur while trying to send to a single channel will be
-                      ignored. Otherwise, a <code>MessageDeliveryExceptions</code>
-                      will be thrown. This attribute defaults to
-                      <emphasis>false</emphasis>.
-                  </para>
+	                  <para>
+	                      If set to <emphasis>true</emphasis>, failures to send to a
+	                      message channel will be ignored. If set to <emphasis>false</emphasis>,
+	                      a <classname>MessageDeliveryException</classname>  will
+	                      be thrown instead, and if the router resolves more than
+	                      one channel, any subsequent channels will not receive
+	                      the message.
+	                  </para>
+	                  <para>
+	                      The exact behavior of this attribute depends on the type
+	                      of the <code>Channel</code> messages are sent to. For
+	                      example, when using direct channels (single threaded),
+	                      send-failures can be caused by exceptions thrown by components
+	                      much further down-stream. However, when sending
+	                      messages to a simple queue channel (asynchronous) the
+	                      likelihood of an exception to be thrown is rather remote.
+	                  </para>
+	                  <note>
+	                      While most routers will route to a single channel, they
+	                      are allowed to return more than one channel name. The
+	                      <code>recipient-list-router</code>, for instance, does
+	                      exactly that.
+
+                          If you set this attribute to <emphasis>true</emphasis>
+                          on a router that only routes to a single channel, any
+                          caused exception is simply swallowed, which usually makes
+                          little sense to do. In that case it would be better to
+                          catch the exception in an error flow at the flow entry
+                          point.
+
+                          Therefore, setting the <code>ignore-send-failures</code>
+                          attribute to <emphasis>true</emphasis> usually makes
+                          more sense when the router implementation returns more
+                          than one channel name, because the other channel(s)
+                          following the one that fails would still receive the Message.
+	                  </note>
+	                  <para>
+	                      This attribute defaults to <emphasis>false</emphasis>.
+	                  </para>
                   </listitem>
               </varlistentry>
               <varlistentry><term><emphasis role="bold">timeout</emphasis></term>
diff --git a/spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-2.1.xsd b/spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-2.1.xsd
index 640129c9ec..27c50c3f75 100644
--- a/spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-2.1.xsd
+++ b/spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-2.1.xsd
@@ -1009,7 +1009,7 @@ endpoint itself is a Polling Consumer for a channel with a queue.
 						That property should be settable on the target payload instance. Exactly one of the 'value'
 						or 'expression' attributes must be provided as well. The former for a literal value to set,
 						and the latter for a SpEL expression to be evaluated. The root object of the evaluation
-						context is the Message that was returned from the flow initiated by this enricher. 
+						context is the Message that was returned from the flow initiated by this enricher.
 					</xsd:documentation>
 				</xsd:annotation>
 			</xsd:element>
@@ -2679,11 +2679,18 @@ endpoint itself is a Polling Consumer for a channel with a queue.
 		</xsd:attribute>
 		<xsd:attribute name="ignore-send-failures" default="false">
 			<xsd:annotation>
-				<xsd:documentation>
-					Specify whether a failure to send to a single channel should
-					be ignored. Otherwise MessageDeliveryExceptions will be thrown.
-					Defaults to false.
-				</xsd:documentation>
+				<xsd:documentation><![CDATA[
+					If set to "true", failures to send to a message channel will
+					be ignored. If set to "false", a MessageDeliveryException will be
+					thrown instead, and if the router resolves more than one channel,
+					any subsequent channels will not receive the message.
+
+					Please be aware that when using direct channels (single threaded),
+					send-failures can be caused by exceptions thrown by components
+					much further down-stream.
+
+					This attribute defaults to false.
+				]]></xsd:documentation>
 			</xsd:annotation>
 			<xsd:simpleType>
                 <xsd:union memberTypes="xsd:boolean xsd:string" />