Event gateway elements

You use the following the elements to create and configure a gateway:

Note: The gateway interfaces and classes, with the exception of the GenericGateway class are fully documented in "Gateway development interfaces and classes" in the CFML Reference. All interfaces and classes in this list, including the GenericGateway class, are documented in less detail in the Javadocs located in the ColdFusion gateways\docs directory. The Javadocs documentation lacks examples and does not have the detailed usage information that you find in the CFML Reference.

Gateway interface

The ColdFusion event gateway must implement the coldfusion.eventservice.Gateway interface. The following table lists the interface method signatures:

Note: For detailed information on implementing each method, see Building an event gateway. For reference pages for these methods, see Gateway interface in the CFML Reference.

Signature	Description
`void setGatewayID(String id)`	Sets the gateway ID that uniquely identifies the gateway instance. ColdFusion calls this method before it starts the event gateway, even if the gateway class constructor also sets the ID.
`void setCFCListeners(String[]` listeners`)`	Identifies the CFCs that listen for incoming messages from the event gateway. The array contains one or more paths to the listener CFCs. ColdFusion calls this method before it starts the event gateway, and if the configuration for a running event gateway changes.
`GatewayHelper getHelper()`	Returns a coldfusion.eventgateway.GatewayHelper class instance, or null. The GatewayHelper class provides event gateway-specific utility methods to CFML applications. ColdFusion calls this method when a ColdFusion application calls the `GetGatewayHelper` function.
`String getGatewayID()`	Returns the gateway ID.
`int getStatus()`	Gets the event gateway status. The interface defines the following status constants: `STARTING`, `RUNNING`, `STOPPING`, `STOPPED`, `FAILED`.
`void start()`	Starts the event gateway. Starts at least one thread for processing incoming messages. ColdFusion calls this method when it starts an event gateway.
`void stop()`	Stops the event gateway. Stops the threads and destroys any resources. ColdFusion calls this method when it stops an event gateway.
`void restart()`	Restarts a running event gateway. ColdFusion calls this method when the ColdFusion Administrator restarts a running event gateway.
`String outgoingMessage (coldfusion. eventgateway.CFEvent` cfmessage`)`	Handles a message sent by ColdFusion and processes it as needed by the gateway type to send a message. ColdFusion calls this method when a listener CFC's listener method returns a CFEvent or when a ColdFusion application calls the `SendGatewayMessage` function. The CFML `SendGatewayMessage` function gets the returned String as its return value.

GatewayServices class

The Gateway class uses the coldfusion.eventgateway.GatewayServices class to interact with the ColdFusion event gateway services. This class has the following methods:

Signature	Description
`GatewayServices getGatewayServices()`	Static method that returns the GatewayServices object. Gateway code can call this method at any time, if required.
`boolean` `addEvent(CFEvent` msg`)`	Sends a `CFEvent` instance to ColdFusion for dispatching to a listener CFC. The event gateway uses this method to send all incoming messages to the application for processing. Returns False if the event is not added to the queue.
`int getQueueSize()`	Returns the current size of the ColdFusion event queue. This queue handles all messages for all gateways.
`int getMaxQueueSize()`	Returns the maximum size of the ColdFusion event queue, as set in the ColdFusion Administrator.
`Logger getLogger() Logger getLogger(String logfile)`	Returns a ColdFusion Logger object that the event gateway can use to log information in the eventgateway.log log file (the default) or the specified log file. The logfile attribute must be a filename without a file extension, such as mylogifile. ColdFusion puts the file in the ColdFusion logs directory and appends .log to the specified filename. For information on using the logger object, see Logging events and using log files.

CFEvent class

The Gateway class sends and receives CFEvent instances to communicate with the ColdFusion listener CFC or application. The Gateway notifies ColdFusion of a message by sending a CFEvent instance in a GatewayServices.addEvent method. Similarly, the Gateway receives a CFEvent instance when ColdFusion calls the gateway's outgoingMessage method.

The CFEvent class extends the java.util.Hashtable class and has the following methods to construct the instance and set and get its fields. (In CFML, you treat CFEvent instances as structures.)

Methods	Description
`CFEvent(String gatewayID)`	CFEvent constructor. The gatewayID parameter must be the value that is passed in the gateway constructor or set using the Gateway `setGatewayID` method.
`void setGatewayType(String type) String getGatewayType()`	Identifies the type of event gateway, such as SMS. For the sake of consistency, use this name in the Type Name field when you add an event gateway type on the Gateway Types page in the ColdFusion Administrator.
`void setData(Map data) Map getData()`	The event data; includes the message being passed to or from ColdFusion. The content of the field depends on the event gateway type. The Map keys must be strings. Because ColdFusion is not case-sensitive, it converts the Map passed in the `setData` method to a case-insensitive Map. As a result, do not create entries in the data with names that differ only in case.
`void setOriginatorID(String id) String getOriginatorID()`	Identifies the originator of an incoming message or the destination of an outgoing message. The value depends on the protocol or event gateway type.
`void setCFCPath(String path) String getCFCPath()`	An absolute path to the application listener CFC that will process the event. By default, ColdFusion uses the first path configured for the event gateway instance on the Event Gateways page in the ColdFusion Administrator.
`void setCFCMethod(String method) String getCFCMethod()`	The method in the listener CFC that ColdFusion calls to process this event. By default, ColdFusion invokes the `onIncomingMessage` method. For the sake of consistency, Adobe recommends that any event gateway with a single listener not override this default. A gateway, such as the ColdFusion XMPP gateway, that uses different listener methods for different message types, uses this method to identify the destination method..
`void setCFCTimeout(String seconds) String getCFCTimeout()`	The time-out, in seconds, for the listener CFC to process the event request. When ColdFusion calls the listener CFC to process the event, and the CFC does not process the event in the specified time-out period, ColdFusion terminates the request and logs an error in the application.log file. By default, ColdFusion uses the Timeout Request value set on the Server Settings page in the ColdFusion Administrator.
`String getGatewayID()`	The event gateway instance that processes the event. Returns the gateway ID that was set in the CFEvent constructor.

