What's the difference between event-filters and plugins?

Introduction

Filters and Plugins are two common components of MachII applications. Because of their somewhat similar nature, newcomers sometimes get mixed up with regard to the purpose that each one serves. First of all, both Filters and Plugins are nothing more than standard CFC's, the first difference between them being that filters extend MachII.framework.EventFilter and plugins extend MachII.framework.Plugin.

Filters

Filters are a common component in MachII applications which enable per-event flow control, and are easily added to Mach-II events through a single line in the XML configuration file. A simple example would be the addition of security or logging to a specific Mach-II event, or conditionally redirecting to a different event based on some value. By developing a filter and adding this filter to the event, this additional functionality can be added to or removed from the event without touching the business logic involved.

Plugins

A plugin is a developer-defined CFC that extends the Mach-II framework. The plugin architecture provides robust extensibility for plugin points for cross-cutting event actions. This means each defined plugin point fires on every request and matching point area. Plugins are useful for executing application wide business login such as loading locale resource bundles before views, checking that the request is secured through SSL or loading specific args into the eventobject on each request.

The Difference

The major difference in functionality between the two is that filters are called on a per-event basis as determined by the developer, whereas plugins are called on every single request. Thus, if you're looking to implement a piece of logic that will run of every request, it belongs in a plugin. If the logic you're looking to implement should only be triggered on specific events, a filter is likely the best candidate. To elaborate, let's start by looking at how each is defined in the mach-ii.xml configuration file.

Defining filters and plugins

Mach-II configuration file fragment:

<mach-ii>
	<event-filters>
		<event-filter name="myFilter" type="dot.delimited.path.to.myFilter" />
	</event-filters>

	<plugins>
		<plugin name="myPlugin" type="dot.delimited.path.to.myPlugin" />
	</plugins>
</mach-ii>

As you can see, it is very simple to register your filters and plugins in the mach-ii.xml configuration file. The name attribute of both the <event-filter> and <plugin> nodes allows you to associate a handle with the filter or plugin for use elsewhere in the mach-ii.xml configuration file, while the type attribute should have a value of a dot delimited path to the filter or plugin CFC (i.e. filters.LoginFilter).

Defining configure-time parameters for filters and plugins

Although not always required, both filters and plugins can declare configuration-time parameters. These additional parameters are then made available for use in the filter or plugin CFC. They can be used to change the behavior of the filter or plugin. This allows the filter or plugin to act differently based on the context of the application, but also be reused in many applications with same source code. As you can see below, the combination of <parameters> and <parameter> nodes are used to define these parameters.

<event-filters>
	<event-filter name="myFilter" type="dot.delimited.path.to.myFilter">
		<parameters>
			<parameter name="myParamName" value="myParamValue" />
		</parameters>
	<event-filter>
</event-filters>

<plugins>
	<plugin name="myPlugin" type="dot.delimited.path.to.myPlugin">
		<parameters>
			<parameter name="myParamName" value="myParamValue" />
		</parameters>
	</plugin>
</plugins>

These configure-time parameters are available for use within any of the filter or plugin methods. You can access the parameters by using these methods:

Method	Description
getParameter	Gets a configuration parameter value, or a default value if not defined.
getParameters	Gets the full set of configuration parameters for the component.
isParameterDefined	Checks to see whether or not a configuration parameter is defined.

Because plugins are called automatically by Mach-II at specific points during every request, the only configuration needed in the mach-ii.xml file to actually register them as illustrated above. Again, the reason for this is that Mach-II itself will handle the calling of the plugin on its own. Upon developing the plugin CFC, you will find that this strategy offers excellent flexibility as you have the ability to define specific functionality at each of nine plugin points in a request. Plugins typically perform "cross-cutting concerns" (i.e. logging, pulling data into the event at the beginning of every request, handling exceptions, etc.) as the all plugin points are called on each request. The full functionality of plugins is covered in more detail in the Introduction to Plugins article, but here are the available plugin points that are called automatically by Mach-II:

• preProcess
• preEvent
• postEvent
• preView
• postView
• postProcess
• handleException

Plugin points added in Mach-II 1.6 and requires use of Application.cfc and the MachII.mach-ii bootstrapper:

• onSessionStart
• onSessionEnd

Filters, on the other hand, are not called automatically by Mach-II on every request, you as the developer must define which events should trigger which filters. This is done by using the <filter> command in the <event-handler> node defined in the mach-ii.xml configuration file.

<event-handler event="myEvent" access="public">
	<filter name="myFilter" />
	<!-- additional processing -->
	<notify listener="myListener" method="myMethod" resultArg="myVar"/>
	<view-page name="myPage"/>
</event-handler>

Defining run-time parameters for filters only

While filters and plugins can both define and use configure-time parameters, since plugins are called automatically by Mach-II, defining run-time parameters are not an option. Filters, however, do offer run-time parameter declarations, which are defined by the <parameter> tag and nested within the <filter> node. Note that <parameter> are not wrapped in a <parameters> tag. Instead the <parameter> tags are nested within the <filter> tag directly.

<event-handler event="myEvent" access="public">
	<filter name="myFilter">
		<parameter name="myRunTimeParamName" value="myValue" />
	</filter>
	<!-- additional processing -->
	<notify listener="myListener" method="myMethod" resultArg="myVar"/>
	<view-page name="myPage"/>
</event-handler>

Conclusion

Filters and Plugins both offer the powerful ability to intercept the processing of requests. Filters are triggered by the developer on an individual event basis, while plugins are called automatically by Mach-II at nine different plugin points on each request. For more information on each, please refer to the Introduction to Filters and Introduction to Plugins documents.

Back to FAQs

---

Special thanks to Brian FitzGerald for initially contributing this FAQ.