## Filter EIP
### Message Filter

The http://www.enterpriseintegrationpatterns.com/Filter.html[Message
Filter] from the link:enterprise-integration-patterns.html[EIP patterns]
allows you to filter messages

image:http://www.enterpriseintegrationpatterns.com/img/MessageFilter.gif[image]

The following example shows how to create a Message Filter route
consuming messages from an endpoint called *queue:a*, which if the
link:predicate.html[Predicate] is true will be dispatched to *queue:b*

### EIP options

// eip options: START
The Filter EIP supports 0 options which are listed below:
// eip options: END


*Using the link:fluent-builders.html[Fluent Builders]*

[source,java]
----------------------------------------------------------------------------
RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        errorHandler(deadLetterChannel("mock:error"));
 
        from("direct:a")
            .filter(header("foo").isEqualTo("bar"))
                .to("direct:b");
    }
};
----------------------------------------------------------------------------

You can, of course, use many different link:predicate.html[Predicate]
languages such as link:xpath.html[XPath], link:xquery.html[XQuery],
link:sql.html[SQL] or various link:scripting-languages.html[Scripting
Languages]. Here is an
http://svn.apache.org/repos/asf/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/XPathFilterTest.java[XPath
example]

[source,java]
----------------------------------------------------------------------------
from("direct:start").
        filter().xpath("/person[@name=&#39;James&#39;]").
        to("mock:result");
----------------------------------------------------------------------------

Here is another example of using a bean to define the filter behavior

[source,java]
----------------------------------------------------------------------------
from("direct:start")
    .filter().method(MyBean.class, "isGoldCustomer").to("mock:result").end()
    .to("mock:end");

public static class MyBean {
    public boolean isGoldCustomer(@Header("level") String level) { 
        return level.equals("gold"); 
    }
}
----------------------------------------------------------------------------

*Using the link:spring-xml-extensions.html[Spring XML Extensions]*

You can also use a method call expression (to call a method on a bean)
in the Message Filter, as shown below:

[source,xml]
----------------------------------------------------------------------------
<bean id="myBean" class="com.foo.MyBean"/>
<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="direct:a"/>
        <filter>
            <method ref="myBean" method="isGoldCustomer"/>
            <to uri="direct:b"/>
        </filter>
    </route>
</camelContext>
----------------------------------------------------------------------------


INFO:make sure you put the endpoint you want to filter (<to uri="seda:b"/>,
etc.) before the closing </filter> tag or the filter will not be applied
(in 2.8+, omitting this will result in an error)

For further examples of this pattern in use you could look at the
http://svn.apache.org/viewvc/camel/trunk/camel-core/src/test/java/org/apache/camel/processor/FilterTest.java?view=markup[junit
test case]

#### *Using stop*

Stop is a bit different than a message filter as it will filter out all
messages and end the route entirely (filter only applies to its child
processor). Stop is convenient to use in a
link:content-based-router.html[Content Based Router] when you for
example need to stop further processing in one of the predicates.

In the example below we do not want to route messages any further that
has the word `Bye` in the message body. Notice how we prevent this in
the when predicate by using the `.stop()`.

#### Knowing if link:exchange.html[Exchange] was filtered or not

*Available as of Camel 2.5*

The link:message-filter.html[Message Filter] EIP will add a property on
the link:exchange.html[Exchange] that states if it was filtered or not.

The property has the key `Exchange.FILTER_MATCHED`, which has the String
value of `CamelFilterMatched`. Its value is a boolean indicating `true`
or `false`. If the value is `true` then the link:exchange.html[Exchange]
was routed in the filter block. This property will be visible within the
link:message-filter.html[Message Filter] block who's
link:predicate.html[Predicate] matches (value set to `true`), and to the
steps immediately following the link:message-filter.html[Message Filter]
with the value set based on the results of the last
link:message-filter.html[Message Filter] link:predicate.html[Predicate]
evaluated.

#### Using This Pattern

If you would like to use this EIP Pattern then please read the
link:getting-started.html[Getting Started], you may also find the
link:architecture.html[Architecture] useful particularly the description
of link:endpoint.html[Endpoint] and link:uris.html[URIs]. Then you could
try out some of the link:examples.html[Examples] first before trying
this pattern out.
