ColdFusion provides several example event gateways and applications in the cf_root\WEB-INF\cfusion\gateway directory on J2EE configurations or the cf_root\gateway directory on server configurations. These gateways provide example code that you can examine or use in developing your gateways. They are intended as examples only, and are not complete, product-quality, implementations.

Example event gateways

The gateway\src\examples directory and its subdirectories include the sources for the example event gateways. Compiled versions are located in the gateway\lib\examples.jar file. The following sections briefly describe the event gateways and their functions. For more detailed information, see the code and comments in the files.

EmptyGateway

The EmptyGateway.java file contains an event gateway template that you can use as a skeleton for creating your own event gateway. For more information on this class, and on creating new event gateways, see Creating Custom Event Gateways

SocketGateway

The SocketGateway event gateway listens on a TCP/IP port. Therefore, you can use this gateway for applications that send and respond to messages using TCP/IP-based protocols such as Telnet, or for applications that send messages between sockets. For example, a simple gateway application that might respond to messages from a Telnet terminal client without supporting the full Telnet protocol.

The SocketGateway.java file defines two classes: SocketGateway, the event gateway, and SocketHelper, a GatewayHelper class. The Source file is located in the gateway\src\examples\socket directory.

SocketGateway: Listens on a TCP/IP port. This event gateway is multithreaded and can handle multiple clients simultaneously. It can send outgoing messages to existing clients, but cannot establish a link itself.

By default, the SocketGateway class listens on port 4445, but you can specify the port number in a configuration file. The file should contain a single line in the following format:

port=portNumber

SocketHelper: A GatewayHelper class with the following methods:

• getSocketIDs() returns an array containing the socket IDs of all Java sockets that are open. The event gateway opens a socket for each remote client.
• killSocket(String socketid) Removes the specified socket. Returns a Boolean success indicator.

DirectoryWatcherGateway

The DirectoryWatcherGateway event gateway sends events to the listener CFC when a file is created, deleted, or modified in a directory. The watcher runs in a thread that sleeps for an interval specified in the configuration file, and when the interval has passed, checks for changes since the last time it was awake. If it finds added, deleted, or changed files, it sends a message to a listener CFC. You can configure separate CFCs for add, delete, and change events, or use a single CFC for all events. The source for this event gateway is located in the gateway/src/examples/watcher directory.

Configuration file

This event gateway requires a configuration file, consisting of lines in the following format:

directory=C:/temp

