Interceptors are CFCs that extend the ColdBox Interceptor class (coldbox.system.Interceptor), implement a configuration method called configure(), and then contain methods for the events it will listen for. All interceptors are treated as singletons in your application, so make sure they are thread safe and var scoped.

/**
* My Interceptor
*/
component extends="coldbox.system.Interceptor"{

    function configure(){}

    function preProcess( event, interceptData, buffer, rc, prc ){}
}

Info You can also remove the inheritance from the CFC (preferred method) and WireBox will extend the coldbox.system.Interceptor for you using Virtual Inheritance.

You can use CommandBox to create interceptors as well:

coldbox create interceptor help

Registration

Interceptors can be registered in your Coldbox.cfc configuration file using the interceptors struct, or they can be registered manually via the system's interceptor service.

In ColdBox.cfc:

// Interceptors registration
interceptors = [
    {
        class   = "cfc.path", //by default this should be interceptors.yourcfcname  
        name    = "unique name/wirebox ID",
        properties = {
            // configuration
        }
    }
];

Registered manually:

controller.getInterceptorService().registerInterceptor( interceptorClass="cfc.path" );

The configure() Method

The interceptor has one important method that you can use for configuration called configure(). This method will be called right after the interceptor gets created and injected with your interceptor properties.

Info These properties are local to the interceptor only!

As you can see on the diagram, the interceptor class is part of the ColdBox framework super type family, and thus inheriting the functionality of the framework.

There are many interception points that occur during an MVC and Remote life cycle in a ColdBox application. We highly encourage you to follow our flow diagrams in our ColdBox Overview section so you can see where in the life cycle these events fire. Also remember that each event can pass a data structure that can be used in your application.

You can also register CFCs as interceptors programmatically by talking to the application's Interceptor Service that lives inside the main ColdBox controller. You can access this service like so:

// via the controller
controller.getInterceptorService();

// dependency injection
property name="interceptorService" inject="coldbox:interceptorService";

Once you have a handle on the interceptor service you can use the following methods to register interceptors:

• registerInterceptor() - Register an instance or CFC path and discover all events it listens to by conventions

• registerInterceptionPoint() - Register an instance in a specific event only

Here are the method signatures:

public any registerInterceptor([any interceptorClass], [any interceptorObject], [any<struct> interceptorProperties='[runtime expression]'], [any customPoints=''], [any interceptorName])

public any registerInterceptionPoint(any interceptorKey, any state, any oInterceptor)

Examples

// register yourself to listen to all events declared
controller.getInterceptorService()
    .registerInterceptor( interceptorObject=this );

// register yourself to listen to all events declared and register new events: onError, onLogin
controller.getInterceptorService()
    .registerInterceptor( interceptorObject=this, customPoints="onError,onLogin" );

// Register yourself to listen to the onException event ONLY
controller.getInterceptorService()
    .registerInterceptionPoint( 
        interceptorKey="MyService", 
        state="onException", 
        oInterceptor=this
     );

By convention, any interceptor CFC must create a method with the same name as the event they want to listen to. This method has a return type of boolean and receives 3 arguments. So let's explore their rules.

boolean function {point}( event, interceptData, buffer, rc, prc );

Arguments

• event which is the request context object

• interceptData which is a structure of data that the broadcaster sends

• buffer which is a request buffer object you can use to elegantly produce content that is outputted to the user's screen

• rc reference to the request collection struct

• prc reference to the private request collection struct

Return type

The intercepting method returns boolean or void. If boolean then it means something:

• True means break the chain of execution, so no other interceptors in the chain will fire.

• False or void continue execution

component extends="coldbox.system.Interceptor"{

    function configure(){}

    boolean function afterConfigurationLoad(event,interceptData,buffer){
        if( getProperty('interceptorCompleted') eq false){
            parseAndSet();    
            setProperty('interceptorCompleted',true);
        }

        return false;
    }
}

Also remember that all interceptors are created by WireBox, so you can use dependency injection, configuration binder's, and even AOP on interceptor objects. Here is a more complex sample:

HTTP Security Example:

