Whatever message this page gives is out now! Go check it out!
Event gateway elements
Last update:
May 18, 2026
You use the following the elements to create and configure a gateway:
- Gateway interface
- GatewayServices class
- CFEvent class
- GatewayHelper class
- Gateway configuration file
- Gateway development classes
Note: The gateway interfaces and classes, except for 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 the listener method of a listener CFC 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 necessary. |
boolean addEventmsg) | 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. |
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 filename extension, such as mylogifile. ColdFusion places 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 in Building an event gateway . |
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 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 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 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. |
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 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 path)String getCFCPath | An absolute path to the application listener CFC that processes 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 method)String getCFCMethod | The method in the listener CFC that ColdFusion calls to process this event. By default, ColdFusion calls the onIncomingMessage method. For the sake of consistency, Adobe recommends that any event gateway with a single listener does 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 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 could 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 calls 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 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:
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.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
