Building an event gateway

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:

• Class constructor
• Providing Gateway class service and information routines
• Starting, stopping, and restarting the event gateway
• Responding to incoming messages
• Responding to a ColdFusion function or listener CFC
• Logging events and using log files

Class constructor

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);
}

ColdFusion 9 | ColdFusion 8 | ColdFusion MX 7 | ColdFusion MX 6.1 | ColdFusion MX | Forums | Developer Center | KnowledgeBase | Bug Reporting

Version 7

Comments

Add Comment

niko1 said on Feb 24, 2005 at 6:47 PM :

where exactly are the classes or is the .jar file to import when we build our own classes? I can not find them and it seems that the documentation leaves out this helpful fact.

jrunrandy said on Feb 26, 2005 at 9:25 AM :

Good catch. I assume you are asking about things like coldfusion.eventgateway.GenericGateway and coldfusion.server.ServiceRuntimeException

These classed are in the cfusion.jar file, whose location varies based on your configuration:
* Server - cf_root/lib
* Multiserver - jrun_root/servers/cfusion/cfusion-ear/cfusion-war/WEB-INF/cfusion/lib
* J2EE - cf_webapp_root/WEB-INF/cfusion/lib

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/coldfusion/7/htmldocs/00001692.htm

Add Comment