Using Filters

Filters specify conditions that must be met for a message to be routed to a external service or continue progressing through a flow. There are several standard filters that come with Mule ESB that you can use, or you can create your own filters.

You can create a global filter and then reference it from your flows. Global filters require the "name" attribute, whereas filters configured on endpoints or routers do not.

For reference to the configuration of each filter, see Filters Configuration Reference.

Using in Flows

Filters return null if the condition is evaluated to false. Otherwise, they return the message. In the case of flows, a condition of false will halt the processing of the flow for that message. If the inbound endpoint defined on a Flow has a request-response exchange-pattern and there are no <response> blocks in your flow then the response used is simply the result from the last Message Processor in the flow, which will be null.

Standard Filters

Mule includes the following standard filters that you can apply to your routers:

Payload Type Filter

Checks the class type of the payload object inside a message.

Expression Filter

Evaluates a range of expressions. Use the evaluator attribute to specify the expression evaluator to use, one of the following: header, payload-type, exception-type, wildcard, regex, ognl, xpath, jxpath, bean, groovy, or custom. Use the expression attribute to set the actual expression. If the expression type is xpath, bean, or ognl, the expression should be a boolean. If the expression type is custom, set the customEvaluator attribute to the name of the custom evaluator, which must be registered with Mule (see Creating Expression Evaluators).

Optionally, set the nullReturnsTrue attribute to true if you want to return true whenever the expression is null.

Using XPath Expressions

XPath expressions are supported using the standard XPath query language. It is based on JAXP, the Java API for XML processing. You can learn more about writing XPath queries from the XPath tutorial.

You can also use the XPath Filter from the XML Module Reference, which supports some additional properties. Mule also provides a Jaxen XPath Filter based on the Jaxen library that may provide faster performance in some scenarios.

Using JXPath Expressions

JXPath is an XPath interpreter that can apply XPath expressions to graphs of objects of all kinds: JavaBeans, Maps, Servlet contexts, DOM etc, including mixtures thereof. For more information about JXPath, see the JXpath user guide, JXPath tutorial. For querying XML, it is recommended to use XPath expressions instead.

You can also use the JXPath filter from the XML Module Reference, which supports some additional properties.

Using OGNL Expressions

OGNL is a simple yet very powerful expression language for plain Java objects. Similar to JXPath, it works on object graphs, and thus the corresponding filter enables simple and efficient content routing for payloads. For example:

or more simply:

This filter would block any messages whose payloads are not arrays or lists and do not contain the value 42 as the first element.

RegEx Filter

Applies a regular expression pattern to the message payload. The filter applies toString() to the payload, so you might also want to apply a PayloadTypeFilter to the message using an AndFilter to make sure the payload is a String.

Wildcard Filter

Applies a wildcard pattern to the message payload. The filter applies toString() to the payload, so you might also want to apply a PayloadTypeFilter to the message using an AndFilter to make sure the payload is a String.

For the string "the quick brown fox jumped over the lazy dog", the following patterns would match:

• *x jumped over the lazy dog
• the quick*
• *fox*

Exception Type Filter

A filter that matches an exception type.

Message Property Filter

This filter allows you add logic to your routers based on the value of one or more properties of a message. This filter can be very powerful because the message properties are exposed, allowing you to reference any transport-specific or user-defined property. For example, you can match one or more HTTP headers for an HTTP event, match properties in JMS and email messages, and more.

By default, the comparison is case sensitive. You can set the caseSensitive attribute to override this behavior.

The expression is always a key value pair. If you want to use more complex expressions, you can use the logic filters. The following example shows two filters :

Logic Filters

There are three logic filters that can be used with other filters: And, Or, and Not. Logic filters can be nested so that more complex logic can be expressed.

And Filter

An And filter combines two filters and only accepts the message if it matches the criteria of both filters.

Or Filter

The Or filter considers two filters and accepts the message if it matches the criteria of either one of the filters.

Not Filter

A Not filter accepts the message if it does not match the criteria in the filter.

Transport and Module Filters

Several Mule transports and modules provide their own filters. For example, the XML Module Reference includes a filter to determine if a message is XML. For more information, see Transports Reference and Modules Reference. Also, there are filters on MuleForge that have been contributed by the community.

Creating Custom Filters

The standard filters handle most filtering requirements, but you can also create your own filter. To create a filter, implement the Filter interface, which has a single method:

This method returns true if the message matches the criteria that the filter imposes. Otherwise, it returns false.

You can then use this filter with the <custom-filter...> element, using the class attribute to specify the custom filter class you created and specifying any necessary properties using the <spring:property> child element. For example: