106
Chapter 56: Using Event Gateways
Adobe ColdFusion provides event gateways, which you can use when writing applications. You configure an event
gateway for an application and deploy the application.
To use event gateways, you should have a thorough knowledge of ColdFusion development concepts and practices,
including ColdFusion components (CFCs). To write applications for custom gateways that are not provided in
ColdFusion, you must also know the details of the event gateway you are using, including its requirements.
Contents
About event gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1060
Event gateway facilities and tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1064
Structure of an event gateway application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1066
Configuring an event gateway instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1067
Developing an event gateway application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1068
Deploying event gateways and applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
Using the CFML event gateway for asynchronous CFCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
Using the example event gateways and gateway applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1077
About event gateways
ColdFusion event gateways are ColdFusion elements that let ColdFusion react to or generate external events or
messages in an asynchronous manner. Event gateways let a ColdFusion application handle information that does not
come through an HTTP request. For example, you can use event gateways to handle instant messages, short
messages from mobile devices, or messages sent to a TCP/IP port.
The event gateway mechanism has the following major features:
• ColdFusion event gateways do not require HTTP requests. ColdFusion developers can write ColdFusion
gateway applications without using any CFM pages (just CFCs).
• ColdFusion CFCs can use event gateways to listen for and respond directly to external events.
• Event gateways operate asynchronously. A gateway typically gets a message and dispatches it for processing,
without requiring or waiting for a response.
• ColdFusion developers can create event gateways to handle any kind of event that a Java application can receive.
ColdFusion includes several product-level event gateways, such as a gateway for the XMPP (Extensible Messaging
and Presence Protocol) instant messaging protocol. Adobe also provides the source for several example gateways,
such as a generalized socket gateway, that you can extend to handle your specific needs. You can also write your own

gateways in Java to handle other event or messaging technologies supported by the Java runtime or by third-party
providers, such as gateways for additional instant messaging protocols, gateways for specific ERP systems, or other
protocols, such as NNTP.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
106
Using event gateways
Because event gateways provide a generalized asynchronous messaging mechanism, you can use them with many
kinds of event or messaging resources. For example, ColdFusion includes gateways (either product quality, or lighter
weight example gateways) for communicating between ColdFusion applications and the following types of
resources:
• Mobile phones and other devices that support short messaging services (SMS)
• XMPP or IBM Sametime Instant message clients
• Java Sockets (which let your ColdFusion application communicate with TCP/IP-based devices and programs,
such as Telnet terminal clients).
• Java Messaging Service (JMS) resources, such as storefront sales order handling systems.
Event gateways are not limited to sending or receiving information using communications protocols. For example,
ColdFusion includes an example event gateway that monitors changes to a directory and invokes a CFC method
whenever the directory changes. ColdFusion also includes an event gateway that lets a CFML application “call” a
CFC asynchronously and continue processing without getting a response from the CFC.
Just as you can create event gateways that serve many different event or messaging based technologies, you can write
many kinds of applications that use them. Just a few examples of possible gateway uses include the following.
Server to client push examples
• An application that sends an instant message (IM) or SMS text message to a person who can approve a purchase
order, get a response, and mark the purchase order as approved or denied.
• A bot that notifies users through their preferred messaging method (cell phone, instant messaging, or even e-
mail) when watch list stock goes up, and offers to buy or sell the stock immediately.
• An application that authenticates web users by sending them an SMS message that includes code that they must
to enter into the browser in order to proceed.
Client to server examples

• A menu-based SMS application that lets users get information from any of several web service data providers.
ColdFusion includes a SMS menuing example int the gateways/cfc directory.
• A instant messaging application that takes messages from users to technical support and assigns and directs the
messages to the most available support staff member. The application could also log the user ID and session, and you
could use ColdFusion to generate usage reports.
• A directory lookup robot IM "buddy" that responds to messages chat contain an employee’s name with the
employee’s phone number or buddy ID.
Server to serve examples
• A JMS subsystem that publishes status updates that are consumed by business intelligence systems.
• A system that monitors and publishes download events from a website.
Event gateway terms and concepts
This document uses the following terms when referring to event gateways:
Event: A trigger that ColdFusion can receive from an external source. ColdFusion event gateways receive events.
Message: The information provided by an event. In ColdFusion, a message is the data structure that the event
gateway receives when an event is triggered.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
106
Event gateway: Java code that receives events and sends them to and from ColdFusion application code. This
document uses the term event gateway, without the word type or instance, to refer to the general concept of a
ColdFusion event gateway. Where the context makes the meaning obvious, the term can also refer to event gateway
type or event gateway instance.
Event gateway type: A specific event gateway implementation, represented by a Java class. Each event gateway type
handles messages belonging to a particular a communications method or protocol, such as short message service
(SMS), an instant messaging protocol, or Sockets. You generally have one event gateway type per communication
protocol. You configure each event gateway type on the Gateway Types page in the Event Gateways area in the
ColdFusion Administrator.
Event gateway instance: A specific instance of an event gateway type class. You configure each event gateway
instance on the ColdFusion Gateways page by specifying the event gateway type, an ID, the path to the event gateway
application CFC that uses this instance, and a configuration file (if needed for the selected event gateway type). You

