1 of 4

Interception Methods

There are several simple implicit AOP (Aspect Oriented Programming) interceptor methods, usually referred to as advices, that can be declared in your event handler that the framework will use in order to execute them before/after and around an event as its fired from the current handler.

This is great for intercepting calls, pre/post processing, localized security, logging, RESTful conventions, and much more. Yes, you got that right, Aspect Oriented Programming just for you and without all the complicated setup involved! If you declared them, the framework will execute them.

Pre Advices

With this interceptor you can intercept local event actions and execute things before the requested action executes. You can do it globally by using the preHandler() method or targeted to a specific action pre{actionName}().

// executes before any action
function preHandler( event, action, eventArguments, rc, prc ){
}

// executes before the list() action ONLY
function preList( event, action, eventArguments, rc, prc ){
}

// concrete example
function preHandler( event, action, eventArguments, rc, prc ){
    if( !security.isLoggedIn() ){
        event.overrideEvent( 'security.login' );
        log.info( "Unauthorized accessed detected!", getHTTPRequestData() );
    }
}
function preList event, action, eventArguments, rc, prc ){
    log.info("Starting executing the list action");
}

The arguments received by these interceptors are:

event : The request context reference
action : The action name that was intercepted
eventArguments : The struct of extra arguments sent to an action if executed via runEvent()
rc : The RC reference
prc : The PRC Reference

Exceptions & Only Lists

You can fine tune these interception methods by leveraging two public properties in the handler:

this.prehandler_only : A list of actions that the preHandler() action will fire ONLY!
this.prehandler_except : A list of actions that the preHandler() action will NOT fire on

// only fire for the actions: save(), delete()
this.prehandler_only = "save,delete";
// DO NOT fire for the actions: login(), doLogin(), logout()
this.prehandler_except = "login,doLogin,logout"

Post Advices

With this interceptor you can intercept local event actions and execute things after the requested action executes. You can do it globally by using the postHandler() method or targeted to a specific action post{actionName}().

// executes after any action
function postHandler( event, action, eventArguments, rc, prc ){
}

// executes after the list() action ONLY
function postList( event, action, eventArguments, rc, prc ){
}

// concrete examples
function postHandler( event, action, eventArguments, rc, prc ){
    log.info("Finalized executing #action#");
}

The arguments received by these interceptors are:

event : The request context reference
action : The action name that was intercepted
eventArguments : The struct of extra arguments sent to an action if executed via runEvent()
rc : The RC reference
prc : The PRC Reference

Exceptions & Only Lists

You can fine tune these interception methods by leveraging two public properties in the handler:

this.posthandler_only : A list of actions that the postHandler() action will fire ONLY!
this.posthandler_except : A list of actions that the postHandler() action will NOT fire on

// only fire for the actions: save(), delete()
this.posthandler_only = "save,delete";
// DO NOT fire for the actions: login(), doLogin(), logout()
this.posthandler_except = "login,doLogin,logout"

Around Advices

Around advices are the most powerful of all as you completely hijack the requested action with your own action that looks, smells and feels exactly as the requested action. This is usually referred to as a proxy design pattern.

users.list => users.aroundHandler() <=> list()

This will allow you to run both before and after advices but also surround the method call with whatever logic you want like transactions, try/catch blocks, locks or even decide to NOT execute the action at all.

You can do it globally by using the aroundHandler() method or targeted to a specific action around{actionName}().

Examples

// executes around any action
function aroundHandler(event,targetAction,eventArguments,rc,prc){
}

// executes around the list() action ONLY
function aroundList(event,targetAction,eventArguments,rc,prc){
}

// Around handler advice for transactions
function aroundHandler(event,targetAction,eventArguments,rc,prc){

    // log the call
    log.debug("Starting to execute #targetAction.toString()#" );

    // start a transaction
    transaction{

        // prepare arguments for action call
        var args = {
            event = arguments.event,
            rc    = arguments.rc,
            prc   = arguments.prc

        };
        structAppend( args, eventArguments );
        // execute the action now
        var results = arguments.targetAction( argumentCollection=args );
    }

    // log the call
    log.debug( "Ended executing #targetAction.toString()#" );

    // return if it exists
    if( !isNull( results ) ){ return results; }
}

// Around handler advice for try/catches
function aroundHandler(event,targetAction,eventArguments,rc,prc){

    // log the call
    if( log.canDebug() ){
        log.debug( "Starting to execute #targetAction.toString()#" );
    }

    // try block
    try{

        // prepare arguments for action call
        var args = {
            event = arguments.event,
            rc    = arguments.rc,
            prc   = arguments.prc

        };
        structAppend( args, eventArguments );
        // execute the action now
        return arguments.targetAction( argumentCollection=args );
    }
    catch(Any e){
        // log it
        log.error("Error executing #targetAction.toString()#: #e.message# #e.detail#", e);
        // set exception in request collection and set view to render
        event.setValue( "exception", e)
            .setView( "errors/generic" );

    }

}

The arguments received by these interceptors are:

event : The request context reference
targetAction : The function pointer to the action that got the around interception. It will be your job to execute it (Look at samples)
eventArguments : The struct of extra arguments sent to an action if any
rc : The RC reference
prc : The PRC Reference

