Overview

In cases where it is not possible to effectively filter message via channel key filters, the application can programmatically register a MessageFilter class that is invoked prior to dispatching received or injected messages to your application. While MessageFilters are less efficient than channel filters, they can nevertheless have a big impact on improving performance because filtered messages are not added to the engine's transaction stream and can be acknowledged upstream sooner. 

Using Message Filters

A MessageFilter can be set on an AepEngine via its setMessageFilter method. The message filter operates on live messages received by an AepEngine operating in the primary role. A message filter does not apply to messages replicated by a peer or recovered from disk. Filtered messages are acknowledged and are not logged to a transaction logs.

Effects of a MessageFilter:

Filtered messages:

• Are acknowledged.
• Are not logged to the transaction log, inbound message log or replicated to cluster peers.
• Are not dispatched to application EventHandlers.
• Do not start new transactions or contribute to adaptive batching counts.
• Contribute to event received/processed and message received stats, but are accounted for in numMsgsFiltered. They do not undergo duplicate checking so filtered duplicates will not be accounted for duplicate counts.

Setting a MessageFilter on an AepEngine replaces the currently registered MessageViewFilter.

Message Filter Threading

The message filter is invoked from the same thread as application message handlers. Consequently they need not be coded in a thread safe fashion unless the application sets the same message filter instance on multiple AepEngines. 

Exceptions thrown from a MessageFilter:

If an exception is thrown by a MessageFilter, it is handled according to the AepEngine.AppExceptionHandlingPolicy for this engine. If the policy is AepEngine.AppExceptionHandlingPolicy.LogExceptionAndContinue, the message is not dispatched to application handlers and is acknowledged.

HA Considerations

Any processing done in a message filter is done outside of a transaction and the effects of processing done in a MessageFilter are not replicated to a backup. It is not legal for a MessageFilter to modify the appliaction's recoverable state. Applications using Event Sourcing should take particular care in this regard as it could lead to divergence between a primary and its backup(s).