Using the CFML event gateway for asynchronous CFCs

The ColdFusion MX CFML event gateway lets CFML code send a message to CFC methods asynchronously. This event gateway lets you initiate processing by a CFC method without waiting for it to complete or return a value. Possible uses for asynchronous CFCs that you access using this event gateway include the following:

Reindexing a Verity collection with new information without delaying an application, for example, when a user uploads a new file
Logging information, particularly if there is significant amount of data to log
Running batch processes that might take a substantial amount of time to complete

Because asynchronous CFCs run independently of a request, they do not provide feedback to the user. You must save any results or error information to a file, data source, or other external resource.

By default, ColdFusion delivers the message to a CFC method named onIncomingMessage. You can specify any method name, however, in the SendGatewayMessage method's data parameter.

CFML event gateway data structure

The structure that you use in the CFML SendGatewayMessage function can include two types of fields:

The structure can include any number of fields with arbitrary contents for use in by the CFC.
Several optional fields can configure how the gateway delivers the information to the CFC.

The CFML gateway looks for the following optional fields, and, if they exist, uses them to determine how it delivers the message. Do not use these field names for data that you send to your CFC method.

Field	Use
cfcpath	Overrides the CFC path specified in the ColdFusion MX Administrator. This field lets you use a single gateway configuration in the ColdFusion MX Administrator multiple CFCs.
method	Sets the name of the method to invoke in the CFC. The default method is `onIncomingMessage`. This field lets you use a single gateway configuration in the ColdFusion MXAdministrator for a CFC that has several methods.
originatorID	Sets the originatorID field of the CFEvent object that ColdFusion MX delivers to the CFC. The default value is CFMLGateway.
timeout	Sets the time-out, in seconds, during which the listener CFC must process the event request and return before ColdFusion gateway services terminates the request. The default value is the Timeout Request value set on the Server Settings page in the ColdFusion MX Administrator. Set this value if a request might validly take longer to process than the default timeout; for example, if the request involves a very long processing time.

Using the CFML gateway

The following procedure describes how to use an asynchronous CFC that has a single, onIncomingMessage method.

To use an asynchronous CFC:

Create a CFC with an onIncomingMessage method. Put the CFC in an appropriate directory for your application. For example, you can put it in the cf_root\WEB-INF\cfusion\gateway\cfc directory on J2EE configurations, in the cf_root\gateway\cfc directory on server configurations, or in a subdirectory of these directories. ColdFusion MX is installed with mappings to these cfc gateway directories.
The onIncomingMessage method must take a CFEvent structure that contains input information in its Data field, and processes the contents of the Data field as needed.
Use the Gateways page in the ColdFusion MX Administrator to add an instance of the CFML event gateway type. Specify the following:
- A unique Gateway ID.
- The path to the CFC that you created in step 1.
- The startup mode. Select Automatic startup mode to start the event gateway when ColdFusion MX starts up.
- Do not specify a configuration file.
Start the event gateway instance.
Write CFML code that uses SendGatewayMessage functions to send messages in structures to the event gateway instance ID that you specified in step 2. The SendGatewayMessage function returns true if the gateway successfully queues the message in the ColdFusion MX Gateway Service; false, otherwise. It does not ensure that the CFC receives or processes the message.
Run your CFML application.

Example: logging messages

The following asynchronous CFML event gateway CFC uses the cflog tag to log a message to a file in the ColdFusion MX logs directory. The CFC takes a message with the following fields:

file The name of the file in which to put the message. The default value is defaultEventLog.
type The cflog type attribute to use. The default value is info.
message The message text.

<cfcomponent>
   <cffunction name="onIncomingMessage" output="no">
      <cfargument name="CFEvent" type="struct" required="yes">
      <cfscript>
         if (NOT IsDefined("CFEvent.Data.file")) {
            CFEvent.Data.file="defaultEventLog"; }
         if (NOT IsDefined("CFEvent.Data.type")) {
            CFEvent.Data.type="info"; }
      </cfscript>
      <cflog text="#CFEvent.Data.message#"
          file="#CFEvent.Data.file#"
         type="#CFEvent.Data.type#"
         thread="yes"
         date="yes"
         time="yes"
         application="yes">
   </cffunction>
</cfcomponent>

The following minimal CFML page tests the event gateway:

Sending an event to the CFML event gateway that is registered in the 
   ColdFusion MX Administrator as Asynch Logger.<br>
<cfscript>
   status = false;
   props = structNew();
   props.Message = "Replace me with a variable with data to log";   
   status = SendGatewayMessage("Asynch Logger", props);
   if (status IS True) WriteOutput('Event Message "#props.Message#" has been sent.');
</cfscript>

View comments in LiveDocs