can have multiple event gateway instances per event gateway type, for example, for different event gateway applica-
tions.
Event gateway application: One or more CFCs and any supporting CFM pages that handle events from an event
gateway instance and send messages using the event gateway instance. The event gateway application is not part of
an event gateway instance, but the code that is responsible for processing event messages to and from the instance.
Event gateway listener: Code in an event gateway that receives events from an event source and passes them to the
ColdFusion gateway service for delivery to a CFML listener CFC.
Listener CFC: A CFC that contains one or more methods that respond to incoming messages from one or more
event gateway instances. Part of an event gateway application.
ColdFusion gateway service: The part of ColdFusion that provides underlying support for event gateways, including
a path between an event gateway instance and listener CFCs.
How event gateway applications work
The following diagram shows the architecture of ColdFusion event gateway applications:
How event gateways interact
Typically, a ColdFusion event gateway instance, a Java object, listens for events coming from an external provider.
For example, a general socket event gateway listens for messages on an IP socket, and an SMS event gateway receives
messages from an SMSC server.
Event Gateway
Instance
SMSC server
(for SMS messages)
Instant
messaging
provider
Other message
generator/receiver
Event Gateway
Instance
Event Gateway
Instance

ColdFusion
Event
Gateway
Service
Java
Event
Event
Event
Event
Event
Event
CFEvent
CFEvent
CFEvent
CFEvent
CFEvent
CFEvent
ColdFusion
Event Gateway
Application
Event Gateway
Application
CFML
Listener CFC
CFEvent
Message
Event Gateway
Application
Listener CFC
CFEvent

Message
CFEvent
Message
Listener CFC
CFM Page
.
.
.
.
.
.
.
.
.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
106
Each event gateway instance communicates with one or more listener CFCs through the ColdFusion event gateway
service. The listener CFCs receive CFEvent object instances that contain the messages, process them, and can send
responses back to the event gateway, which can send the messages to the external resources.
Alternatively, a ColdFusion application can initiate a message by calling a ColdFusion function that sends the
message to the event gateway. The event gateway then forwards the message to an external resource, such as an
instant messaging server. A CFC in the application listens for any responses to the sent message.
Some event gateways can be one-way: they listen for a specific event and send it to a CFC, or they get messages from
a ColdFusion function and dispatch it, but they do not do both. The example DirectoryWatcherGateway listens for
events only, and the asynchronous CFML event gateway receives messages from CFML only. (You could even say
that the directory watcher gateway doesn’t listen for events; it creates its own events internally by periodically
checking the directory state.) For information on the asynchronous CFML event gateway, see “Using the CFML
event gateway for asynchronous CFCs” on page 1075.
Event gateway structure

