This section describes how to build an event gateway. To build a Gateway class, you can start with the EmptyGateway.java file as a template. (In the server configuration, this file is located in the cf_root/gateway/src/examples/ directory; in the J2EE configuration, the file is in the cf_root/WEB-INF/cfusion/gateway/src/examples/ directory.) This file defines a nonfunctional event gateway, but has the basic skeleton code for all Gateway class methods.
Wherever possible, the following sections use code based on the sample Socket event gateway to show how to implement event gateway features. (In the server configuration, this file is cf_root/gateway/src/examples/socket/SocketGateway.java; in the J2EE configuration, the file is cf_root/WEB-INF/cfusion/gateway/src/examples/socket/SocketGateway.java.)
This section describes the following topics:
An event gateway can implement any of the following constructors:
MyGateway(String gatewayID, String configurationFile)
MyGateway(String gatewayID)
MyGateway()
When ColdFusion MX starts, it calls the constructor for each event gateway instance that you configure in ColdFusion MX. (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 event gateway's setGatewayID method.
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 do this, it is a good coding practice.
A minimal constructor that takes only a gateway ID might 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 there is an error that otherwise cannot be handled. For example, you should throw this exception if the event gateway requires a configuration file and cannot read the file contents.
If your gateway uses a configuration file, the constructor should load the file, even if the Start method also loads the file. You should do this because the constructor does not run in an independent thread, and ColdFusion can display an error in the ColdFusion MX 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 MX 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);
}