Filters
| Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version. |
Mule bundles more than a dozen Filters that determine whether a message can proceed through an application flow based on some condition or test.
There are filters to test the payload and properties of a message, an exception, or if a message is a duplicate of a previous message. Other filters let you quickly define more flexible tests, using MEL, schema validation, wildcard, regex expressions. Additional boolean logic filters such as and, or, and not help you link filters together to create more complex logical tests.
When to Use Filters
Most filters silently eliminate the tested message with no logging or reporting. This may not be desirable, especially for messages that have already progressed through several steps of a flow. Because of this behavior, filters are usually used immediately after a message source to filter out unwanted message types. For example, you might use filters immediately after an HTTP Listener to automatically reject request messages that don’t have a required payload type or some other required Metadata, or to otherwise automatically silently filter spurious requests that are definitely not intended for that Mule application flow.
Alternatives to using filters include using typical defensive coding techniques, such as using Choice routers to test a message for conditions, then routing the message to different flows based on certain logical conditions. If a condition indicates an error state, you can either handle the error and log the condition, or you could throw an exception from the flow for processing in a parent flow, or with a global exception handling strategy. Another option to test for exceptional conditions in a flow is to use a Validation component. Validation components are similar to filters, except they throw exceptions when the logical test fails.
Some filters include options to throw exceptions, and the Message filter wraps any other type of Filter so that you can call a compensating flow or throw an exception if the wrapped filter’s condition fails. While this is technically OK, you should always consider if Filters are the correct message processor for your use case, or if your flows will be more understandable by just using Choice routers, and then throwing exceptions with Validation components or directly with Java inside a Groovy component or other MEL expression.
Custom Filters
In addition to applying standard filters, you can create a custom filter to specify a precise set of conditions a message must satisfy before it can continue through the flow. Note that the reference is to a class implementing the Filter interface.
The Filter Class is required if you build global filter. See Filters Configuration Reference for details on how to work with this class.
Global Filters
You can create a global filter that specifies a set of conditions that the message must meet at points along the flow specified by the Filter Reference processor:
Drag the Filter Reference processor to the canvas, click the green plus sign to configure the filter, and click a filter type from the Choose Global Type menu. For more information, see Filter Reference.
Some Filtering Scenarios
Here are some use cases to demonstrate when you might or might not want to use filters vs. another option.
-
Checking for preconditions. The client has sent a message that does not meet the contract of the current flow (endpoint). This might be a reasonable case for a filter just after a connector.
For example, a filter could verify a message has some allowed header information, otherwise just silently discarded the message without logging or throwing an exception. The result is invalid client requests are ignored and no resources are used to track these invalid attempts. However, if the HTTP listener was listening for SOAP requests, if the message was invalid due to violating the WSDL definition, normally the expectation from the WSDL file is that this flow should return a SOAP Fault to the SOAP requestor. In this case filtering would be a bad idea.
If checking for early preconditions requires complex logic, with multiple filters, it is often more natural to express complex conditions and logic with choice routers which should then, in the individual branches, contain Filters or Validation components.
-
Checking for invariants. During the flow, just confirming what we think is true about how the message should look like. The disadvantage of using a filter is the error condition will cause the message to disappear without logging the message or throwing an exception. In this scenario, using a filter is usually a bad practice. It would be better to either correct the issue and move on in the flow, or throw an exception. A Validation component can perform similar logical tests as filters, but can then throw an exception if the test fails.
-
Checking for postconditions. Just before returning, assert that what should be returned from the flow matches our contract with the calling flow (client). Again, your use cases and business requirements will indicate if it is appropriate or not to silently discard a message in the last stages of a flow. Normally, you should not silently discard the message, but instead handle the issue or throw an exception. A Validation component can perform similar logical tests as filters, but can then throw an exception if the test fails.
| Filters | Description |
|---|---|
And, Or, Not |
These logic filters express simple logic. When required to express complex logic, these three filters can be used in combination with other filters. Reference: Logic Filter Reference |
Custom |
References a user-implemented filter class. Reference: Custom Filter Reference |
Exception |
Filters against an exception of a specified type. Reference: Exception Filter Reference |
Expression |
Filters against a range of expressions. |
Idempotent Message |
Ensures that a flow receives only unique messages. Reference: Idempotent Filter |
Message |
Applies specified criteria to a message to determine whether it should be processed. Reference: Message Filter Reference |
Message Property |
Applies a regular expression pattern to the message payload to determine whether it should be processed. Reference: Message Property Filter Reference |
Payload |
Evaluates the payload type of a message to determine whether it should be processed. |
Regex |
Applies a regular expression pattern to determine whether it should be processed. |
Schema Validation |
Uses the JAXP libraries, to validate a message against a schema. Reference: Schema Validation Filter Reference |
Wildcard |
Matches string messages against a wildcard pattern. Reference: Wildcard Filter Reference |
Filter Logic
When a message fails to satisfy the conditions specified by a filter, that filter returns a null value, which causes the processing of that particular message to halt. In other words, the message is rejected and undergoes no further processing.
When a message satisfies the conditions specified by a filter, that filter passes the payload of the message to the next processor in the flow, and processing of that particular message continues.
When you place a filter immediately after an HTTP endpoint configured for a request-response pattern, and no response has been configured for the flow, Mule uses as a response the result returned by the final message processor in the flow, which is null.
Configuring Filters
This section covers only those configuration activities common to all filters. For configuration activities that apply only to individual filters, click one of the links in the Reference column of the table Bundled Filters.
As for all Studio processors, you configure Filters in two major steps:
-
Drag the filter from the Palette to the Message Flow canvas, then set its position within the sequence of processors that make up the application flow.
-
Provide values for the required fields on the various tabs in the filter’s Properties Editor.
Filter Example
The following example creates an And filter:
<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns:http="http://www.mulesoft.org/schema/mule/http" xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:doc="http://www.mulesoft.org/schema/mule/documentation"
xmlns:spring="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
http://www.mulesoft.org/schema/mule/http http://www.mulesoft.org/schema/mule/http/current/mule-http.xsd">
<http:listener-config name="HTTP_Listener_Configuration" host="localhost" port="8081" doc:name="HTTP Listener Configuration"/>
<and-filter name="And" doc:name="And">
<and-filter/>
</and-filter>
<flow name="add_logicFlow">
<http:listener config-ref="HTTP_Listener_Configuration" path="/" doc:name="HTTP"/>
<filter ref="And" doc:name="Filter Reference"/>
</flow>
</mule>