Understanding Event Gateways

Event gateways are connectors, bridges between ColdFusion and other systems and technologies. Whereas out of the box ColdFusion can respond to HTTP requests (via Web Server connectors) and can talk to a variety of back-end technologies (databases, LDAP, Web Services, and more), event gateways allow ColdFusion to respond to and interact with just about anything.

note

Event gateways are supported in ColdFusion Enterprise and ColdFusion Developer Edition, but not in ColdFusion Standard.

Gateway Internals

A thorough understanding of event gateway processing is required to effectively leverage this powerful technology.

The Event Gateway Service

ColdFusion includes an event gateway service, a process that may be started or stopped from within the ColdFusion Administrator. The gateway service queues and processes all gateway requests, and must be running for any gateways to be used.

NOTE

ColdFusion remembers the gateway service setting, and will automatically restart it upon server restart if needed.

All gateway requests are routed by ColdFusion to the event gateway service. The service queues requests until a thread is available, and then hands it off for execution within a thread. If the queue is full, requests will not be executed and an exception will be thrown.

TIP

The default request queue size is 25000 and the default number of available threads for event gateway processing is 10. These values can be changed using the ColdFusion Administrator.

Gateway Types

Gateways themselves are written in Java, and must be registered with ColdFusion as a gateway type before use. Registration maps a gateway type name to a Java class file (the actual gateway). The ColdFusion Administrator providers an interface for registering and managing gateway types.

The Java classes are generally not tied to any specific ColdFusion code or implementation. Rather, they are tied to specific back-ends or technologies and provide hooks that ColdFusion code can tie in to. For example, a gateway to an ERP system would need to be intimately tied to that system, exposing functionality that ColdFusion code could then connect to.

NOTE

The Java code for a stubbed gateway is included with ColdFusion, as is code for several complete working examples. These can be used as starting point for your own gateways.

ColdFusion ships with a set of gateways already installed and registered ready for you to use:

• CFML provides access to asynchronous ColdFusion processing.

• Directory Watcher allows developers to write code that will be automatically executed when changes are made to a watched directory (file added, file changed, file deleted).

• JMS provides access Java Message Service queuing.

• SAMETIME provides Lotus Sametime integration.

• SMS enables communication between ColdFusion and SMS clients and devices.

• Socket allows ColdFusion to respond to activity on watched sockets.

• XMPP provides access to instant messaging via XMPP.

Gateway Instances

Gateway instances are specific uses of gateways, a Java gateway type and an associated ColdFusion Component. Gateway instances are also registered in the ColdFusion Administrator, and there is no limit to the number of gateway instances that may be defined nor the number of instances of any gateway type.

NOTE

Gateway instances are bound to ColdFusion Components, and not to .cfm files.

Back to the ERP example, if three different ColdFusion applications (doing very different things) all had to interact with the ERP system, there would likely be three gateway instances defined (each with a different CFC tied to the same Java class).

NOTE

Gateway instances can also point to optional configuration files, plain text files that contain gateway settings. This allows for the same gateway to be used with different options or settings defined.

When gateway instances are defined, a startup mode is specified:

• Automatic starts gateway instances automatically upon server start-up.

• Manual makes the gateway instance usable, but it will need to be manually started to be used.

• Disabled prevents a gateway instance from being used.

TIP

The Gateway Instance screen in the ColdFusion Administrator displays two counters for each gateway, in is the number of inbound requests and out is the number of outbound requests. This activity indicator is a useful debugging tool.

Initiators And Responders

Event gateway activity falls into one of two categories (and specific gateway types support either or both, depending on what the gateway does).

• Initiator gateways are those where ColdFusion (or CFML code) trigger execution. For example, a ColdFusion event gateway instance may initiate a JMS transaction by placing an item on an outbound JMS queue. Or a ColdFusion event gateway instance my send an IM or SMS message to inform a user that an error has occurred.

• Responder gateways are those where ColdFusion event gateway execution is triggered by an external event. For example. A file uploaded to a watch folder could trigger CFML code to be executed via a directory watcher gateway. Or an IM or SMS message from a user may cause ColdFusion to execute a database query the results of which are sent back via a return message.

In the examples listed here, the directory watcher gateway instance is a responder, the JMS gateway instance is an initiator, and the IM and SMS gateways are both initiators and responders.