/**
* Intercepts with HTTP Basic Authentication
*/
component {

    // Security Service
    property name="securityService" inject="id:SecurityService";

    void function configure(){
        if( !propertyExists("enabled") ){
            setProperty("enabled", true );
        } 
    }

    void function preProcess(event,struct interceptData, buffer){

        // verify turned on
        if( !getProperty("enabled") ){ return; }

        // Verify Incoming Headers to see if we are authorizing already or we are already Authorized
        if( !securityService.isLoggedIn() OR len( event.getHTTPHeader("Authorization","") ) ){

            // Verify incoming authorization
            var credentials = event.getHTTPBasicCredentials();
            if( securityService.authorize(credentials.username, credentials.password) ){
                // we are secured woot woot!
                return;
            };

            // Not secure!
            event.setHTTPHeader(name="WWW-Authenticate",value="basic realm=""Please enter your username and password for our Cool App!""");

            // secured content data and skip event execution
            event.renderData(data="<h1>Unathorized Access<p>Content Requires Authentication</p>",statusCode="401",statusText="Unauthorized")
                .noExecution();
        }    

    }    

}

Interceptors can be declared in the Coldbox.cfc configuration file or programmatically at runtime. If you register them in the configuration file, then you have control over the order in which they fire. If you register interceptors programmatically, you won't have control over the order of execution.

In the configuration file, interceptors are declared as an array of structures in an element called interceptors. The elements of each interceptor structure are:

• class - The required instantiation path of the CFC.

• name - An optional unique name for the interceptor. If this is not passed then the name of the CFC will be used. We highly encourage the use of a name to avoid collisions.

• properties - A structure of configuration properties to be passed to the interceptor

In ColdBox.cfc:

// Interceptors registration
interceptors = [
    { 
        class = "cfc.path",
        name = "unique name/wirebox ID",
        properties = { 
            // configuration
        }
    }
];

Example

// Interceptors registration
interceptors = [
    {
        class="coldbox.system.interceptors.SES",
        properties={}
    },
    {
        class="interceptors.RequestTrim",
        properties={
            trimAll=true
        }
    },
    {
        class="coldbox.system.interceptors.Security",
        name="AppSecurity",
        properties={
            rulesSource="model",
            rulesModel="securityRuleService@cb",
            rulesModelMethod="getSecurityRules",
            validatorModel="securityService@cb"
        }
    }
];

Info Remember that order is important!

Interceptors are CFC listeners that react on incoming events. Events can be announced by the core framework or be custom events from your application. These interceptors can also be stacked to form interceptor chains that can be executed implicitly for you. This is a powerful feature that can help developers and framework contributors share and interact with their work. (Read more on Intercepting Filters)

Event Driven Programming

The way that interceptors are used is usually referred to as event-driven programming, which can be very familiar if you are already doing any JavaScript or AngularJS coding. You can listen and execute intercepting points anywhere you like in your application, you can even produce content whenever you announce:

Custom Announcements

<!-- Announce an event in the div and produce content -->
<div>#announceInterception( 'onSidebar' )#</div>

// Announce inside a function
if( userCreated ){
    announceInterception( 'onUserCreate', { user = prc.oUser } );
}

If you are familiar with design patterns, custom interceptors can give you an implementation of observer/observable listener objects, much like any event-driven system can provide you. In a nutshell, an observer is an object that is registered to listen for certain types of events, let's say as an example onError is a custom interception point and we create a CFC that has this onError method. Whenever in your application you announce or broadcast that an event of type onError occurred, this CFC will be called by the ColdBox interceptor service.

Interceptor Example

component extends="coldbox.system.Interceptor"{

    function onError( event, interceptData={} ){
        // Listen to onError events
    }

}

Resources

• http://en.wikipedia.org/wiki/Observer_pattern

• http://sourcemaking.com/design_patterns/observer

• http://java.sun.com/blueprints/corej2eepatterns/Patterns/InterceptingFilter.html

For what can I use them

Below are just a few applications of ColdBox Interceptors:

• Security

• Event based Security

