Creating a Simple Gateway Application

In Chapter 29, "Extending ColdFusion with Java," we created several examples for a photo album application. One of the examples we created looped over the contents of a directory and made thumbnails for all the images found in that directory. That's pretty cool, but it requires a user to interact with the application through a Web browser. What if your boss now asks you to allow users to FTP-upload files of photos, and wants the application to detect that a file has been uploaded and create an associated directory of thumbnails! Normally you couldn't do this with ColdFusion because you're not interacting with the server directly through HTTPbut with ColdFusion MX 7 and the DirectoryWatcher event gateway, it's a snap.

For this example, the DirectoryWatcher event gateway (supplied with CFMX7) will create a simple responder application. The DirectoryWatcher gateway sends events to a listener CFC when a file is created, deleted, or modified in a directory you tell the gateway to watch. It runs checks the directory at an interval specified in a configuration file that you edit, and when the interval has passed, checks for changes since last time. If it finds any changes, DirectoryWatcher sends a message to a listener CFC, which can perform the unzipping and creation of thumbnails.

First you need to configure the gateway configuration file, found in:

 coldfusion_root\gateway\config\directory-watcher.cfg 

For this example we'll assume that your ColdFusion root is on drive C, so a literal example of the file path would look like this:

 C:\CFusionMX7\gateway\config\directory-watcher.cfg 

Open this file and edit the very first attribute, directory, and have it point to where you will FTP your zipped files. For this example, the directory is called gallery and the path is as follows:

 directory=C:/Inetpub/wwwroot/JavaInteg/imageio/resize/gallery/ 

Table 31.1 lists a number of other configuration file attributes you can set. After you've edited the directory path, save the file.

Table 31.1. Gateway Configuration File Attributes

VALUE	REQUIRED OR OPTIONAL	DESCRIPTION
directory	Required	Path to the directory to watch.
recurse	Optional	Whether to check subdirectories. The default value is No.
extensions	Optional	Comma-delimited list of extensions to watch. The event gateway logs only changed files that have these extensions. An asterisk (*) indicates all files; this is the default.
interval	Optional	Number of milliseconds between the event gateway's checks on the directory. The default value is 60 seconds.
addFunction	Optional	Name of the function to call when a file is added. The default value is onAdd.
changeFunction	Optional	Name of the function to call when a file is changed. The default value is onChange.
deleteFunction	Optional	Name of the function to call when a file is deleted. The default value is onDelete.

NOTE

For the directory gateway configuration file, you want to use the forward slash (/) rather than the normal backslash (\).

NOTE

Not all event gateways will have a configuration file, and each configuration file will be unique to that specific gateway.

Next, we'll create a CFC that listens for events from the gateway. For this example, we'll only use the onAdd method supplied by the DirectoryWatcher gateway. What we want our CFC to do is listen for an event from the directory watcher, saying that files have been added to the gallery directory. Then the CFC will call the imagemanipulator.cfc (from Chapter 29) to create the thumbnails. For this example we are assuming that the DirectoryWatcher.cfc is being placed in the same directory as the imagemanipulator.cfc which is webroot\JavaInteg\ and the directory gallery is beneath that. Lastly, we'll log the event. The code to do all this is in Listing 31.1.

Listing 31.1. DirectoryWatcher.cfcSimple CFC that creates thumbnails of new images

[View full width]

 <cfcomponent>       <cffunction name="onAdd" output="no">       <cfargument name="CFEvent" type="struct">       <!--- get event data --->       <cfset data=CFEvent.data>       <!--- watcher will ignore outgoing messages --->       <!--- Location of images --->       <cfset GalleryFolder = ExpandPath("gallery")>       <!--- Get list of images --->       <cftry>       <cfdirectory  action="list" name="GetImages"  directory="#GalleryFolder#"       filter="*.jpg">             <!--- Loop over images --->             <cfloop query="GetImages">             <!--- Proposed location of thumbnail --->             <cfset ThumbPath = ExpandPath("gallery/thumbs/#Name#")>             <!--- If the thumbnail does not exist --->             <cfif not FileExists(ThumbPath)>             <!--- Invoke our image-resizing function --->             <cfinvoke component="JavaInteg.imageio.resize.ImageManipulator"             method="createResizedImage"      sourcePath="#GalleryFolder#/#Name#"             destPath="#ThumbPath#"  newWidth="100">             <!--- log a message --->             <cflog file="watch" text="a file was #data.type# and the name was #data .filename#">             </cfif>             </cfloop>             <cfcatch type="Any">             <cflog file="watch" text="A exception, #CFCATCH.TYPE#, was thrown in             DirectoryWatcher.CFC, the error message is #cfcatch.message#">             </cfcatch>       </cftry>       </cffunction> </cfcomponent> 

