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.

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 flexibility 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 developers 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.