Message Filter

The Message Filter from the EIP patterns allows you to filter messages

The following example shows how to create a Message Filter route consuming messages from an endpoint called queue:a which if the Predicate is true will be dispatched to queue:b

Using the Fluent Builders

        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 Predicate languages such as XPath, XQuery, SQL or various Scripting Languages. Here is an XPath example

                from("direct:start").
                        filter().xpath("/person[@name='James']").
                        to("mock:result");

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

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 Spring XML Extensions

    <camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/spring">
        <route>
            <from uri="direct:a"/>
            <filter>
                <xpath>$foo = 'bar'</xpath>
                <to uri="direct:b"/>
            </filter>
        </route>
    </camelContext>

filtered endpoint required inside </filter> tag

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 junit test case

Using stop

Available as of Camel 2.0

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 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().

                from("direct:start")
                    .choice()
                        .when(body().contains("Hello")).to("mock:hello")
                        .when(body().contains("Bye")).to("mock:bye").stop()
                        .otherwise().to("mock:other")
                    .end()
                    .to("mock:result");

Knowing if Exchange was filtered or not

Available as of Camel 2.5

The Message Filter EIP will add a property on the Exchange which states if it was filtered or not.

The property has the key Exchannge.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 Exchange was routed in the filter block.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started, you may also find the Architecture useful particularly the description of Endpoint and URIs. Then you could try out some of the Examples first before trying this pattern out.