Mach II Development Guide - Designing Plugins

Release 1.2.1 (4/14/2005)

« Designing Event Filters | Contents | Revision History »

Printable Version

Designing Plugins For Mach II

This section looks at designing and using plugins.

Anatomy Of A Plugin

A plugin is a component that provides methods which are called with the current eventContext (an object of type MachII.framework.EventContext) at various points in the lifecycle of a request:

1. preProcess() - called at the start of each request: the eventContext has the current event in the event queue but getCurrentEvent() will not yet return that event (see Processing The First Event In A Request below).
2. preEvent() - called for each event, immediately prior to execution of the relevant event-handler tag: the eventContext contains the current event (the one that is about to be handled).
3. preView() - called for each view, immediately prior to execution of the relevant view-page tag: the eventContext contains the current event (the one that is being executed).
4. postView() - called for each view, immediately after execution of the relevant view-page tag: the eventContext contains the current event (the one that is being executed).
5. postEvent() - called for each event, immediately after execution of the relevant event-handler tag: the eventContext contains the current event (the one that has just been handled).
6. postProcess() - called at the end of each request: the eventContext no longer contains an event.
7. handleException() - called whenever an exception is thrown back to the framework: the eventContext contains the current event (if there is one). This plugin method is also passed the exception object (of type MachII.util.Exception).

A plugin can define a configure() method if it needs to perform initialization - this is called automatically by the framework. Plugins - like all other parts of the Mach II framework - are stored in application scope so their instance variables are effectively application scope variables.

A minimal plugin CFC might look like this:

<cfcomponent extends="MachII.framework.Plugin">
	<cffunction name="configure" returntype="void" access="public" output="false">
		<!--- perform any initialization --->
	</cffunction>
	<cffunction name="preEvent" returntype="void" access="public" output="false">
		<cfargument name="eventContext" type="MachII.framework.EventContext" required="yes" />
		<!--- perform processing prior to every event being handled --->
	</cffunction>
</cfcomponent>

This plugin overrides just the preEvent() method but it could override any of the seven of the methods listed above.

The plugin is declared inside the <plugins> .. </plugins> tags in mach-ii.xml as follows:

<plugin name="pluginName" type="Path.To.YourPlugin" />

You may optionally specify parameters for the plugin declaration:

<plugin name="pluginName" type="Path.To.YourPlugin">
	<parameters>
		<parameter name="param1" value="value1" />
		<parameter name="param2" value="value2" />
	</parameters>
</plugin>

This provides default parameter values for param1 and param2 (of value1 and value2 respectively). These can be accessed within the plugin using the getParameter() method, e.g., getParameter("param1").

The handleException() Plugin Point

You can let the framework handle exceptions by using the exception event and using a single event handler. For many applications this will be perfectly acceptable. You can also add custom exception handling to an application by implementing the handleException() method on a plugin. This plugin point is executed after an exception is encountered, before the exception event is announced and handled. After executing this plugin point, the event queue is cleared and the specified exceptionEvent (from the <properties> section of mach-ii.xml) is announced and handled.

You should not throw an exception from handleException() nor call abortEvent() - both operations will lead to an unhandled exception that will be displayed to the end user. You cannot announce a new event (since the event queue is cleared after handleException() has been executed). You can add information to the current event object which can then be retrieved in the exception event handler:

<cfif arguments.eventContext.hasCurrentEvent()>
	<cfset arguments.eventContext.getCurrentEvent().setArg("argName",argValue) />
</cfif>

This will set the event argument argName to the value argValue if an event was defined when the exception was encountered.

Inside the exception event handler, the current event is the exception event itself which has the following arguments:

• exception - the MachII.util.Exception object containing details of the original exception
• exceptionEvent - the MachII.framework.Event object that was being handled when the exception was thrown (this is only present if there was a current event defined when the exception occurred)

You can use <event-mapping> to provide finer-grained control over Exception Handling in event handlers.

Processing The First Event In A Request

Since the "current event" is not set by the time preProcess() is invoked, it is might not be obvious how to process just the first event in each request:

<cffunction name="preProcess" returntype="void">
	<cfargument name="eventContext" type="MachII.framework.EventContext" />
	<!--- peek at the first event in the queue: --->
	<cfset var firstEvent = arguments.eventContext.getNextEvent() />
	<!--- ...process firstEvent here... --->
</cffunction>

Note: prior to 1.0.9, the above call to getNextEvent() would remove the first event from the queue!

« Designing Event Filters | Contents | Revision History »

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/wtg/public/machiidevguide/plugins.html

Add Comment