• Method Tracing

• AOP Interceptions

• Publisher/Consumer operations

• Implicit chain of events

• Content Appending or Pre-Pending

• View Manipulations

• Custom SES support

• Cache advices on insert and remove

• Much much more...

  *

You can restrict the execution of an interception point by using the eventpattern annotation. This annotation will be placed in the function and the value is a regular expression that the interceptor service uses to match against the incoming event. If the regex matches, the interception function executes, else it skips it. This is a great way for you to create interceptors that only fire not only for the specific interception point you want, but also on the specific incoming event.

also announces several other events in the object creation life cycles, so please see

Our caching engine, , also announces several events during its life cycle, so please see The as well.

The last piece of the puzzle is how to announce events. You will do so via the inherited super type method announceInterception() that all your handlers,plugins and even the interceptors themselves have or via the interceptor service processState() method. This method accepts an incoming data struct which will be broadcasted alongside your event:

// Announce with no data
announceInterception( "onExit" );

// Announce with data
announceInterception( 'onLog', {
    time = now(),
    user = event.getValue( "user" ),
    dataset = prc.dataSet
} );

// Announce via interceptor service
controller.getInterceptorService().processState( "onRecordInsert", {} );

Hint Announcing events can also get some asynchronous love, read the Interceptor Asynchronicity for some asynchronous love.

Once your custom interception or event points are registered and CFC are registered then you can write the methods for listening to those events just like any other interceptor event:

component{

    function onLog(event,interceptData,buffer){
        // your code here
    }

    function onRecordInserted(event,interceptData,buffer){
        // your code here
    }

}

Every interception point receives a unique request output buffer that can be used to elegantly produce output. Once the interception point is executed, the interceptor service will check to see if the output buffer has content, if it does it will advice to write the output to the ColdFusion output stream. This way, you can produce output very cleanly from your interception points, without adding any messy-encapsulation breaking output=true tags to your interceptors. (BAD PRACTICE). This is an elegant solution that can work for both core and custom interception points.

// Using methods, meaning you inherited from Interceptor or registered at configuration time.
function preRender( event, interceptData, buffer, rc, prc ){
    //clear all of it first, just in case.
    arguments.buffer.clear();
    //Append to buffer
    arguments.buffer.append( '<h1>This software is copyright by Funky Joe!</h1>' );    
}

Hint Each execution point will have its own clean buffer to work with. As each interception point has finalized execution, the output buffer is flushed, only if content exists.

Output Buffer Argument

Here are some examples using the buffer argument:

function onSidebar( event, interceptData, buffer, rc, prc ){
    savecontent variable="local.data"{
        /// HTML HERE
    }

    arguments.buffer.append( local.data );
}

// using argument
function preRender( event, interceptData, buffer, rc, prc ){
    //clear all of it first, just in case.
    arguments.buffer.clear();
    //Append to buffer
    arguments.buffer.append('<h1>This software is copyright by Funky Joe!</h1>');    
}

Here are some common methods on the buffer object:

• append( str ) Append strings to the buffer

• clear() Clear the entire buffer

• length() Get size of the buffer

• getString() Get the entire string in the buffer

• getBufferObject() Get the actual java String Builder object

You can use the interceptor service to register new events or interception points via the appendInterceptionPoints() method. This way you can dynamically register events in your system:

public any appendInterceptionPoints( array or list customPoints )

The value of the customPoints argument can be a list or an array of interception points to register so the interceptor service can manage them for you:

controller.getInterceptorService()
    .appendInterceptionPoints( [ "onLog", "onError", "onRecordInserted" ] );

In addition to all the events announced by the framework, you can also register your own custom events.

Curt Gratz shares a brief example and use case for ColdBox custom interception points in his video ColdBox Custom Interception Points - How To.

In the ColdBox.cfc configuration file, there is a structure called interceptorSettings with two keys:

• throwOnInvalidStates - This tells the interceptor service to throw an exception if the state announced for interception is not valid or does not exist. By default it does not throw an exception but ignore the announcement.

• customInterceptionPoints - This key is a comma delimited list of custom interception points you will be registering for execution.