Java programmers develop ColdFusion event gateways by writing Java classes that implement the coldfusion.event-
gateway.Gateway interface. ColdFusion event gateways normally consist of one or more threads that listen for events
from an event provider, such as a Socket, an SMSC server, or some other source. The event gateway sends event
messages to the ColdFusion event gateway service message queue, and provides a method that gets called when an
event gateway application CFC or CFM page sends an outgoing message.
The event gateway class can also do the following:
• Provide the ColdFusion application with access to a helper class that provides event gateway-specific services,
such as buddy-list management or connection management.
• Use a file that specifies configuration information, such as IP addresses and ports, passwords, and other ID infor-
mation, internal time-out values, and so on.
About developing event gateway applications
ColdFusion application developers write applications that use event gateways. The person or company that provides
the event gateway supplies gateway-specific information to the ColdFusion developer. This information must
include the structure and contents of the messages that the ColdFusion application receives and sends to the event
gateway, plus any information about configuration files or helper methods that the ColdFusion application might
use.
The ColdFusion developer writes a CFC that listens for messages. Many event gateway types send messages to a
listener CFC method named
onIncomingMessage. A minimal event gateway application might implement only this
single method. More complex event gateway types can require multiple CFC listener methods. For example, the
ColdFusion XMPP IM event gateway sends user messages to the
onIncomingMessage CFC method, but sends
requests to add buddies to the
onAddBuddyRequest CFC method.
Depending on the event gateway and application types, the event gateway application might include CFM pages or
CFC methods to initiate outgoing messages. The application also might use an event gateway-specific Gateway-
Helper object to do tasks such as getting buddy lists in IM applications or getting a messaging server’s status.
The ColdFusion application developer also configures an event gateway instance in the ColdFusion Administrator,
and possibly in a configuration file. The ColdFusion Administrator configuration information specifies the listener
CFC that handles the messages from the event gateway and other standard event gateway configuration details. The

configuration file, if required, contains event gateway type-specific configuration information.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
106
Event gateway facilities and tools
ColdFusion provides a number of features and tools for developing and deploying event-handling applications, these
including the following:
• Standard event gateways.
• Development tools and example code.
• A gateway directory structure configured for use by custom event gateways and event gateway applications. This
directory also contains the example code.
• An event gateway-specific log file
• Three pages in the ColdFusion Administrator for managing event gateways.
Standard event gateways
Adobe provides several event gateways as part of ColdFusion. These event gateways support the following messaging
protocols:
• SMS (Short Message Service): A system designed for exchanging short, often text, messages with wireless
devices, such as mobile phones or pagers. For detailed information on using the SMS event gateway, see “Using the
SMS Event Gateway” on page 1099.
• XMPP (Extensible Messaging and Presence Protocol): An open, XML-based protocol for instant messaging.
For detailed information on using the XMPP event gateway, see “Using the Instant Messaging Event Gateways” on
page 1083.
• IBM Lotus Instant Messaging: (commonly referred to as Lotus Sametime) The IBM product for real-time
collaboration. For detailed information on using the Lotus Sametime event gateway, see “Using the Instant
Messaging Event Gateways” on page 1083.
ColdFusion also provides an event gateway, the CFML asynchronous event gateway, that lets a CFML application
invoke a CFC method asynchronously. This event gateway does not follow the model of providing a mechanism for
exchanging messages with resources outside of ColdFusion. Instead, it provides a one-way path for invoking CFCs
when an application does not require (indeed, cannot receive) a return value from the CFC. For detailed information
on using the CFML asynchronous event gateway, see “Using the CFML event gateway for asynchronous CFCs” on

page 1075.
Development tools and example code
ColdFusion provides the following tools and example code for developing your own event gateways and event
gateway applications:
• An SMS client (phone simulator) and a short message service center (SMSC) server simulator, for developing
SMS applications without requiring an external SMS provider.
• Four sample event gateways with source code:
• A template for an empty event gateway that contains a skeleton on which you can build your own event
gateways
• A TCP/IP socket event gateway that listens on a TCP/IP port
• A directory watcher event gateway that monitors changes to the contents of a directory
• A Java Messaging Service (JMS) gateway that acts as a JMS consumer or producer.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
106
• Several sample applications, including the following:
• A menu application that uses an inquiry-response drill-down menu to provide services such as weather
reports and stock quotes.
• A simple echo application that sends back the messages that it receives.
• A temperature converter, an asynchronous logging application.
• An application that returns employee phone number and other information.
The chapters in this manual use these example applications.
• Javadoc documentation for the Java interfaces and classes that you use to create gateways.
For more information on these examples, see “Using the example event gateways and gateway applications” on
page 1077.
The ColdFusion gateway directory
The ColdFusion installation includes a cf_root\WEB-INF\cfusion\gateway directory on J2EE configurations, or
cf_root\gateway directory on server configurations. This directory contains all the code for ColdFusion example
event gateways and example event gateway applications, and example configuration files for use by standard
ColdFusion event gateways. You do not have to put your event gateways, event gateway application CFCs, or event

