The ColdFusion event gateway service calls one or more listener methods in the CFC to process incoming messages. The number of listener methods that you must write and their names depends on the event gateway. For example, the ColdFusion SMS event gateway requires a single listener method, which is typically named onIncomingMessage. (You can change the SMS event gateway listener method name in the event gateway configuration file.) The ColdFusion XMPP IM event gateway expects the listener CFC to have five methods: onIncomingMessage, onAddBuddyRequest, onAddBuddyResponse, onBuddyStatus, and onIMServerMessage. By default, if the event gateway does not specify the method name, ColdFusion calls the onIncomingMessage method of the listener CFC. For the sake of consistency, Adobe recommends you to use the onIncomingMessage method for any event gateway with a single listener method.

The listener method does the following:

1. Takes a single parameter, a CFEvent structure.

2. Processes the contents of the instance as required by the application.

3. Optionally, returns an outgoing message to the event gateway in a cfreturn tag. It can also send a message back to the event gateway by calling the ColdFusion SendGatewayMessage function.

The following code shows a listener CFC with an onIncomingMessage method that echoes a message back to the Socket event gateway that sent it. It contains the minimum code required to process an incoming message and respond to the sender using the socket gateway.

<cfcomponent displayname="echo" hint="echo messages from the event gateway"> 
    <cffunction name="onIncomingMessage" output="no"> 
        <cfargument name="CFEvent" type="struct" required="yes"> 
        <!--- Create a return structure that contains the message. ---> 
        <cfset retValue = structNew()> 
        <cfset retValue.DestinationID = arguments.CFEvent.OriginatorID> 
        <cfset retValue.MESSAGE = "Echo: " & arguments.CFEvent.Data.MESSAGE> 
        <!--- Send the return message back. ---> 
        <cfreturn retValue> 
    </cffunction> 
</cfcomponent>

Other event gateways require different fields in the return structure. For example, to echo a message using the SMS event gateway, you use the following lines to specify the return value:

<cfset retValue.command = "submit"> 
<cfset retValue.sourceAddress = arguments.CFEVENT.gatewayid> 
<cfset retValue.destAddress = arguments.CFEVENT.originatorid> 
<cfset retValue.ShortMessage = "Echo: " & arguments.CFEvent.Data.MESSAGE>

The ColdFusion event gateway service passes a CFEvent structure with information about the message event to the listener method. The following table describes the structure fields:

When a ColdFusion application responds to an event gateway message, or sends a message independently, it does not use a CFEvent structure. However, the ColdFusion event gateway service creates a Java CFEvent instance with the message data before calling the outgoingMessage method of the event gateway.

ColdFusion listener CFCs can use the Application, Client, and Session persistent scopes.

Because incoming event gateway messages are not associated with HTTP requests, ColdFusion uses different session and client IDs for interactions initiated by these events than for CFM Page requests, as follows:

The gatewayID value is the event gateway ID that you set in the ColdFusion Administrator, and gatewayType and originatorID are the values that the event gateway sets in the CFEvent instance for an incoming message.

The Application scope lets the CFC share data with any ColdFusion page or CFC that uses the same application name. This way, a listener CFC can use the same Application scope as CFML pages that send messages. Also, you can place multiple listener CFCs in a single directory and have them share an Application.cfc or Application.cfm file and application name.

As with all ColdFusion code, use the Application.cfc This.name variable or the cfapplication tag to set the application name. The listener CFC can use an Application.cfc or Application.cfm file if the CFC is in a directory that is in or under one of the following places:

• the ColdFusion web root

• a directory that is in the ColdFusion Administrator Mappings list.

The ColdFusion installer creates a mapping in the ColdFusion Administrator for the gateway\cfc directory.

The Client scope can store long-term information associated with the ID of the message sender. For example, it can store information about an IM buddy.

To use Client variables across multiple connections, your gateway type must use the same client ID for all interactions with a particular client. For many technologies and gateways, such as the IM and SMS gateways, this requirement is not an issue.

The Session scope can store information required across multiple interactions. For example, an interactive IM or SMS application that uses a drill-down menu to select a service can store the information about the menu selections in the Session scope.

Event gateway sessions terminate when they time out. Because the identifiers for event sessions and clients differ from request-driven session and client identifiers, you cannot use the same Session or Client scope on a standard CFM page that sends an outgoing message and in a listener CFC that handles an incoming response to that message.

For an example of using the Session scope, see the example Menu application in the gateway\cfc\examples\menu directory.

When an event gateway CFC responds to an event, it cannot display debugging information in the response page, as CFM pages do. As a result, many of the normal ColdFusion debugging techniques, including the cfdump tag, are not available. When you develop event gateway CFCs, consider the following debugging techniques:

