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.

This section describes the following topics:

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.

Note: The ColdFusion MX 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 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.

Note: The ColdFusion MX 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, you must 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.

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 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	Name of 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 MX 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 MX Administrator lists the compiled gateway (which is included in the gateway\lib\examples.jar file) on the Gateway Types page.

Note: The ColdFusion MX 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.

View comments in LiveDocs