gateway configuration files in this directory, but ColdFusion is configured to find event gateways and CFCs that you
put there.
The following table lists the event gateway directory subdirectories, their purpose, and their initial contents. For
more information on using the example event gateways and applications, see “Using the example event gateways and
gateway applications” on page 1077.
Directory Purpose
cfc Event gateway application CFCs. ColdFusion is installed with an Administrator Mapping between /gateway and this
cfc directory.
cfc/examples Code for the ColdFusion sample applications.
config Configuration files for all ColdFusion event gateways, including standard ColdFusion event gateways, such as SMS,
and example event gateways, such as the directory watcher event gateway.
doc/api Javadoc for the Gateway, and GatewayHelper interfaces, and the CFEvent, GatewayServices, and GenericGateway
classes that gateway developer use when writing gateways. This documentation is a subset of the information in
“Gateway development interfaces and classes” on page 1325 in the CFML Reference.
lib Executable code for example and user-developed event gateway classes. The ColdFusion class loader includes this
directory on its classpath and includes any JAR files that are in that directory on the class path. The examples.jar file
in this directory contains the class files for the DirectoryWatcherGateway, EmptyGateway, and SocketGateway
classes.
src/examples Source code for the example event gateway classes that Adobe provides. Includes the EmptyGateway.java file and
the following subdirectories:
• socket: Socket gateway source files
• watcher: directory watcher gateway source files
• JMS: JMS gateway source files
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
106
The eventgateway.log file
Event gateways provided with ColdFusion log event gateway errors and events to the cf_root\WEB-
INF\cfusion\logs\eventgateway.log file on J2EE configurations, or the cf_root\logs\eventgateway.log file on server
configurations. ColdFusion includes methods that let any event gateway use this file. This log file can be very useful

in debugging event gateways and event gateway applications.
ColdFusion Administrator event gateway pages
The ColdFusion Administrator includes a Gateways section with three pages for managing event gateways:
• Settings
• Gateway types
• Gateways
The Settings page lets you enable and disable support for event gateways, specify the number of threads that
ColdFusion can devote to processing events, specify the maximum number events that ColdFusion can hold in its
event queue (which holds events that are waiting to be processed) and start the SMS test server.
The Gateway Types page lets you add, remove, and configure event gateway types by specifying a name, a Java class,
and startup time-out behavior.
Note: The gateway type name in the ColdFusion Administrator does not have to be the same as the gateway type that is
used in the gateway Java code and the
CFEvent data structure; however, you should use the same name in both places
for consistency.
The Gateways page lets you add, remove, configure, start, and stop individual event gateway instances. You configure
an event gateway instance by specifying a unique ID, the gateway type, one or more listener CFC paths, a configu-
ration file (not required for all gateway types), and a startup mode (manual, automatic, or disabled).
Structure of an event gateway application
To develop an event gateway application, you create and use some or all of the following elements:
• One or more listener CFCs that handle any incoming messages and send any necessary responses.
• In some applications, ColdFusion pages that generate outgoing messages directly.
• An event gateway instance configuration in the ColdFusion Administrator. This configuration might require a
separate event gateway configuration file.
• In some applications, a GatewayHelper object to provide access to additional features of the protocol or
technology; for example, to manage instant messaging buddy lists.
The role of the listener CFC
All incoming event messages must be handled by one or more listener CFCs. You specify the listener CFCs when you
configure an event gateway in the ColdFusion Administrator. You must specify at least one CFC in the administrator.
Some gateway types can use more than one CFC. By default, the ColdFusion event gateway service delivers events

by calling the CFC’s
onIncomingMessage method.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
106
The event gateway developer must inform the event gateway application developer of methods that the listener CFC
must implement (may be only the
onIncomingMessage method) and of the structure and contents of the event
message data, contained in the CFEvent instance, that the listener CFC must handle. Outgoing messages have the
same event message data structure as incoming messages.
Many gateways let the listener CFCs send a response by calling the
cfreturn function, but ColdFusion does not
require a return value. Listener CFCs can also use the
SendGatewayMessage function, which provides more flexi-
bility than the
cfreturn tag.
The role of ColdFusion pages
ColdFusion CFM pages cannot receive event messages. However, they can send messages using an event gateway.
Therefore, an event gateway application that initiates outgoing messages might use one or more
SendGatewayMessage functions to send the messages. An application that sends an SMS message to notify users
when a package ships, for example, could use the
SendGatewayMessage function to send the notification.
The role of the ColdFusion Administrator
The Gateways page in the ColdFusion Administrator associates a specific event gateway instance with one or more
listener CFCs that processes messages from the event gateway. It tells the ColdFusion event gateway service to send
messages received by the event gateway to the listener CFC. It also lets you specify a configuration file for the event
gateway instance and whether to start the event gateway instance (and therefore any responder application) when
ColdFusion starts. For more information on using the Administrator, see the ColdFusion Administrator
online Help.
The role of the GatewayHelper object