• Place trace variables in the Application scope. These variables persist, and you can specify an application name for your CFC (see Application scope). You can inspect the Application scope contents, including your trace variables, in any CFML page that has the same application name as your CFC.

• Use cflog tags to help you trace any errors by logging significant events to a file. Also, carefully inspect the eventgateway.log and exceptions.log files that ColdFusion maintains. For more information on using the eventgateway.log file, see The eventgateway.log file.

• You can simulate responses from CFCs to the event gateway by using the SendGatewayMessage function in a CFM page. The function’s message parameter should contain the information that the CFC would place in its return variable.

• If you run ColdFusion from the command line, you can use the Java System.out.println method to write messages to the console window, as the following code shows:

  <cfscript> 
      sys = createObject("java", "java.lang.System"); 
      sys.out.println("Debugging message goes here"); 
  </cfscript>

The following code shows a temperature scale converter tool that can work with any of several event gateways: SMS, XMPP, Lotus Sametime, or the example Socket event gateway. Users enter a string that consists of the temperature scale (F, Fahrenheit, C, or Celsius), a comma, and a temperature on their device. The CFC converts Celsius to Fahrenheit or Fahrenheit to Celsius, and returns the result.

This example shows how a responder event gateway application can work, and illustrates how different event gateway types require different outgoing message formats:

<cfcomponent displayname="tempconverter" hint="Convert temperatures between 
    Celsius and Fahrenheit"> 
 
<cffunction name="onIncomingMessage" output="no"> 
    <cfargument name="CFEvent" type="struct" required="yes"> 
    <!--- Standard error message giving the correct input format. ---> 
    <cfset var errormsg = "Please enter scale, integer where scale is F or C,  
        for example:F, 32"> 
 
    <!--- Get the message. ---> 
    <cfset data=cfevent.DATA> 
    <cfset message="#data.message#"> 
    <!--- Where did it come from? ---> 
    <cfset orig="#CFEvent.originatorID#"> 
 
    <!--- Process the input, generate a message with the new temperature. ---> 
    <!--- Input format is: degrees, temperature. ---> 
    <cfif listlen(message) eq 2> 
        <cfif (listgetat(message,1) IS "F") OR 
                (listgetat(message,1) IS "Fahrenheit") OR 
                (listgetat(message,1) IS "C") OR 
                (listgetat(message,1) IS "Celsius")> 
            <cfset scale=listgetat(message,1)> 
            <cfif isNumeric(listgetat(message,2))> 
                <cfset temperature=listgetat(message,2)> 
                <cfswitch expression="#scale#"> 
                    <cfcase value="F, Fahrenheit"> 
                        <cfset retmsg = temperature & " degrees Fahrenheit is "  
                            & (temperature-32.0) * (5.0/9.0) & " degrees Celsius"> 
                    </cfcase> 
                    <cfcase value="C, Celsius"> 
                        <cfset retmsg = temperature & " degrees Celsius is "  
                            &(temperature * 9.0/5.0) + 32 & " degrees Fahrenheit"> 
                    </cfcase> 
                </cfswitch>     
            <cfelse> 
                <cfset retmsg=errormsg> 
            </cfif>         
        <cfelse>     
            <cfset retmsg=errormsg> 
        </cfif>         
    <cfelse> 
        <cfset retmsg=errormsg> 
    </cfif> 
     
    <!--- Fill the return value as required for the event gateway type. ---> 
    <cfif arguments.CFEVENT.GatewayType is "Socket"> 
        <cfset retValue = structNew()> 
        <cfset retValue.MESSAGE = retmsg> 
        <cfset retValue.originatorID = orig> 
    <cfelseif (arguments.CFEVENT.GatewayType is "Sametime") OR 
            (arguments.CFEVENT.GatewayType is "XMPP")> 
        <cfset retValue = structNew()> 
        <cfset retValue.MESSAGE = retmsg> 
        <cfset retValue.BuddyID = arguments.CFEVENT.DATA.SENDER> 
        <cfset retValue.originatorID = orig> 
    <cfelseif arguments.CFEVENT.GatewayType is "SMS"> 
        <cfset retValue = structNew()> 
        <cfset retValue.command = "submit"> 
        <cfset retValue.sourceAddress = arguments.CFEVENT.gatewayid> 
        <cfset retValue.destAddress = arguments.CFEVENT.originatorid> 
        <cfset retValue.shortMessage = retmsg> 
    </cfif>     
 
    <!--- Send the return message back. ---> 
    <cfreturn retValue> 
 
</cffunction> 
</cfcomponent>