//Interceptor Settings
interceptorSettings = {
    throwOnInvalidStates = false,
    customInterceptionPoints = "onLogin,onWikiTranslation,onAppClose"
};

The customInterceptionPoints is what interest us. This can be a list or an array of events your system can broadcast. This way, whenever interceptors are registered, they will be inspected for those events.

There are several reporting and utility methods in the interceptor service that I recommend you explore. Below are some sample methods:

The third use case is exactly the same scenario as the async listeners but with the exception that the caller will not wait for the spawned threads at all. This is accomplished by using the asyncAllJoin=false flag. This tells ColdBox to just spawn, return back a structure of thread information and continue execution of the calling code.

Configuration Arguments

You can also combine this call with the following arguments:

• asyncPriority : The priority level of each of the spawned threads. By default it uses normal priority level

The second use case is where you want to run the interception but multi-thread all the interceptor CFCs that are listening to that interception point. So let's say we have our onPageCreate announcement and we have 3 interceptors that are listening to that interception point. Then by using the asyncAll=true argument, ColdBox will create 3 separate threads, one for each of those interceptors and execute their methods in their appropriate threads. This is a great way to delegate long running processes simultaneously on a specific piece of data. Also, by default, the caller will wait for all of those 3 threads to finalize before continuing execution. So it is a great way to process data and wait until it has become available.

Caution Please remember that you are also sharing state between interceptors via the event and interceptData, so make sure you either lock or are careful in asynchronous land.

Configuration Arguments

You can also combine this call with the following arguments:

• asyncPriority : The priority level of each of the spawned threads. By default it uses normal priority level

• asyncJoinTimeout : The timeout in milliseconds to wait for all spawned threads. By default it is set to 0, which waits until ALL threads finalize no matter how long they take.

• asyncAllJoin : The flag that determines if the caller should wait for all spawned threads or should just spawn all threads and continue immediately. By default, it waits until all spawned threads finalize.

We have also extended the interceptor registration process so you can annotate interception points to denote threading. You will do so with the following two annotations:

This allows you the flexibility to determine in code which points are threaded, which is a great way to use for emails, logging, etc.

function preProcess( event, interceptData ) async asyncPriority="low"{
    // Log current request information
    log.info("Executing request: #event.getCurrentEvent()#", getHTTPRequestData() );    
}

So if you have 3 interceptors in a chain and only 1 of them is threaded, then the 2 will execute in order while the third one in the background. Overall, your processing power and choices have now grown.

Each interceptor can unregister itself from any event by using the unregister( state ) method. This method is found in all Interceptors or can be accessed via the interceptor service as well.

The first case involves where you want to completely detach an interception call into the background. You will accomplish this by using the async=true argument. This will then detach the execution of the interception into a separate thread and return to you a structure containing information about the thread it created for you. This is a great way to send work jobs, emails, processing and more to the background instead of having the calling thread wait for execution.

Configuration Arguments

You can also combine this call with the following arguments:

• asyncPriority : The priority level of the detached thread. By default it uses normal priority level.

In honor of one of my favorite bands and album, The Police - Synchronicity, we have some asynchronous capabilities in ColdBox Interceptors. These features are thanks to the sponsorship of Guardly, Inc, Alert, Connect, Stay Safe. So please make sure to check them out and thank them for sponsoring this great feature set. The core interceptor service and announcement methods have some arguments that can turn asynchronicity on or off and can return a structure of threading data.

any announceInterception(state, interceptData, async, asyncAll, asyncAllJoin, asyncJoinTimeout, asyncPriority);

The asynchronous arguments are listed in the table below:

All asynchronous calls will return a structure of thread information back to you when using the announceInterception() method or directly in the interceptor service, the processState() method. The structure contains information about all the threads that where created during the call and their respective information like: status, data, errors, monitoring, etc.

threadData = announceInterception(
    state           = "onLogin", 
    interceptData   = { user=user }, 
    asyncAll        = true
);

Now that you have seen all asynchronous arguments and their features, let's investigate each use case one by one.