A ColdFusion event gateway provides an information conduit: at its most basic, it receives and dispatches event
messages. In some cases, however, an event gateway must provide additional functionality. An instant messaging
event gateway, for example, needs to provide such services as managing buddies and providing status information.
To support such use, an event gateway can enable access to a GatewayHelper object. The event gateway developer
writes a Java class that provides the necessary utility routines as Java methods, and ColdFusion application devel-
opers can get an instance of the class by calling the CFML
GetGatewayHelper method. The application calls the
GatewayHelper object’s methods using normal ColdFusion object access techniques. The ColdFusion instant
messaging event gateways and the example socket event gateway provide GatewayHelper objects.
Configuring an event gateway instance
Before you develop or deploy an event gateway application, you must use the ColdFusion Administrator to configure
an event gateway instance that will handle the event messages. You specify the following information:
• An event gateway ID to identify the specific event gateway instance. You use this value in the CFML
GetGatewayHelper and SendGatewayMessage functions.
• The event gateway type, which you select from the available event gateway types, such as SMS or Socket.
• The absolute path to the listener CFC or CFCs that will handle incoming messages. If you have multiple listener
CFCs, enter the paths separated by commas. You must specify absolute file paths, even if you put the CFCs in the
ColdFusion gateway\cfc directory.
• A configuration file, if required for this event gateway type or instance.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
106
• The event gateway start-up status; one of the following:
Automatic: Start the event gateway when ColdFusion starts.
Manual: Do not start the event gateway with ColdFusion, but allow starting it from the ColdFusion Adminis-
trator Event Gateways list.
Disabled: Do not allow the event gateway to start.
Developing an event gateway application
All event gateway applications handle information. They exchange event messages, and possibly other types of infor-
mation, 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 similar to most ColdFusion applications. At some point, ColdFusion executes a CFM page
in response to a request. (The request could be initiated by the ColdFusion Administrator Scheduled Tasks page.)
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’s 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 might use the
SendGatewayMessage function either in place or in addition to the return
value.
ADOBE COLDFUSION 8

ColdFusion Developer’s Guide
106
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” on page 1074. For more infor-
mation on the instant messaging GatewayHelper object, see “Sample IM message handling application” on
page 1088.
The example code in “Example event gateway CFC” on page 1072 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 needs to 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 configu-
ration 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 listener CFC’s
onIncomingMessage method. For the sake of consistency, Adobe recommends that any event gateway with a single
listener method use the
onIncomingMessage method.
The listener method does the following:
1 Takes a single parameter, a CFEvent structure, described in the following section.

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>
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
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 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’s 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 event gateway’s
outgoingMessage method.
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.
Field Description
GatewayID The event gateway that sent the event; the value is the ID of an event gateway instance configured on the ColdFusion
Administrator Gateways page. If the application calls the SendGatewayMessage function to respond to the event
gateway, it uses this ID as the function’s first parameter.
Data A structure containing the event data, including the message. The Data structure contents depend on the event
gateway type.
OriginatorID The originator of the message. The value depends on the protocol or event gateway type. Many event gateways
require this value in response messages to identify the destination of the response. Identifies the sender of the
message.
GatewayType The type of event gateway, such as SMS. An application that can process messages from multiple event gateway
types can use this field. This value is the gateway type name that is specified by the event Gateway class. It is not
necessarily the same as the gateway type name in the ColdFusion Administrator.
CFCPath The location of the listener CFC. The listener CFC does not need to use this field.
CFCMethod The listener method that ColdFusion invokes to process the event. The listener CFC does not need to use this field.
CFCTimeout The time-out, in seconds, for the listener CFC to process the event request. The listener CFC does not need to use this
field.
Identifier Structure
Session ID gatewayType_gatewayID_originatorID

