ColdBox Interceptors

ColdBoxInterceptors

Brad Woodwww.codersrevolution.combrad@bradwood.com

What is an interceptor?

 An encapsulated piece of logic that “listens” to events that happen during the life-cycle of your application.

It allows for loose coupling, cross cutting concerns, and implicit chain-able execution points.

Interception points can be tapped into without modifying the core code of your application.

What is an interceptor?

Interceptors follow the model of event-driven programming.

Also known as The Hollywood principle-  “Don’t call us, we’ll call you.” 

What is an interceptor?

There are a number of baked-in interception points that the ColdBox framework broadcasts that can give you AOP-style “before” or “after” filters.

Your application can declare and announce custom interception points which model the observer/observable pattern.

Multiple listeners for the same event (or interception point) will be chained together in the order of declaration. 

Core Interception Points

A sample of Interception points that ColdBox announces out-of-the-box:

• afterConfigurationLoad• preProcess• postProcess• preEvent• postEvent• preRender• afterCacheElementInsert• onException

What are they good for?

   • Security• Method Tracing• AOP Interceptions like Cache advices on

insert and remove• Publisher/Consumer operations• Content Appending or Pre-Pending• View Manipulations• Custom SES support

Creating an Interceptor

  myInterceptor.cfc

 <cfcomponent displayname="myInterceptor" extends="coldbox.system.interceptor"         output="false">    <cffunction name="preProcess" output="true">       <cfargument name="event" required="true">       <cfargument name="interceptData" required="true">         <!--- Do some really awesome stuff here --->   </cffunction> </cfcomponent>

Creating an Interceptor

coldbox.cfc    interceptors =      [            {                  class="path.to.myInterceptor"            }      ];

Create a custom interception point

 coldbox.cfc interceptorSettings =      {            throwOnInvalidStates = false,            customInterceptionPoints = "refreshContentHierarchy"      };           ...   interceptors =      [            {                  class="interceptors.contentHierarchySynch",                  properties={}            }   ]; 

Create a custom interception point

 contentHierarchySynch.cfc  <cfcomponent displayname="contentHierarchySynch"       extends="coldbox.system.interceptor" output="false" singleton="true">   <cfproperty name="contentService" inject="model:contentService">      <cffunction name="refreshContentHierarchy" access="public" output="false">       <cfargument name="event">       <cfargument name="interceptData">                   <cfif not interceptData.justKidding>                  <cfset contentService.contentXrefNodeBackfill()>            </cfif>   </cffunction> </cfcomponent>  

Create a custom interception point

  Somewhere in my handlers ...   var interceptData = {};interceptData.justKidding = false;announceInterception('refreshContentHierarchy', interceptData);  Somewhere in my model...

var interceptData = {};interceptData.justKidding = true;interceptorService.processState("refreshContentHierarchy",interceptData);

Interceptor Properties

You can include properties in the config when you declare an interceptor.  These properties are available during execution to control how the interceptor behaves. {      class="coldbox.system.interceptors.Autowire",      properties =                        {                              debugMode="false",                              enableSetterInjection="false"                        }}

Interceptor Properties

 Interceptors can use these properties with built-in functions including: • propertyExists()• getProperty(name)• setProperty(name, value)

if(!properyExists("configFile"))    {            setProperty("configFile","defaultConfig.cfc")    } loadConfig(getProperty("configFile"));

Interceptor chaining

If multiple interceptors are listening to the same interception point they will be chained together and executed in the order they are declared in the config.  

Any interceptor can break the chain by returning a value of true. preProcess 1 (Returns false or void)preProcess 2 (Returns false or void)preProcess 3 (Returns true)preProcess 4 (Doesn't get executed)

Interceptor chaining

ColdBox also supplies each execution chain with a buffer object that can be appended to.  Any content in the buffer at the end of the execution chain will be flushed out to the page. <cffunction name="preRender" access="public" returntype="boolean" output="false" >      <cfargument name="event" required="true">      <cfargument name="interceptData" required="true">            <cfscript>            //clear all of it first            clearBuffer();            //Append to buffer            appendToBuffer('I want this text at the bottom of every page.');          </cfscript>    </cffunction>

Code Examples

  •Form Parser

•JavaScript Defer

•Browser Snob

•SES

Questions?• Brad Wood• www.codersrevolution.com• brad@bradwood.com

• Mailing List: groups.google.com/group/coldbox

• Docs: http://wiki.coldbox.org/wiki/Interceptors.cfm

• Website:http://www.coldbox.org/