Book Excerpt

Digg This!

Page 2 of 4   « previous page   next page »

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. Last, we'll log the event. The code to do all this is in Listing 1.

Most of the code here is pretty straightforward. 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 2 shows an example of what the CFEvent message might look like in our example. Table 2 describes each node in the structure.

In Listing 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 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 3.

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 directorywatcher.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 thumbnails - or 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 work, but 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.

Creating an Initiator Application Using the ColdFusion Gateway
So far, you've seen how to create a responder application that listens for events from an event gateway instance and takes some sort of action. Now we'll study an application called an initiator application that sends a message to an event gateway. This example uses the ColdFusion Gateway to asynchronously log messages to a file via a simple CFC.

Logging may seem trivial, especially since you can just use CFLOG, but CFML pages that use CFLOG to write large amounts of data to a log file can seriously degrade an application's performance, as well as tie up threads that could be better used serving your application's Web users. In addition, you might have an application like a B2B that needs to log large amounts of information, such as every type of transaction between partners for legal reasons. Thus you might want to decouple logging into its own subsystem, not only for performance but for good design. Using the ColdFusion Gateway allows you to create applications that call CFCs asynchronously, which is perfect for this example. Okay, let's look at some code (see Listing 2).

As you can see, this is a very simple CFC that accepts a CFEvent message and logs information from it. After you save this file to a directory, create an event gateway instance in the Event Gateways page of the Administrator, as described earlier. For this example, give the instance a Gateway ID of DataLogger and point it to this CFC. Then leave the Configuration File field blank, create the instance, and start it running.

Now we can take our previous code and, instead of using CFLOG directly for logging information, send a message to the event gateway that will call the DataLogger.cfc to log the event. We do this using SendGatewayMessage with "GatewayID" and a struct with an event message. Let's look at Listing 3.

We have just added some simple code in a CFSCRIPT block and then used the SendGatewayMessage() function, which takes two required attributes. The first is the Gateway ID and the second is data, a structure that conforms to the specific gateway type. In this case, the gateway expects the event to contain a message node as well as an optional file node.

As you can see, creating an initiator application is simple enough, and in this case we have a listener that both responds to an event from a gateway and fires an event to a gateway.

Debugging CFML Applications for Event Gateways
When you need to develop ColdFusion applications that use event gateways, you need to be particularly careful - CFCs that are responding to events work differently than when they are responding to a normal page request. If an event gateway triggers a CFC and that CFC throws an error, the event gateway continues to function without pause and does not display any sort of debugging information back to you. For this reason, you'll need to follow some different development paradigms - especially with regard to debugging, so that you can make sure your CFCs and event gateways are functioning as expected. In this section we'll examine some techniques you can and should use to help you debug and write better code.

Page 2 of 4   « previous page   next page »