An event gateway can implement any of the following constructors:

• MyGateway(String gatewayID, String configurationFile)

• MyGateway(String gatewayID)

• MyGateway()

When ColdFusion starts, it calls the constructor for each event gateway instance that you configure in ColdFusion. (ColdFusion also calls the gateway Start method after the event gateway is instantiated.). ColdFusion first attempts to use the two-parameter constructor.

Because each event gateway instance must have a unique ID, ColdFusion provides redundant support for providing the ID. If the event gateway implements only the default constructor, ColdFusion provides the ID by calling the setGatewayID method of the event gateway.

If the event gateway does not implement the two-parameter constructor, it does not get configuration file information from ColdFusion.

The constructor normally calls the static GatewayServices.getGatewayServices method to access ColdFusion event gateway services. Although you need not make this call, it is a good coding practice.

A minimal constructor that takes only a gateway ID could look like the following:

public MyGateway(String gatewayID) { 
    this.gatewayID = gatewayID; 
    this.gatewayService = GatewayServices.getGatewayServices(); 
}

The gateway constructor must throw a coldfusion.server.ServiceRuntimeException exception if an error occurs that otherwise cannot be handled. For example, throw this exception if the event gateway requires a configuration file and cannot read the file contents.

If your gateway uses a configuration file, have the constructor load the file, even if the Start method also loads the file. Load the file because the constructor does not run in an independent thread, and ColdFusion can display an error in the ColdFusion Administrator of the file fails to load. If the Start method, which does run in a separate thread, fails to load the file, ColdFusion logs the error, but it cannot provide immediate feedback in the administrator.

The sample Socket event gateway has a single constructor that takes two parameters. It tries to load a configuration file. If you specify a configuration file in the ColdFusion Administrator, or the file path is invalid, it gets an IO exception. It then uses the default port and logs a message indicating what it did. The following example shows the Gateway constructor code and the loadProperties method it uses:

