DataFaucet ORM

Statement Listeners

A statement listener is a way of massaging the data returned from a SQL statement object when it's executed. Listeners can be used to manipulate the queries returned by select statements or the structures returned by inserts, updates or deletes. While they can alter the returned data (and they must also return it), they don't strictly have to modify it. They might simply be used as triggers to perform other tasks, such as performing a particular logging task if an update statement affected no rows.

A listener can be applied to a statement object using the addListener method like this:

<cfscript>
  // get the datasource
  ds = request.DataFaucet.getDatasource(); 
  // get a select statement 
  stmt = ds.getSelect("*","mytable"); 
  
  // add a listener to filter the returned query 
  stmt.addListener(CreateObject("component","my.listener.class").init()); 
  
  // execute the query 
  // the returned query will now be modified by the listener 
  qry = stmt.execute(); 
</cfscript>

The listener CFC might then look like this:

<cfcomponent output="false">
  
  <cffunction name="init" access="public" output="false">
    <cfreturn this />
  </cffunction>
  
  <cffunction name="filterSQLStatement" access="public" output="false">
    <cfargument name="result" type="query" required="true" />
    
    <cfset QueryAddColumn(result,"new_column",ArrayNew(1)) />
    
    <cfreturn result />
  </cffunction>
</cfcomponent>