Exceptions & Only Lists

You can fine tune these interception methods by leveraging two public properties in the handler:

this.aroundhandler_only : A list of actions that the aroundHandler() action will fire ONLY!
this.aroundhandler_except : A list of actions that the aroundHandler() action will NOT fire on

// only fire for the actions: save(), delete()
this.aroundhandler_only = "save,delete";
// DO NOT fire for the actions: login(), doLogin(), logout()
this.aroundhandler_except = "login,doLogin,logout"

Around Advices

users.list => users.aroundHandler() <=> list()

You can do it globally by using the aroundHandler() method or targeted to a specific action around{actionName}().

Examples

// executes around any action
function aroundHandler(event,targetAction,eventArguments,rc,prc){
}

// executes around the list() action ONLY
function aroundList(event,targetAction,eventArguments,rc,prc){
}

// Around handler advice for transactions
function aroundHandler(event,targetAction,eventArguments,rc,prc){

    // log the call
    log.debug("Starting to execute #targetAction.toString()#" );

    // start a transaction
    transaction{

        // prepare arguments for action call
        var args = {
            event = arguments.event,
            rc    = arguments.rc,
            prc   = arguments.prc

        };
        structAppend( args, eventArguments );
        // execute the action now
        var results = arguments.targetAction( argumentCollection=args );
    }

    // log the call
    log.debug( "Ended executing #targetAction.toString()#" );

    // return if it exists
    if( !isNull( results ) ){ return results; }
}

// Around handler advice for try/catches
function aroundHandler(event,targetAction,eventArguments,rc,prc){

    // log the call
    if( log.canDebug() ){
        log.debug( "Starting to execute #targetAction.toString()#" );
    }

    // try block
    try{

        // prepare arguments for action call
        var args = {
            event = arguments.event,
            rc    = arguments.rc,
            prc   = arguments.prc

        };
        structAppend( args, eventArguments );
        // execute the action now
        return arguments.targetAction( argumentCollection=args );
    }
    catch(Any e){
        // log it
        log.error("Error executing #targetAction.toString()#: #e.message# #e.detail#", e);
        // set exception in request collection and set view to render
        event.setValue( "exception", e)
            .setView( "errors/generic" );

    }

}

The arguments received by these interceptors are:

event : The request context reference
targetAction : The function pointer to the action that got the around interception. It will be your job to execute it (Look at samples)
eventArguments : The struct of extra arguments sent to an action if any
rc : The RC reference
prc : The PRC Reference

Exceptions & Only Lists

You can fine tune these interception methods by leveraging two public properties in the handler:

this.aroundhandler_only : A list of actions that the aroundHandler() action will fire ONLY!
this.aroundhandler_except : A list of actions that the aroundHandler() action will NOT fire on

// only fire for the actions: save(), delete()
this.aroundhandler_only = "save,delete";
// DO NOT fire for the actions: login(), doLogin(), logout()
this.aroundhandler_except = "login,doLogin,logout"

Pre Advices

// executes before any action
function preHandler( event, action, eventArguments, rc, prc ){
}

// executes before the list() action ONLY
function preList( event, action, eventArguments, rc, prc ){
}

// concrete example
function preHandler( event, action, eventArguments, rc, prc ){
    if( !security.isLoggedIn() ){
        event.overrideEvent( 'security.login' );
        log.info( "Unauthorized accessed detected!", getHTTPRequestData() );
    }
}
function preList event, action, eventArguments, rc, prc ){
    log.info("Starting executing the list action");
}

The arguments received by these interceptors are:

event : The request context reference
action : The action name that was intercepted
eventArguments : The struct of extra arguments sent to an action if executed via runEvent()
rc : The RC reference
prc : The PRC Reference

Exceptions & Only Lists

You can fine tune these interception methods by leveraging two public properties in the handler:

this.prehandler_only : A list of actions that the preHandler() action will fire ONLY!
this.prehandler_except : A list of actions that the preHandler() action will NOT fire on

// only fire for the actions: save(), delete()
this.prehandler_only = "save,delete";
// DO NOT fire for the actions: login(), doLogin(), logout()
this.prehandler_except = "login,doLogin,logout"

Post Advices

// executes after any action
function postHandler( event, action, eventArguments, rc, prc ){
}

// executes after the list() action ONLY
function postList( event, action, eventArguments, rc, prc ){
}

// concrete examples
function postHandler( event, action, eventArguments, rc, prc ){
    log.info("Finalized executing #action#");
}

The arguments received by these interceptors are:

event : The request context reference
action : The action name that was intercepted
eventArguments : The struct of extra arguments sent to an action if executed via runEvent()
rc : The RC reference
prc : The PRC Reference

Exceptions & Only Lists

You can fine tune these interception methods by leveraging two public properties in the handler:

this.posthandler_only : A list of actions that the postHandler() action will fire ONLY!
this.posthandler_except : A list of actions that the postHandler() action will NOT fire on

// only fire for the actions: save(), delete()
this.posthandler_only = "save,delete";
// DO NOT fire for the actions: login(), doLogin(), logout()
this.posthandler_except = "login,doLogin,logout"