cfid originatorID
cftoken gatewayType_gatewayID
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
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 might be used to send
messages. Also, you can put 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 appli-
cation 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 a message sender’s ID. 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 interac-
tions with a particular client. For many technologies and gateways, such as the IM and SMS gateways, this is not an
issue.
Note: To use Client scope variables with gateways, you must store the Client scope variables in a data source or the
registry. You cannot store the variables in cookies, because gateways do not use cookies.
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 those used for request-driven sessions and clients, 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 might handle 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.
Note: ColdFusion cannot create a session if an initiator application uses a
SendGatewayMessage method to start an
interaction with a client, such as an SMS user. In this case, the sending code must keep track (for example, in a database)
of the messages it sends and their destinations. When a response event arrives, it can look up the origniatorID to
determine whether it was in response to an outgoing message.
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, you should consider the following debugging techniques:
• Put trace variables in the Application scope. These variables persist, and you can specify an application name for
your CFC (see “Application scope” on page 1071). You can inspect the Application scope contents, including your
trace variables, in any CFML page that has the same application name as your CFC.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
• 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 event-
gateway.log file, see “The eventgateway.log file” on page 1066.
• 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 put 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>
Note: You do not have to restart the event gateway instance when you make changes to a CFC. ColdFusion automatically
uses the updated CFC when the next event occurs.
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:
<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">
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
<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>
Sending a message using the SendGatewayMessage function
The SendGatewayMessage function has the following format:
SendGatewayMessage(gatewayID, messageStruct)
• The gatewayID parameter must be the gateway ID specified in the ColdFusion Administrator for the event
gateway instance that will send the message.
• The messageStruct parameter is a structure whose contents depends on the requirements of the event gateway’s
outgoingMessage method, and possibly the recipient application. For example, in addition to any message, the
structure might 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.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
<cfscript>
status = "No";
props = structNew();
props.Message = "Replace me with a variable with data to log";
status = SendGatewayMessage("Asynch Logger", props);
if (status IS "OK") WriteOutput("Event Message ""#props.Message#"" has been sent.");
</cfscript>
Note: To see the code for the CFC that logs the information, see “Using the CFML event gateway for asynchronous CFCs”
on page 1075.
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 might 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 appli-
cation (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 J2EE and Java Elements in CFML Applications” on page 927). 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:
<cfscript>
myHelper = GetGatewayHelper(myGatewayID);
status = myHelper.addBuddy("jsmith23", "Jim Smith", "support");
</cfscript>
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 infor-
mational 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:
gatewayType (gatewayID) message body
When you are developing an event gateway application, you can use the ColdFusion Log viewer to inspect the event-
gateway.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.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
Deploying event gateways and applications
To deploy an event gateway application in a ColdFusion server, you must install your listener CFC and configure an
gateway instance that uses the CFC.
Deploy an event gateway application
1 Ensure that the ColdFusion Administrator is configured with the required event gateway type. If it is not, deploy
the event gateway type (see “Deploying an event gateway” on page 1140).
2 If the event gateway type requires a configuration file, ensure that there is a valid file in the gateway\config
directory. Some event gateways might be designed to let multiple event gateway instances share a configuration file.
Others might require a separate file for each event gateway instance.

3 Install the event gateway application listener CFC and any other application components. ColdFusion provides
a cf_root\gateways\cfc directory as a convenient location for these CFCs, and includes a mapping in the ColdFusion
Administrator page for that directory. However, ColdFusion does not require you to install the listener CFC in this
directory.
4 Configure an event gateway instance on the Gateways page of the Event Gateways section in the ColdFusion
Administrator (see “Configuring an event gateway instance” on page 1067)
Using the CFML event gateway for asynchronous CFCs
The ColdFusion CFML event gateway lets CFML code send a message to CFC methods asynchronously. This event
gateway lets you initiate processing by a CFC method without waiting for it to complete or return a value. Possible
uses for asynchronous CFCs that you access using this event gateway include the following:
• Reindexing a Verity collection with new information without delaying an application, for example, when a user
uploads a new file
• Logging information, particularly if there is significant amount of data to log
• Running batch processes that might take a substantial amount of time to complete
Because asynchronous CFCs run independently of a request, they do not provide feedback to the user. You must save
any results or error information to a file, data source, or other external resource.
By default, ColdFusion delivers the message to a CFC method named onIncomingMessage. You can specify any
method name, however, in the
SendGatewayMessage method’s data parameter.
CFML event gateway data structure
The structure that you use in the CFML SendGatewayMessage function can include two types of fields:
• The structure can include any number of fields with arbitrary contents for use in by the CFC.
• Several optional fields can configure how the gateway delivers the information to the CFC.
The CFML gateway looks for the following optional fields, and, if they exist, uses them to determine how it delivers
the message. Do not use these field names for data that you send to your CFC method.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
Using the CFML gateway
The following procedure describes how to use an asynchronous CFC that has a single, onIncomingMessage method.

