The Gateway Type dropdown list allows you to select the gateway type the new instance will be. These values are drawn, obviously, from the types configured earlier on the Event Gateways Gateway Types page.

The CFC Path field allows you to specify a ColdFusion component that will handle the specific functionality of your gateway instance. There are no hard limitations on the length of the information entered into this form field. The CFC specified here is called a listener CFC in the jargon and will be discussed in greater detail in the next article.

The Configuration File field allows you to indicate the specific configuration file that will be applied to this gateway instance. The default installation of the ColdFusion Server keeps a number of configuration fields in the [ColdFusion install path]\gateway\config directory. The de facto file extension for an event gateway is .cfg but it is really nothing more than a Java configuration file. There is no hard requirement that gateway configuration files reside in this default directory so placing them in a subdirectory specific a ColdFusion application would be a good idea.

The Startup Mode dropdown list has three options; Automatic (the default option), Manual and Disabled. An Automatic gateway instance is started when the ColdFusion Server starts up and Disabled ones cannot be started. Instances with a Manual startup mode must be started from the Administrator or through the new Admin API's cfide.adminapi.eventgateway component. For more details on using the Admin API refer to the product documentation: Configuring and Administering ColdFusion MX, Using the ColdFusion Administrator, Administrator API.

The table of Configured ColdFusion Event Gateway Instances at the bottom of this page is more than merely a listing of the configured instances; it is also a control panel for starting and stopping each of the instances.

Putting It Together
So, armed with a basic understanding of how to configure a gateway, let's put together a simple example (a gateway application in the jargon).

I've created a directory in my Server's wwwroot for this sample; [ColdFusion install path]\wwwroot\ccojas\part1. Herein I've placed two files, CCOJASDirectoryWatcher.cfg (shown in Listing 1) and CCOJASDirectoryWatcher.cfc (shown in Listing 2).

This file is a slightly modified version of the directory-watcher.cfg file copied from [ColdFusion install path]\gateway\config. The first property, directory, defines the directory to monitor, which has been set to the sample's base directory; [ColdFusion install path\wwwroot\ccojas. The third property, interval, sets the number of milliseconds to wait in-between checks (basically how long the monitoring thread will sleep). The interval has been set to 5 seconds so you don't have to wait around a full minute before seeing activity in the logs.

This component implements three methods which handle additions, deletions, and changes to files in the watched directory. These methods are defined by the DirectoryWatcher gateway type already configured in the Administrator as part of the default installation. Finding the documentation on a specific gateway is not yet as easy as looking up a CFML tag or function, but I expect that will change in subsequent product releases (this information can currently be found in the product documentation: Developing ColdFusion MX Applications, Using Event Gateways, Using the example event gateways and gateway applications, Example event gateways).

I will be discussing the specific contents of this file in the next article so I won't muddy up the example with a length discussion at this point. A cursory examination of the code will show that each of these methods merely writes a message to a log.

Once these files are in place you can create a new event gateway instance using the settings shown in Figure 4.

Since the gateway is set for a Manual startup, you'll need to start it by pressing the green play button in the gateway's control panel, Configured ColdFusion Event Gateway Instances, at the bottom of the page. Once the gateway is started, create a new file (I just created a text file using the context menu in the Windows File Explorer) in the watched directory; [ColdFusion install path]\wwwroot\ccojas. Looking in the ColdFusion Server's logs directory you should see a new log file called CCOJASDirectoryWatcher.log which should show a new last entry declaring the creation of the new text file you created with an ADD entry. Back in the watched directory, open the file and type some gibberish and save it. This too will create a new entry in the log file indicating the changed file with a CHANGE entry. And just to tidy things up, after checking the log for the CHANGE entry, go back and delete the file, which will result in a DELETE entry in the log.

[Note: Once you see things are working it is probably a good idea to stop this gateway instance - there is no useful reason to have a piece of demonstration code waking up to read a directory listing every 5 seconds. If you did not fill out the gateway instance information exactly and it is set for an Automatic startup (which, again, is the default option) you will want to change it to Manual. It does no good to stop the gateway if it is just going to startup automatically when you restart the ColdFusion Server.]

The eventgateway Log
The eventgateway.log in the Server's logs directory is a good way to keep tabs on the general goings-on of all your gateways. Informational details like which gateways the Server has started up as well as error specific messages about any problems that occur in a gateway.

While most errors in configuration settings will show up as errors in the ColdFusion Administrator right away, such as setting the CFC Path field in the Event Gateways Gateway Instances page to a CFC that does exist, this is still a good place to look if you are manually moving files and directories around or installing gateways from CAR files. Likewise, as you'll see in a later article in this new series, when the Server's gateway thread pool or message queue is exceeded it will be flagged in the log.

Wrapping It Up
Event gateways are undoubtedly going to be a major growth area for ColdFusion development just as custom tags, user-defined functions and components. Getting a solid grounding in how to administer them and how to write them will be a key set of skills for building advanced applications; opening integration opportunities that were near impossible.

The next installment in the series will look closely at the new CFML functions for passing messages to gateways and the components that handled those requests. [Author's Note: All of the sample code for this article is packaged in a Zip file available at the Web site, ccojas-part1-code.zip.]

• Sidebar