The configuration file can have comment lines, preceded by a number sign (#). If you omit a property or comment it out, ColdFusion uses the default value. If you specify a property with no value, ColdFusion sets an empty property. The configuration file can define the following values:

An example configuration file is located in the gateway\config\directory-watcher.cfg file.

CFC methods

When the directory contents change, the event gateway calls one of the following CFC listener methods, unless you change the names in the configuration file:

• onAdd
• onChange
• onDelete

The CFEvent.Data field sent to the listener methods includes the following fields:

The event gateway supports multiple listener CFCs and sends the event messages to all listeners. The event gateway is one-way; it watches for events and dispatches event information to a CFC, but it does not accept return values from the CFC or input from SendGatewayMessage functions.

The directory watcher logs errors to the watcher.log file in the ColdFusion logs directory.

Example DirectoryWatcher application

The following code shows a simple directory watcher application. It enters a line in a log file each time a file is added, deleted, or changed in the directory specified in the configuration file. ColdFusion includes the date and time that a log entry is made. However, if the directory watcher monitors changes infrequently, for example once every minute or more, the time in the log entry might differ from the time a file was added or changed, so the information includes the time (but not date) for these actions.

<cfcomponent>
<cffunction name="onAdd" output="no">
    <cfargument name="CFEvent" type="struct" required="yes">
    <cfset data=CFEvent.data>
    <cflog file="MydirWatcher" application="No" 
        text="ACTION: #data.type#;FILE: #data.filename#;
        TIME: #timeFormat(data.lastmodified)#">
</cffunction>

<cffunction name="onDelete" output="no">
<cfargument name="CFEvent" type="struct" required="yes">
<cfset data=CFEvent.data>
<cflog file="MydirWatcher" application="No" 
    text=" ACTION: #data.type#;FILE: #data.filename#">
</cffunction>

<cffunction name="onChange" output="no">
<cfargument name="CFEvent" type="struct" required="yes">
<cfset data=CFEvent.data>
<cflog file="MydirWatcher" application="No" 
        text=" ACTION: #data.type#;FILE: #data.filename#;
        TIME: #timeFormat(data.lastmodified)#">
</cffunction>
</cfcomponent>

JMSGateway

The JMSGateway class acts as a Java Messaging Service consumer or producer. The source for this event gateway is located in gateway/src/examples/JMS. The gateway requires a configuration file, which is in gateway/config/jmsgateway.cfg. For full documentation of the configuration options, See the configuration file. The ColdFusion Administrator lists the compiled gateway (which is included in the gateway\lib\examples.jar file) on the Gateway Types page.

Using the JMS Gateway as a consumer

The JMSGateway class creates a subscriber to the topic specified in the configuration file. The gateway consumes the following types of messages:

• TextMessage
• BytesMessage containing raw UTF-8 text

The gateway passes the contents of the message to the configured CFC in the event structure, as follows:

The listener CFC method must be named onIncomingMessage. If the CFC method does not send a message in response, it should return a structure containing a status field with a value of OK or EXCEPTION. (In this case, The gateway checks the return status field, but does not process these return values further.) To send a message, the CFC method must return a structure as documented in the following section.

Using the JMS Gateway as a producer

To send a JMS message, the return value of your CFC method or the second, messageStruct, parameter to the SendGatewayMessage function must be a structure with the following fields:

If you send the message in a SendGatewayMessage function, the function returns OK if the gateway sends the message, or EXCEPTION if it fails to send the message.

ActiveMQ JMS event gateway

Apache ActiveMQ is a message broker that implements JMS. The source for this event gateway is located in gateway/src/examples/ActiveMQ. For information about using the ActiveMQ JMS event gateway, see the gateway\docs\ActiveMQDeveloperGuide.pdf file.

Menu example application

ColdFusion is installed with a menu-based responder application. The menu application is written to work with any of the standard ColdFusion event gateways (SMS, XMPP, and Sametime) and with the Socket example event gateway, and ColdFusion is preconfigured with an instance of the application that uses SMS, as follows:

• The Gateways page in the ColdFusion Administrator includes a gateway instance for this application that uses the SMS gateway type.
• The gateway/cfc/examples/menu directory and its subdirectories include the CFML for the application
• The gateway/config/sms-test.cfg file is configured to use this application with the SMS client (phone simulator), and short message service center (SMSC) server simulator that are provided with ColdFusion.

The application presents users with a drill-down menu of tools that they can use, including a weather report, stock information, status and configuration information, and language tools such as a dictionary.

The code for this application is relatively complex and is distributed among 13 files. The following brief description provides an overview of how it works. To get a full understanding of how the application works, see the source code.

• The top level, menu, directory contains two files: Application.cfm and main.cfc.
• The Application.cfm file consists of a single cfapplication tag that enables session management and names the application. Session variables maintain the current state information of the session, such as the active menu, and so on.
• The main.cfc file contains the master CFC; the event gateway configuration in ColdFusion Administrator uses it as the listener CFC. The main CFC file processes CFEvent structures from the event gateway. It does the following:
  1. Inspects the gatewayType field to determine the rest of the structure contents. This is necessary because different event gateways put the message in fields with different names.
  2. If a Session.menu variable does not exist, initializes the menu system. To do so, it calls methods in two other CFCs: menu and menunode. These two CFCs contain the menu system code.
  3. Calls the session.menu.process method to process the user's input. This method can dispatch a message to an individual application for processing, if appropriate.
• The apps directory contains several CFCs. Each file contains the code for a single application, such as the weather report or dictionary lookup (definition.cfc).

Use the menu application with the Socket event gateway