Use an asynchronous CFC
1
Create a CFC with an onIncomingMessage method. Put the CFC in an appropriate directory for your appli-
cation. For example, you can put it in the cf_root\WEB-INF\cfusion\gateway\cfc directory on J2EE configurations,
in the cf_root\gateway\cfc directory on server configurations, or in a subdirectory of these directories. ColdFusion
is installed with mappings to these cfc gateway directories.
The
onIncomingMessage method must take a CFEvent structure that contains input information in its Data
field, and processes the contents of the Data field as needed.
2 Use the Gateways page in the ColdFusion Administrator to add an instance of the CFML event gateway type.
Specify the following:
• A unique Gateway ID.
• The path to the CFC that you created in step 1.
• The startup mode. Select Automatic startup mode to start the event gateway when ColdFusion starts up.
• Do not specify a configuration file.
3 Start the event gateway instance.
4 Write CFML code that uses SendGatewayMessage functions to send messages in structures to the event gateway
instance ID that you specified in step 2. The
SendGatewayMessage function returns true if the gateway successfully
queues the message in the ColdFusion Gateway Service; false, otherwise. It does not ensure that the CFC receives or
processes the message.
5 Run your CFML application.
Example: logging messages
The following asynchronous CFML event gateway CFC uses the cflog tag to log a message to a file in the
ColdFusion logs directory. The CFC takes a message with the following fields:
• file The name of the file in which to put the message. The default value is defaultEventLog.
• type The cflog type attribute to use. The default value is info.
• message The message text.
<cfcomponent>
Field Use

cfcpath Overrides the CFC path specified in the ColdFusion Administrator. This field lets you use a single gateway configura-
tion in the ColdFusion Administrator multiple CFCs.
method Sets the name of the method to invoke in the CFC. The default method is onIncomingMessage. This field lets you
use a single gateway configuration in the ColdFusion Administrator for a CFC that has several methods.
originatorID Sets the originatorID field of the CFEvent object that ColdFusion delivers to the CFC. The default value is CFML-
Gateway.
timeout Sets the time-out, in seconds, during which the listener CFC must process the event request and return before Cold-
Fusion gateway services terminates the request. The default value is the Timeout Request value set on the Server
Settings page in the ColdFusion Administrator. Set this value if a request might validly take longer to process than
the default timeout; for example, if the request involves a very long processing time.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
<cffunction name="onIncomingMessage" output="no">
<cfargument name="CFEvent" type="struct" required="yes">
<cfscript>
if (NOT IsDefined("CFEvent.Data.file")) {
CFEvent.Data.file="defaultEventLog"; }
if (NOT IsDefined("CFEvent.Data.type")) {
CFEvent.Data.type="info"; }
</cfscript>
<cflog text="#CFEvent.Data.message#"
file="#CFEvent.Data.file#"
type="#CFEvent.Data.type#"
thread="yes"
date="yes"
time="yes"
application="yes">
</cffunction>
</cfcomponent>

The following minimal CFML page tests the event gateway:
Sending an event to the CFML event gateway that is registered in the
ColdFusion Administrator as Asynch Logger.<br>
<cfscript>
status = false;
props = structNew();
props.Message = "Replace me with a variable with data to log";
status = SendGatewayMessage("Asynch Logger", props);
if (status IS True) WriteOutput(’Event Message "#props.Message#" has been sent.’);
</cfscript>
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. 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” on page 1128
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
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 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 Gateway-
Helper 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 Administrator uses DirectoryWatcher as the gateway type name for the DirectoryWatcher-
Gateway 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 value is all files.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
107
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#">
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.
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.
Property Req/Opt Description
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
108
</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:
• Tex tMes sa ge
• 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:
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

