INT-676

spring-integration-reference/src/filter.xml

@@ -12,6 +12,10 @@
       to a router, except that for each Message received from the filter's input channel, that same Message may or may
       not be sent to the filter's output channel. Unlike the router, it makes no decision regarding
       <emphasis>which</emphasis> Message Channel to send to but only decides <emphasis>whether</emphasis> to send.
+      <note>
+        As you will see momentarily, the Filter does also support a discard channel, so in certain cases it
+        <emphasis>can</emphasis> play the role of a very simple router (or "switch") based on a boolean condition.
+      </note>
     </para>
     <para>
       In Spring Integration, a Message Filter may be configured as a Message Endpoint that delegates to some
@@ -39,24 +43,34 @@
       Alternatively, the "method" attribute can be added at which point the "ref" may refer to any object.
       The referenced method may expect either the <interfacename>Message</interfacename> type or the payload type of
       inbound Messages. The return value of the method must be a boolean value. Any time the method returns 'true',
-      the Message <emphasis>will</emphasis> be passed along to the output-channel. Otherwise, it will be dropped.
+      the Message <emphasis>will</emphasis> be passed along to the output-channel.
       <programlisting language="xml"><![CDATA[ <filter input-channel="input" output-channel="output"
          ref="exampleObject" method="someBooleanReturningMethod"/>
 
  <bean id="exampleObject" class="example.SomeObject"/>]]></programlisting>
     </para>
+    <para>
+      If the selector or adapted POJO method returns <code>false</code>, there are a few settings that control the
+      fate of the rejected Message. By default (if configured like the example above), the rejected Messages will
+      be silently dropped. If rejection should instead indicate an error condition, then set the
+      'throw-exception-on-rejection' flag to <code>true</code>:
+      <programlisting language="java"><![CDATA[ <filter input-channel="input" ref="selector"
+      output-channel="output" throw-exception-on-rejection="true"/> ]]></programlisting>
+	  If you want the rejected messages to go to a specific channel, provide that reference as the 'discard-channel':
+      <programlisting language="java"><![CDATA[ <filter input-channel="input" ref="selector"
+      output-channel="output" discard-channel="rejectedMessages"/> ]]></programlisting>
+    </para>
     <note>
-      A common usage for Message Filters is in conjunction with a publish/subscribe channel. Many filter endpoints may
+      A common usage for Message Filters is in conjunction with a Publish Subscribe Channel. Many filter endpoints may
       be subscribed to the same channel, and they decide whether or not to pass the Message for the next endpoint which
       could be any of the supported types (e.g. Service Activator). This provides a <emphasis>reactive</emphasis>
       alternative to the more <emphasis>proactive</emphasis> approach of using a Message Router with a single
-      point-to-point input channel and multiple output channels.
+      Point-to-Point input channel and multiple output channels.
     </note>
 	<para>
-     Using a "ref" attribute is generally recommended if the custom filter implementation can be reused in other
+      Using a "ref" attribute is generally recommended if the custom filter implementation can be reused in other
       <code>&lt;filter&gt;</code> definitions. However if the custom filter implementation should be scoped to a
-      concrete definition of the <code>&lt;filter&gt;</code>, starting with v1.0.3, Spring Integration supports inner
-      bean definitions for custom filters within the <code>&lt;filter&gt;</code> element:
+      single <code>&lt;filter&gt;</code> element, provide an inner bean definition:
 <programlisting language="xml"><![CDATA[<filter method="someMethod" input-channel="inChannel" output-channel="outChannel">
 	<beans:bean class="org.foo.MyCustomFilter"/>
 </filter>]]></programlisting>
@@ -64,10 +78,9 @@
     <note>
       <para>
         Using both the "ref" attribute and an inner handler definition in the same <code>&lt;filter&gt;</code> configuration
-        is not allowed, as it creates an ambiguous condition and will result in Exception being thrown.
+        is not allowed, as it creates an ambiguous condition, and it will therefore result in an Exception being thrown.
       </para>
     </note>
-
   </section>
 
 </chapter>