Developing an event gateway application

All event gateway applications handle information. They exchange event messages, and possibly other types of information, with other resources. Event gateway applications require a listener CFC to handle events that are sent to the event gateway. Event gateway applications can also use the following code elements:

• SendGatewayMessage CFML functions to send messages from outside the listener CFC (or, optionally, from the CFC)
• GatewayHelper objects
• The eventgateway log file

Event gateway application models

Event gateway applications follow one or both of the following models:

• Responder applications Where event messages from external sources initiate a response from a ColdFusion listener CFC
• Initiator applications Where a ColdFusion application generates event messages to send out using the event gateway Unlike other ColdFusion applications, responder applications are request-free. They do not have CFM pages, just CFCs, and they do not respond to HTTP requests. Instead, ColdFusion the event gateway service deliver the event messages directly to the listener CFC, and the CFC listener method returns any response directly to the event gateway service. Applications that allow mobile phone owners to get a news feed, check for text messages, or request other forms of information follow this model.
  Initiator applications are like most ColdFusion applications. At some point, ColdFusion executes a CFM page in response to a request. (The ColdFusion Administrator Scheduled Tasks page can initiate the request.) ColdFusion sends a message to the event gateway when the application calls a CFML SendGatewayMessage function. An application that uses SMS to notify customers when orders have been shipped follows this model.

Sending information to the event gateway

A ColdFusion application can send an outgoing message to the event gateway in either of the following ways:

• In a cfreturn tag in the listener CFC listener method
• By calling the ColdFusion SendGatewayMessage function
  The first method is useful to automatically respond to incoming messages. Some complex applications that respond to incoming messages could use the SendGatewayMessage function either in place or in addition to the return value.
  Some event gateway types also use a GatewayHelper object to send information to external resources. For example, the ColdFusion XMPP and Lotus Sametime instant messaging event gateways provide a GatewayHelper object that can manage buddy lists, and set configuration and status information on the instant messaging server. For more information on the GatewayHelper object, see Using the GatewayHelper object. For more information on the instant messaging GatewayHelper object, see Sample IM message handling application.
  The example code in Example event gateway CFC shows the use of a listener return value, and indicates how event gateways can require different data in the return structure to send equivalent messages.

Developing event gateway listener CFCs

The listener CFC responds to event gateway messages. The listener CFC uses, at a minimum, the following basic software elements:

• One or more listener methods
• CFEvent structures that contain the messages
  Listener CFCs can use ColdFusion persistent scopes to store data that must be preserved over multiple CFC invocations or shared with other CFML elements.

Listener methods

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.

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:

The CFEvent structure

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.

Using persistent scopes in listener CFCs

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.

Application scope

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.

Client scope

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.

Session scope

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.

Debugging event gateway CFCs

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 below.
• 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.printlnmethod to write messages to the console window, as the following code shows:

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

   

Example event gateway CFC

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:

Sending a message using the SendGatewayMessage function

The SendGatewayMessage function has the following format:

• The gatewayID parameter must be the gateway ID specified in the ColdFusion Administrator for the event gateway instance that sends the message.
• The messageStruct parameter is a structure whose contents depends on the requirements of the outgoingMessage method of the event gateway, and possibly the recipient application. For example, in addition to any message, the structure could include a destination identifier.
  The CFEvent instance passed to the event gateway contains these two parameters in the GatewayID and Data fields; the remaining fields are empty.
  The following example sends a message to a logging CFC, which logs information to a file. If the SendGatewayMessage function returns "OK", the example code displays a message. The code uses an instance of the asynchronous CFML event gateway named Asynch Logger. The props variable used in the messageStruct parameter has two entries, the destination file and the message to log.

Using the GatewayHelper object

The ColdFusion GetGatewayHelper function tells ColdFusion to create and initialize a Java GatewayHelper object that provides event gateway-specific helper methods and properties. To use this function, the event gateway must implement a GatewayHelper class. For example, an instant messaging event gateway could make buddy list management methods available in a GatewayHelper object.
The ColdFusion GetGatewayHelper function takes a single parameter, the ID of the event gateway instance that provides the helper, and returns a GatewayHelper Java object. The parameter value must be the gateway ID for the instance that is specified in the ColdFusion Administrator. If you do not want to hard-code an ID value in the application (for example, if your listener CFC can respond to multiple event gateway instances), get the gateway ID from the CFEvent structure of the first incoming message.
The CFML code accesses the GatewayHelper object's methods and properties using standard ColdFusion Java object access techniques (see Integrating JEE and Java Elements in CFML Applications). For example, if an event gateway's GatewayHelper class includes an addBuddy method that takes a single String parameter, you could use the following code to get the ColdFusion XMPP or Sametime gateway GatewayHelper object and add a buddy to the buddies list:

Using the event gateway error log file

When a standard ColdFusion event gateway encounters an error that does not prevent the event gateway from continuing to process, it logs it to the eventgateway.log file in the ColdFusion logs directory. Other event gateways can also to log information in this file, or to other application-specific files in the logs directory. 
The standard ColdFusion event gateways log errors in interaction with any messaging server, errors in messages sent by the ColdFusion application, and recoverable errors in event gateway operation. The event gateways also log informational status messages for significant normal events, including event gateway initialization and restarts.
ColdFusion event gateway messages in the eventgateway.log file normally have the following format:

When you are developing an event gateway application, you can use the ColdFusion Log viewer to inspect the eventgateway.log file and filter the display by using the gateway type and possibly the gateway ID as keywords. By selecting different severity levels, you can get a good understanding of errors and possible inefficiencies in your application and event gateway operation.