Using Filters
Filters specify conditions that must be met for a message to be routed to a 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 services and flows. Global filters require the "name" attribute, whereas filters configured on endpoints or routers do not.
<!-- Globally defined filter with name attribute -->
<payload-type-filter name="payloadFilter" expectedType="java.lang.String" />
<model>
<service>
<inbound>
<tcp:inbound-endpoint host="locahost" port="1234">
<!-- Here we reference the filter defined globally using it for this endpoint -->
<filter ref="payloadFilter"/>
</tcp:inbound-endpoint>
</inbound>
<echo-component/>
<service>
</model>
<flow>
<tcp:inbound-endpoint host="locahost" port="1234">
<!-- Here we reference the filter defined globally using it for this endpoint -->
<filter ref="payloadFilter"/>
</tcp:inbound-endpoint>
<echo-component/>
</flow>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.
<payload-type-filter expectedType="java.lang.String"/>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.
<expression-filter evaluator="xpath" expression="(msg/header/resultcode)='success'"/>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. For querying XML, it is recommended to use XPath expressions instead.
<expression-filter evaluator="jxpath" expression="(msg/header/resultcode)='success'"/>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:
<expression-filter evaluator="ognl" expression="[MULE:0].equals(42)"/>or more simply:
<ognl-filter expression="[MULE:0].equals(42)"/>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 Payload Type Filter to the message using an And Filter to make sure the payload is a String.
<regex-filter pattern="the quick brown (.*)"/>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 Payload Type Filter to the message using an And Filter 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 *
<wildcard-filter pattern="the quick brown *"/>Exception Type Filter
A filter that matches an exception type.
<exception-type-filter expectedType="java.lang.RuntimeException"/>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.
<message-property-filter pattern="Content-Type=text/xml" caseSensitive="false"/>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 :
<and-filter>
<message-property-filter pattern="JMSCorrelationID=1234567890"/>
<message-property-filter pattern="JMSReplyTo=null"/>
</and-filter>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.
<and-filter>
<payload-type-filter expectedType="java.lang.String"/>
<regex-filter pattern="the quick brown (.*)"/>
</and-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 additional filters on Anypoint Exchange.
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:
public boolean accept(MuleMessage message);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:
<outbound>
<filtering-router>
<http:outbound-endpoint address="http://localhost:65071/services/EnterOrder?method=create" exchange-pattern="request-response"/>
<custom-filter class="org.mule.transport.http.filters.HttpRequestWildcardFilter">
<spring:property name="pattern" value="/services/EnterOrder?wsdl"/>
</custom-filter>
</filtering-router>
</outbound>