Adobe ColdFusion 8

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

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.

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

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.

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" 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

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 configuration file (not required for all gateway types), and a startup mode (manual, automatic, or disabled).