GatewayHelper class

ColdFusion includes a coldfusion.eventgateway.GatewayHelper Java marker interface. You implement this interface to define a class that provides gateway-specific utility methods to the ColdFusion application or listener CFC. For example, an instant messaging event gateway might use a helper class to provide buddy list management methods to the application.

The Gateway class must implement a getHelper method that returns the helper class or null (if the gateway does not need such a class).

ColdFusion applications call the GetGatewayHelper CFML function, which invokes gateway's the getHelper method to get an instance of the helper class. The application can then call helper class methods using ColdFusion object dot notation.

The following code defines the SocketHelper class, the gateway helper for the SocketGateway class. It has an empty constructor and two public methods: one returns the socket IDs; the other closes a specified socket. These classes let an application monitor and end session connections.

public class SocketHelper implements GatewayHelper {
    public SocketHelper() {
    }
    public coldfusion.runtime.Array getSocketIDs () {
        coldfusion.runtime.Array a = new coldfusion.runtime.Array();
        Enumeration e = socketRegistry.elements();
        while (e.hasMoreElements()) {
            a.add(((SocketServerThread)e.nextElement()).getName());
         }
         return a;
     }
    public boolean killSocket (String socketid) {
        try
        {
            ((SocketServerThread)socketRegistry.get(socketid)).socket.close();
            ((SocketServerThread)socketRegistry.get(socketid)).socket = null;
            socketRegistry.remove(socketid);
            return true;
        }
        catch (IOException e) {
            return false;
        }
    }
}

Gateway configuration file

Gateways can use a configuration file to specify information that does not change frequently. For example, the ColdFusion SMS event gateway configuration file contains values that include an IP address, port number, system ID, password, and so on.

You can specify a configuration file path for each event gateway instance in the ColdFusion Administrator. ColdFusion passes the file path in the gateway constructor when it instantiates the event gateway. The configuration file format and content handling is up to you. It is the responsibility of the gateway class to parse the file contents and use it meaningfully.

One good way to access and get configuration data is to use the java.util.Properties class. This class takes an ISO8859-1 formatted input stream with one property setting per line. Each property name must be separated from the value by an equal sign (=) or a colon (:), as the following example shows:

ip-address=127.0.0.1
port=4445

The example SocketGateway event gateway uses this technique to get an optional port number from a configuration file. For an example of reading a properties file and using its data, see the code in Class constructor.

Gateway development classes

ColdFusion provides two classes that you can use as building blocks to develop your event gateway classes. Each corresponds to a different development methodology:

The coldfusion.eventgateway.GenericGateway class is an abstract class from which you can derive your gateway class.
The EmptyGateway class in the gateway\src\examples directory is a template gateway that you can complete to create your gateway class.

The GenericGateway class

ColdFusion includes a coldfusion.eventgateway.GenericGateway abstract class that implements many of the methods of ColdFusion Gateway interface and provides some convenience methods for use in your gateway class.

You can derive your gateway class from this class, which handles the basic mechanics of implementing a gateway, such as the getGatewayID and SetCFCListeners methods. Your derived class must implement at least the following methods:

startGateway (not start)
stopGateway (not stop)
outgoingMessage

Your derived gateway class also must implement the following:

If you support a configuration file, a constructor that takes a configuration file, and configuration loading routines.
If you use a gatewayHelper class, the getHelper method.
If the event source status can change asynchronously from the gateway, the getStatus method.

The example JMS gateway is derived from the generic gateway class. The gateway class JavaDocs in the gateway\docs directory provide documentation for this class. (The CFML Reference does not document this class.)

The EmptyGateway class

The gateway\src\examples\EmptyGateway.java file contains an event gateway template that you can use as a skeleton for creating your own event gateway. (The gateway directory is in the cf_root directory in the server configuration and the cf_root\WEB-INF-cfusion directory on J2EE configurations.) This file contains minimal versions of all methods in the coldfusion.eventgateway.Gateway interface. It defines a skeleton listener thread and initializes commonly used Gateway properties. The EmptyGateway source code includes comments that describe the additional information that you must provide to complete an event gateway class.

Adobe ColdFusion 8