public SocketGateway(String id, String configpath) 
{ 
    gatewayID = id; 
    gatewayService = GatewayServices.getGatewayServices(); 
    // log things to socket-gateway.log in the CF log directory 
    log = gatewayService.getLogger("socket-gateway"); 
    propsFilePath=configpath; 
    try 
    { 
        FileInputStream propsFile = new FileInputStream(propsFilePath); 
        properties.load(propsFile); 
        propsFile.close(); 
        this.loadProperties(); 
     } 
     catch (IOException e) 
    { 
        // Use default value for port and log the status. 
        log.warn("SocketGateway(" + gatewayID + ") Unable to read configuration  
            file '" + propsFilePath + "': " + e.toString() + ".Using default port 
            " + port + ".", e); 
    } 
} 
 
private void loadProperties() { 
    String tmp = properties.getProperty("port"); 
    port = Integer.parseInt(tmp); 
}

Several gateway methods perform event gateway configuration services and provide event gateway information. The ColdFusion event gateway services call many of these methods to configure the event gateway by using information stored by the ColdFusion Administrator, and to get access to resources and information that the event gateway services and applications require. Some of these methods can also be useful in event gateway code. The following methods provide these services and information:

• setCFCListeners

• setGatewayID

• getHelper

• getGatewayID

• getStatus

ColdFusion calls the setCFCListeners method with the CFC or CFCs that are specified in the ColdFusion Administrator when it starts a gateway. ColdFusion also calls the method in a running event gateway when the configuration information changes, so the method must be written to handle such changes. The setCFCListeners method must save the listener information so that the gateway code that dispatches incoming messages to gateway services can use the listener CFCs in setCFCPath methods.

ColdFusion calls the setGatewayID method when it starts a gateway. The getGatewayID method must return the value set by this method.

ColdFusion calls the getHelper method when an application calls the CFML GetGatewayHelper function.

The following code shows how the SocketGateway class defines these methods. To create a gateway, modify the getHelper definition to return the correct class, or to return null if no gateway helper class exists. Most gateways can leave the other method definitions unchanged.

public void setCFCListeners(String[] listeners) { 
    this.listeners = listeners; 
} 
public GatewayHelper getHelper() { 
    // SocketHelper class implements the GatewayHelper interface. 
    return new SocketHelper(); 
} 
public void setGatewayID(String id) { 
    gatewayID = id; 
} 
public String getGatewayID() { 
    return gatewayID; 
} 
public int getStatus() { 
    return status; 
}

Because an event gateway uses at least one listener thread, it must have start, stop, and restart methods to control the threads. These methods must also maintain the status variable that the Gateway class getStatus method checks, and change its value among STARTING, RUNNING, STOPPING, STOPPED, and FAILED, as appropriate.

One or more listener threads respond to incoming messages (events). The threads must include code to dispatch the messages to ColdFusion event gateway services, as follows:

1. Create a CFEvent instance.

2. Create a Map instance that contains the message and any other event gateway-specific information, and pass it to the CFEvent setData method.

3. Call the CFEvent setOriginator method to specify the source of the message. (This call is required if the ColdFusion application sends a response.)

4. Call the CFEvent setGateWayType method to specify the event gateway type.

5. Set any other CFEvent fields where the default behavior is not appropriate; for example, call the setCFCPath method to replace the default listener CFC. (For information on default CFEvent fields, see CFEvent class.)

6. Call the gatewayService.addEvent method to dispatch the CFEvent instance to ColdFusion.

7. Handle cases where the event is not added to the event gateway service queue (the addEvent method returns False).

If your application sends any messages to multiple listener CFCs, the gateway must create and configure a CFEvent instance and call the gatewayService.addEvent method to send the message to each separate listener CFC. The setCFCListeners method of the gateway must make the CFC paths available to the gateway for configuring the CFEvent instances.

If your ColdFusion server carries a heavy event gateway message load, the ColdFusion event gateway services event queue could reach the maximum value set in the ColdFusion Administrator. When the queue reaches the maximum, the gatewayService.addEvent method returns False and fails. Your code can do any of the following:

• Return a message to the sender to indicate that their message was not received.

• Wait until the queue is available by periodically comparing the values returned by the GatewayService getQueueSize and getMaxQueueSize methods, and retry the addEvent method when the queue size is less than the maximum.

• Log the occurrence using the logger returned by the GatewayService getLogger method. (For more information, see Logging events and using log files.)

The SocketGateway class implements the listener using a java.net.ServerSocket class object and SocketServerThread listener threads. (See the SocketGateway source for the SocketServerThread code.) When the listener thread gets a message from the TCP/IP socket, it calls the following processInput method to dispatch the message to ColdFusion. This method explicitly sets all required and optional CFEvent fields and sends the event to ColdFusion. If the addEvent call fails, it logs the error.

private void processInput(String theInput, String theKey) 
{ 
    // Convert listeners list to a local array 
    // Protect ourselves if the list changes while we are running 
    String[] listeners; 
    int size = cfcListeners.size(); 
    if (size > 0) 
    { 
        // Capture the listeners list 
        synchronized (cfcListeners) 
        { 
            listeners = new String[size]; 
            cfcListeners.toArray(listeners); 
        } 
    } 
    else 
    { 
        // Create a dummy list 
        listeners = new String[1]; 
        listeners[0] = null; 
    } 
    // Broadcast to all the CFC listeners 
    // Send one message at a time with different CFC address on them 
    for (int i = 0; i < listeners.length; i++) 
    { 
        String path = listeners[i]; 
        CFEvent event = new CFEvent(gatewayID); 
        Hashtable mydata = new Hashtable(); 
        mydata.put("MESSAGE", theInput); 
        event.setData(mydata); 
        event.setGatewayType("SocketGateway"); 
        event.setOriginatorID(theKey); 
        event.setCfcMethod(cfcEntryPoint); 
        event.setCfcTimeOut(10); 
        if (path != null) 
            event.setCfcPath(path); 
            boolean sent = gatewayService.addEvent(event); 
        if (!sent) 
            log.error("SocketGateway(" + gatewayID + ") Unable to place message on 
                event queue. Message not sent from " + gatewayID + ", thread " + theKey 
                + ".Message was " + theInput); 
    } 
}

The ColdFusion event gateway services call the outgoingMessage method of the gateway to handle messages generated when the listener method of an event gateway application listener CFC returns a message or any CFML code calls a SendGatewayMessage function. This method must send the message to the appropriate external resource.

The outgoingMessage method parameter is a CFEvent instance, containing the information about the message to send out. The CFEvent getData method returns a Map object that contains event gateway-specific information about the message, including any message text. All CFEvent instances received by the outgoingMessage contain information in the Data and GatewayID fields.

CFEvent instances returned from listener CFC onIncomingMessage methods include the originator ID of the incoming message and other information. However, a gateway that could handle messages from the ColdFusion SendGatewayMessage function cannot rely on this information being available, so it is good practice to require that all outgoing messages include the destination ID in the data Map.

The outgoingMessage method returns a String value. The CFML sendGatewayMessage function returns this value to the ColdFusion application. Indicate the status of the message in the returned string. By convention, ColdFusion event gateway outgoingMessage methods return “OK” if they do not encounter errors and do not have additional information (such as a message ID) to return.

Because event messages are asynchronous, a positive return normally does not indicate that the message was successful delivered, only that the outgoingMessage method successfully handled the message. In some cases, however, it is possible to make the outgoingMessage method at least partially synchronous. The SMS gateway, for example, provides two outgoingMessage modes:

Asynchronous mode

The outgoingMessage method returns when the message is queued internally for delivery to the short message service center (SMSC) of the messaging provider.

Synchronous mode

The method does not return until the message is delivered to the SMSC, or an error occurs.

This way, an SMS application can get a message ID for later use, such as to compare with a message receipt.

The GatewayServices.getLogger method returns an instance of the coldfusion.eventgateway.Logger class that you can use to log messages to a file in the ColdFusion logs directory. (You set this directory on the ColdFusion Administrator Logging Settings page.) The method can take no parameter, or one parameter:

• The default GatewayServices.getLogger method uses the eventgateway.log file.

• Optionally, you can specify a log filename, without the .log extension or directory path.

The following example tells ColdFusion to log messages from the gateway to the mygateway.log file in the ColdFusion logs directory:

coldfusion.eventgateway.Logger log =getGatewayServices().getLogger("mygateway");

The Logger class has the following methods, all of which take a message string. The method you use determines severity level that is set in the log message.

• info

• warn

• error

• fatal

You can also pass these methods an exception instance as a second parameter. When you pass an exception, ColdFusion places the exception information in the exception.log file in the ColdFusion logs directory.

You can use these methods to log any messages that you find appropriate. If you use the default eventgateway.log file, however, remember that all ColdFusion standard gateways us it, and other gateways could use it. As a result, limit the messages that you normally log to this file to infrequent normal occurrences (such as gateway startup and shutdown) or errors for which you want to retain data.

ColdFusion uses the following format for the message text, so have your application follow this pattern:

GatewayType (Gateway ID) Message

The SMS event gateway, for example, includes the following exception catching code, which logs a general exception messages and the exception name in the eventgateway.log file, and also (automatically) logs the exception in the exceptions.log file:

catch(Exception e) 
{ 
    logger.error("SMSGateway (" + gatewayID + ") Exception while processing 
    incoming event: " + e, e); 
}