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>