The ColdFusion 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:
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.
The structure that you use in the CFML SendGatewayMessage function can include two types of fields:
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 Administrator. This field lets you use a single gateway configuration in the ColdFusion 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 Administrator for a CFC that has several methods. |
originatorID |
Sets the originatorID field of the CFEvent object that ColdFusion 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 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. |
The following procedure describes how to use an asynchronous CFC that has a single, onIncomingMessage method.
The following asynchronous CFML event gateway CFC uses the cflog tag to log a message to a file in the ColdFusion logs directory. The CFC takes a message with the following fields:
<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 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>