Most of the code here is pretty straightforward. It has been repurposed from Chapter 29, and you'll see some things that are specific to working with event gateways. The first is that the listener CFC expects a struct called CFEvent, which is a Java object that is mapped to a ColdFusion struct. The CFEvent object contains a variety of information, including a GatewayID, OriginatorId, GatewayType, CFCPath, CFCMethod, CFCTimeout, and Data. Figure 31.2 shows an example of what the CFEvent message might look like in our example. Table 31.2 describes each node in the structure.

Table 31.2. CFEvent Information

FIELD	DESCRIPTION
GatewayID	The event gateway that sent the event or will handle the outgoing message. The value is the ID of an event gateway instance configured on the ColdFusion MX Administrator Gateways page. If the application calls the SendGatewayMessage function to respond to the event gateway, it uses this ID as the function's first parameter.
OriginatorID	The originator of the message. The value depends on the protocol or event gateway type. Some event gateways might require this value in response messages to identify the destination of the response. Identifies the sender of the message.
Data	A structure containing the event data, including the message. Contents depend on the event gateway type. This field corresponds to the SendGatewayMessage function's second parameter.
GatewayType	The type of event gateway, such as SMS. This field can be used by an application that can process messages from multiple event gateway types. This value is the gateway type name specified by the event gateway class. It is not necessarily the same as the gateway type name in the ColdFusion MX Administrator.
CFCPath	The location of the listener CFC. The listener CFC does not need to use this field.
CFCMethod	The listener method that ColdFusion invokes to process the event. The listener CFC does not need to use this field.
CFCTimeout	The timeout, in seconds, for the listener CFC to process the event request. The listener CFC does not need to use this field.

In Listing 31.1, the CFEvent message is used only to log the DirectoryWatcher method that was used, data.type, as well as the file and file path, data.filename. In a more-complex application, you may want your CFC to take actions based on specific information from the CFEvent message.

Now to get our code to actually work, we need to do two other things. The first is to go into the ColdFusion Administrator and create a mapping for the DirectoryWatcher CFC; otherwise, the event gateway will not know where to look. The second thing we need to do is create an instance of the event gateway.

Creating an Event Gateway Instance

Before you can use the example in Listing 31.1, you must create an instance of the event gateway.

First go to the ColdFusion Administrator and select Event Gateways > Gateway Instances. You'll see something like Figure 31.3.

Figure 31.3. The Event Gateways > Gateway Instances configuration screen in the ColdFusion Administrator.

You should now see a form with a number of fields including Gateway ID, Gateway Type, CFC Path etc. To create the gateway follow these steps:

• The first field is the Gateway ID, which can be anything; for our example, let's just use PhotoAlbum.
  
  
• The next field is Gateway Type, which is a drop-down list of all the registered gateways. For this example, we select DirectoryWatcher, which watches a directory for file changes.
  
  
• The next field is CFC Path, which is the CFC path to our listener DirectoryWatcher.cfc. After that you need to add the path to the directory-watcher.cfg.
  
  
• Finally, select the Startup Mode drop-down list to choose whether you want the event instance to be started automatically, manually, or disabled on startup of ColdFusion. Choose Automatic and then click Add Gateway Instance.
  
  

You should now see your gateway instance in the Configured ColdFusion Event Gateway Instances area of the page. Be sure to click the green button to start your event gateway instance. Now your event gateway instance is running and ready to respond to events.

You can make as many instances as you want of a specific gateway, so you could create several DirectoryWatcher instances in order to watch many directories (although it would probably be better to just change the DirectoryWatcher class to support multiple directories). For each event gateway for which you want to create applications, you must have at least one instance actually running if you want to use it.

Now that you have the DirectoryWatcher instance running, you can test the example by copying some images into the gallery folder. Then navigate to your ColdFusion logs directory; you should see a new log created, watcher.log, which is our listener CFC's log. If you have set your directory-watcher.cfg to 60 seconds, you may have to wait, but eventually you'll see the watcher.log update. Look there, and you'll see that it has recorded the action, add, and the file and file path of the images you added to the directory. Examine the thumbnails directory under gallery to see the thumbnails that have been created. At this point it is easy to add code to support things like unzipping zip files of images, moving them to their own new directory based on the zip file names, and then creating the thumbnailsor any other cool functionality you like.

NOTE

If you change or delete a file in the watched directory you'll see an error in the gateway.log file and the cfexception log file. This is because we did not define these methods in our CFC. You can easily do this and just add these methods and have them do nothing, or log the change to a file, etc.

At this point you have created a simple responder application and have set up an event gateway instance. You've learned something about how ColdFusion event gateways workbut there is a lot more to event gateways. Now we'll explore them further, discussing initiator applications, some of the particular differences between coding CFML for gateways and other applications, and how to debug your CFML gateway applications. Finally, we'll look at a simple example of creating your own custom gateway using ColdFusion MX 7's API for gateways using Java.