Hibernate can announce events to listener objects so they can tap in to the life-cycle of the entities. You can either listen to the events globally or within the entity itself by just declaring a few listener methods. The cborm module taps in to the global Hibernate events and re-transmits them as ColdBox interception points. This allows you to intercept ORM events via multiple CFC listeners instead of the rigid approach of a single listener CFC which the ColdFusion engines give you.

This is achieved by the cborm.models.EventHandler class and by telling the application about it. The event handler also (if configured) will talk to WireBox and auto wire entities with dependencies. Just add your dependency injection properties and off you go with entity injection.

Enabling The Event Handler

You can enable the cborm event handler by opening the Application.cfc and adding two settings:

• eventHandling

• eventHandler

this.ormSettings = {
    cfclocation="model",
    dbcreate = "update",
    dialect = "MySQLwithInnoDB",
    logSQL = true,
    // Enable event handling
    eventhandling = true,
    // Set the event handler to use, which will be inside our application.
    eventhandler = "cbmorm.models.EventHandler"
};

That's it, now the cborm event handler will listen to the ORM events, re-broadcast them and you can create ColdBox Interceptors to listen to them.

Listening to Events

Below are the new interception points the ORM Event Handler exposes with the appropriate interception data it announces. Just create an Interceptor CFC, add the method with the name of the interception point and off you go!

With the exposure of these interception points to your ColdBox application, you can easily create decoupled executable chains of events that respond to ORM events. This really expands the ORM interceptor capabilities to a more decoupled way of listening to ORM events. You can even create different interceptors for different ORM entity classes that respond to the same events, extend the entities with AOP, change entities at runtime, and more; how cool is that.

component extends="coldbox.system.Interceptor"{

    function ORMPostLoad( event, interceptData, rc, prc ){
        // audit the data.
        var state = interceptData.entity.getMemento();
        autidService.logState( state, interceptData.entity );    
    }

}

The ColdFusion documentation says that in order to create a global event handler that it must implement the CFIDE.orm.IEventHandler interface. So all you need to do is create the CFC and make it extend the core class that will provide you with all these capabilities: cborm.models.EventHandler

component extends="cborm.models.EventHandler"{
}

That's it! Just by doing this the CF ORM will call your CFC's event methods in this CFC and satisfy the interface. Of course you can override the methods, but always remember to fire off the parent class methods in order for the ColdBox interceptions to still work. You can then override each event method as needed. Below is a chart of methods you can override:

The base event handler CFC you inherit from has all the ColdBox interaction capabilities you will ever need. You can find out all its methods by referring to the API and looking at that class or by inspecting the ColdBox Proxy class, which is used for enabling ColdBox interactions: coldbox.system.remote.ColdboxProxy