Using the example event gateways and gateway applications

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. This document briefly describes 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 responds to messages from a Telnet terminal client without supporting the full Telnet protocol.

Note: The ColdFusion Administrator uses Socket as the gateway type name for the SocketGateway class.

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 multi-threaded 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.

Note: The ColdFusion Administrator uses DirectoryWatcher as the gateway type name for the DirectoryWatcherGateway class.

Configuration file

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

directory=C:/temp
Note: If you use backward slash characters (\) as directory separators in Windows the file paths, escape them by using double slashes, as in C:\\temp. You can use forward slashes (/) as the directory separator on all operating systems, including Windows.
Note: When you specify filename extensions in the Directory Watcher configuration file, do not include the period, instead use a comma, for example, doc,txt.

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:

Property

Req/Opt

Description

directory

Required

Path to the directory to watch.

recurse

Optional

Whether to check subdirectories. The default value is no.

extensions

Optional

Comma-delimited list of extensions to watch. The event gateway logs only changed files with these extensions. An asterisk (*) indicates all files. The default value is all files.

interval

Optional

Number of milliseconds between the times that the event gateway checks the directory. The default value is 60 seconds.

addFunction

Optional

Name of the function to call when a file is added. The default value is onAdd.

changeFunction

Optional

Name of the function to call when a file is changed. The default value is onChange.

deleteFunction

Optional

Name of the function to call when a file is deleted. The default value is onDelete.

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:

Field

Description

TYPE

Event type, one of ADD, CHANGE, DELETE.

FILENAME

Absolute path from the system directory root to the file that was added, deleted, or changed.

LASTMODIFIED

The date and time that the file was created or modified. This field is not included if the file was deleted.

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 could 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.

Note: The ColdFusion Administrator uses JMS as the gateway type name for the JMSGateway class.

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:

Field

Contents

data.id

Message correlation ID

data.msg

Text of the message

gatewayType

Gateway type: JMS

originatorID

Topic name from which the message was consumed

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:

Field

Contents

status

Must be SEND.

topic

Name of the topic to publish the message to.

id

(Optional) The JMS correlation ID to associate with the message. The default is null.

message

Text of the message to publish.

asBytes

(Optional) How to publish the message:

  • If omitted, no, or false, send the message as text.

  • If any other value, send the message as byte-encoded UTF-8.

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 Gateway Instances 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 check is necessary because different event gateways place 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 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

  1. On the Gateway Settings page in the ColdFusion Administrator, click the Start SMS Test Server button.

  2. On the Gateway Instances page in the ColdFusion Administrator, start the SMS Menu App - 5551212 event gateway by clicking the green play button (third button from the left in the Actions column). If the Status does not say Running after a few seconds, click Refresh to check that the server started.

  3. In the cf_root\WEB-INF\cfusion\bin directory on J2EE configurations or the cf_root\bin directory on server configurations, run the SMSClient.bat file (on Windows) or SMSClient.sh file (on UNIX or Linux) to start the SMS phone simulator. The simulator is preconfigured by default to “call” the default SMS event gateway configuration.

  4. Enter any character by typing or by using the mouse to click the simulator keypad, and press Enter on your keyboard or click Send on the simulator.

  5. The menu application responds with the top-level menu. Enter L for language tools such as a dictionary and thesaurus, S to get stock quotes or weather forecasts, or C to get information about the server. Press Enter on your keyboard or click Send on the simulator.

  6. The application displays a submenu. For example, if you select S in step 5, the options are Q for a stock quote, W for weather, or B to go back to the previous menu. Enter your selection.

  7. The application requests information such as a Zip code for the weather, stock symbol for a price, word for the dictionary, and so on. Enter and send the required information (or enter B to go back to the menu).

  8. The application gets and displays the requested information. Depending on the application, you could also be prompted to enter M to get more. Enter M (if more information is available), another term, or B to return to the previous menu.

  9. Continue by entering menu items and detailed information requests.

  10. To exit, select File > Exit from the menu bar.