Field Contents
status Must be SEND.
topic Name of the topic to publish the message to.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
108
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:
a 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.
b 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.
c 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).
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.
Field Contents
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
108
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 Gateways 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 might also be
prompted to enter M to get more. Enter M (if there is more information 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.
108
Chapter 57: Using the Instant Messaging
Event Gateways
You can develop an application that uses either of two instant message (IM) event gateway types provided with
ColdFusion: an IBM Lotus Sametime gateway, and an Extensible Messaging and Presence Protocol (XMPP) gateway.
You should be familiar with ColdFusion event gateway principles and programming techniques (see “Using Event
Gateways” on page 1060).
Contents
About ColdFusion and instant messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1083
Configuring an IM event gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1085
Handling incoming messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087
Sending outgoing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1087
Sample IM message handling application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1088
Using the GatewayHelper object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1093
About ColdFusion and instant messages
ColdFusion includes two instant messaging gateway types: one for messaging using the XMPP protocol, and one for
IBM Lotus Instant Messaging (Sametime). These gateway types use identical interfaces for sending and receiving
messages and for managing the IM presence information and infrastructure. This chapter, therefore, refers to IM
gateways, and only describes the two types where there are differences.

The ColdFusion IM gateways act as IM clients and let you do the following:
• Send and receive instant messages.
• Send and respond to buddy or friend requests and manage buddy/friend information.
• Set and get status and other information.
• Receive and handle messages from the IM server.
About XMPP
XMPP (Extensible Messaging and Presence Protocol) is an open, XML-based protocol for instant messaging. It is the
core protocol of the Jabber Instant Messaging and Presence technology that is developed by the Jabber Software
Foundation. As of November 2004, XMPP was defined by four Internet Engineering Task Force (IETF) specifica-
tions (RFCs), numbers 3920-3922. RFC 3920 covers the XMPP core, and 3921, covers instant messaging and
presence. Numerous XMPP servers and clients are available. ColdFusion supports the IETF XMPP protocol.
The following websites provide additional information about the XMPP protocol:
• Jabber Software Foundation: www.jabber.org/. This site includes information on available XMPP servers and
clients.
• IETF has copies of the internet standards for XMPP: www.ietf.org/rfc/.
ADOBE COLDFUSION 8
ColdFusion Developer’s Guide
108
• The xmpp.org website was under development as of December 2004; at that time it included several useful links,
including links to relevant specifications: www.xmpp.org/.
About IBM Lotus Instant Messaging (Sametime)
IBM Lotus Instant Messaging, commonly referred to as Lotus Sametime, is the IBM product for real-time collabo-
ration. For more information about this product, see www.lotus.com/sametime.
Note: In the Enterprise Edition, to use the Lotus Sametime event gateway, you must disable FIPS-140 Compliant Strong
Cryptography by adding the following to the JVM arguments in the ColdFusion Administrator:
-Dcoldfusion.disablejsafe=false
About IM application development and deployment
The following sections introduce the ColdFusion IM application development tools and process, and discuss IM
messaging providers.
ColdFusion IM gateway classes

ColdFusion provides the following instant messaging gateway classes:
XMPPGateway: The class for the XMPP event gateway type
SAMETIMEGateway: The class for the IBM Lotus Instant Messaging event gateway
You implement your IM application by configuring a gateway instance in ColdFusion Administrator that uses one
of these gateway classes and creating a ColdFusion application that uses the gateway instance to communicate with
an instant messaging server.
Application development and deployment process
The following is a typical process for developing and deploying an IM application:
1 Design your application.
2 Configure an IM event gateway instance to use an available XMPP or Lotus Sametime server.
3 Write your CFCs, CFM pages, and any other application elements.
4 Test your application using your XMPP or Lotus Sametime server and an appropriate client application.
5 Deploy the application (see “Deploying event gateways and applications” on page 1075).
How the IM event gateway and provider interact
Each IM event gateway instance has a single instant messaging ID. You must establish the ID and its related password
on the IM server using server-specific tools, such as a standard instant messaging client. In ColdFusion, you set the
ID, password, and other gateway-specific information in a gateway configuration file, and you create a gateway
instance that uses this file.
When you start the gateway, it logs onto the IM server with the ID and password, and receives and sends the
messages for the ID. The gateway sends incoming messages to a CFC, which you specify when you configure the
gateway instance in the ColdFusion Administrator. The gateway passes outgoing messages from this CFC and from
other CFML code to the IM server.
The IM event gateway also provides a number of helper methods for managing the gateway and its configuration
information.