Using application event handlers
The following table briefly describes the application event CFC methods that you can implement, including when they are triggered. The following sections describe how to use these methods in more detail.
|
Method |
When run |
|---|---|
| onApplicationStart |
The application first starts: when the first request for a page is processed or the first CFC method is invoked by an event gateway instance, Flash Remoting request, or a web service invocation. This method is useful for setting application-wide (Application scope) variables, such as the names of data sources. |
| onApplicationEnd |
The application ends: when the application times out or the server shuts down. |
| onSessionStart |
A new session is created as a result of a request that is not in an existing session, including ColdFusion event gateway sessions. The application must enable sessions for this event to happen. |
| onSessionEnd |
A session time-out setting is reached. This event is not triggered when the application ends or the server shuts down. |
| onRequestStart |
ColdFusion receives any of the following: a request, an HTTP request (for example, from a browser), a message to an event gateway, a SOAP request, or a Flash Remoting request. |
| onRequest |
The onRequestStart event has completed. This method can act as a filter for the requested page content. |
| onRequestEnd |
All pages and CFCs in the request have been processed: equivalent to the OnRequestEnd.cfm page. |
| onMissingTemplate |
When ColdFusion receives a request for a nonexistent page. |
| onError |
When an exception occurs that is not caught by a try/catch block. |
When ColdFusion receives a request, it instantiates the Application CFC and runs the Application.cfc code in the following order:
- CFC initialization code at the top of the file
- onApplicationStart, if not run before for this application
- onSessionStart, if not run before for this session
- onRequestStart
- onRequest, or the requested page if there is no onRequest method
- onRequestEnd
The following methods are triggered by specific events:
- onApplicationEnd
- onSessionEnd
- onMissingTemplate
- onError
The onApplicationEnd and onSessionEnd methods do not execute in the context of a page request, so they cannot access request variables or display information to the user. The onMissingTemplate method is triggered when a URL specifies a CFML page that does not exist. The OnError method does not always execute in the context of a request; you can use its Event argument to determine the context.