One of the most powerful new features available in ColdFusion MX 7 Enterprise that many ColdFusion developers might not yet be using is event gateways. Event gateways open up entirely new possibilities for ColdFusion and allow our ColdFusion applications to communicate with more or less any other Internet-enabled system even if the system doesn't communicate via the "traditional" HTTP protocol.
CFMX 7 Enterprise ships with a few gateways to get you started, such as an SMS gateway for communicating with mobile devices, a directory watcher gateway, a socket gateway, a Java Message Service (JMS) gateway, and Jabber/XMMP as well as Lotus Sametime IM gateways, so you have a lot of possibilities right out of the box.
If you don't need the specific functionality offered by these gateways you might not have investigated them thoroughly and because the event gateways themselves are written in Java, creating new gateways may not be a high-priority item for many ColdFusion developers. But there is another gateway that ships with CFMX 7 Enterprise that ColdFusion developers can take advantage of right away, which offers numerous benefits in your ColdFusion applications. In this article I'd like to introduce you to the Asynchronous CFML Gateway, describe some of the great potential uses of the gateway, and show how I added an asynchronous CFML gateway to vastly improve the performance and functionality in an existing ColdFusion application.
The Asynchronous CFML Gateway
The purpose of the asynchronous CFML gateway is to allow developers to offload long-running processes to the gateway. The gateway immediately passes control back to the application and does it's processing behind the scenes. This means that your users will no longer have to wait for lengthy batch processes to complete before doing other things within the application. This is great for things like logging, which if you log a lot of data can really bog down your application since the user has to wait for the logging process to complete on each request.
Even if you have a process that runs behind the scenes that is initiated by the ColdFusion scheduler as opposed to by a user action, leveraging the asynchronous gateway can allow for the process to complete more quickly. For example, if you have a loop of some sort and the work done upon each iteration is fairly lengthy, by sending a message to the asynchronous gateway on each loop iteration the overall process doesn't need to wait for each iteration to complete before proceeding.
What allows this magic to be possible is the use of ColdFusion Components (CFCs) that operate within the event gateway environment as opposed to being tied to a specific request. By creating a CFC that contains a few specific methods (actually we'll concern ourselves with one method in particular - more on this in a moment) and registering the CFC as an event gateway instance in the ColdFusion administrator, the CFC can now operate independently of the traditional request/response model of web applications.
Bear in mind, however, that not all processes are suitable for use with the asynchronous event gateway. One big caveat here is that because the asynchronous process is detached from the request/response cycle, it isn't really feasible to provide feedback to the user in a traditional way such as sending the user to a confirmation page when a process completes. Also, if your application contains processes that occur sequentially and later processes rely on the results of preceding processes, then even if one of these processes is time-consuming this isn't a case in which use of the asynchronous gateway is possible. When you use the asynchronous gateway you essentially throw the process over the fence and give up control over when it completes and the ability to rely on the results of the asynchronous process.
The asynchronous CFC can however, do things such as log information to a file or database, send information via e-mail, or even send an instant message using the IM gateway, so by no means does the asynchronous CFC's processing disappear into a black hole.
In addition to these methods the event gateways can of course also use the cflog tag, which outputs information to a log that can be viewed from the ColdFusion administrator or directly in the log file itself. In the ColdFusion administrator's Debugging & Logging section you will also see an Event Gateway log that can provide information about what occurs inside your gateways. Finally, for some additional thoughts and methods by which to get feedback from asynchronous CFCs, please see Sean Corfield's blog entries about his Concurrency library under "Resources" at the end of this article.
If you haven't considered the power of asynchronous processing before, I'd be willing to bet the wheels are spinning and your head is filling with ideas of how you can leverage this power in your applications. Let's take a look at one real-world example that created dramatic improvements and was surprisingly easy to build.
Web-Based "E-Mail Blaster"
A few years ago I wrote a ColdFusion application for my company's marketing department that is used for generating and sending e-mail marketing campaigns. This application became affectionately known as the "E-Mail Blaster." Prior to the existence of the E-Mail Blaster our marketing team was literally cutting and pasting e-mail addresses from an Excel spreadsheet into the Lotus Notes e-mail client. Clearly not the most efficient way to do things given the fact that some of our larger batches of e-mail can top 50,000 recipients, and Notes has an upper limit of a few hundred recipients for each e-mail. (Before you declare me the Spam King of Texas, bear in mind that that our lists are entirely opt-in!)
When I saw how the marketing department was dealing with these e-mail campaigns I immediately knew that this was a perfect job for ColdFusion. ColdFusion Enterprise handles large volumes of e-mail extremely well, and it was quite simple to build a web-based interface for creating e-mail campaigns that saves countless hours of time versus the old cut-and-paste method. We use another tool to maintain contact lists, so the marketing team extracts the recipient list into an Excel spreadsheet. They then use the ColdFusion application to upload the Excel spreadsheet containing the recipients' e-mail addresses along with an HTML file containing the contents of the e-mail, and the E-mail Blaster handles the rest.
Hurry Up and Wait
The application was an immediate hit with the marketing department, but there was one drawback. Even as quickly as ColdFusion handles e-mail it still takes a bit of time to process 50,000 e-mails, and in the traditional request/response model of web applications this means the user of the application has to wait ... and wait ... and wait for the process to complete. This doesn't necessarily mean the user can't go do something else while it's processing, but people tend to get used to submitting a form and seeing a response relatively quickly so by force of habit the users of the E-mail Blaster tend to wait for a response from the application.
In a long-running process such as this the response can be substantially delayed, and this can cause problems ranging from simple annoyance to users resubmitting e-mail batches because they assume the process stopped or an error occurred. In the original version of the application there were problems with Internet Explorer refreshing the processing page automatically because I wasn't flushing anything to the screen during the send process. Once I discovered this issue I updated the application to flush each e-mail address to the screen as the e-mail was sent, which gave the user primitive feedback and also solved the auto-refresh issue with Internet Explorer.
This was still a less-than-ideal situation. I hope this doesn't come as a shock to any of you, but in case you were unaware, users can be impatient at times. No matter how many different ways I explained the situation, because most users are accustomed to clicking on a link and having the next page finish processing more or less instantly, some users just couldn't understand why generating 50,000 e-mails was taking so long.
Even with the addition of flushing each address to the screen, there were still occasional timeout issues that would cause the browser to throw an error of one kind or another. At a minimum seeing an error at the end of the batch would create a sense of uncertainty in the user's mind as to whether or not the e-mails were sent successfully. I thought about going to some relatively insane lengths to change this situation, but in the end I just stuck with the solution and dealt with continually educating my users on the process.
Asynchronous Processing to the Rescue
My wish for a better way of handling things in the E-Mail Blaster was answered with CFMX 7 Enterprise and the asynchronous CFML gateway. No longer do my users have to wait for each e-mail to be sent. Now I can just generate the recipient list, pass everything off to my e-mailer CFC via the asynchronous gateway, and immediately return a message back to the user informing them that their e-mail batch is in process and they will be notified via e-mail (and Lotus Sametime IM as well, but that's a story for another article!) when the process is complete. I also log each e-mail address to a text file as the e-mails are generated and attach this text log to the confirmation e-mail, so no longer do I have to respond to questions concerning whether or not a particular e-mail was sent to a particular address.
This is an amazingly powerful solution, and as usual ColdFusion makes doing powerful things such as this extremely simple. Let's walk through the steps involved with creating a CFC and registering it in the ColdFusion administrator so it can be used via the asynchronous gateway. (Just a reminder: event gateways are only available in ColdFusion Enterprise and Developer editions. Gateways are not available in ColdFusion Standard.)
Step One: Create AsynchE-mailer.cfc
This step was surprisingly easy. Since I originally wrote the E-mail Blaster when CFMX was first released I wasn't using CFCs very heavily at that point, so my e-mail sending code was in a simple CFML page. The actual code itself did its job well, however, so basically it was just a matter of some minor tweaks and pasting the CFML code into a new CFC.
In order to be able to use a CFC via the asynchronous gateway there is one key method that must exist in the CFC: onIncomingMessage. This function is what is called when SendGatewayMessage() is called from your ColdFusion application (more on this in a moment). The onIncomingMessage method in the CFC takes a struct as an argument, and this struct contains the information you want to use within the asynchronous CFC. In the case of the E-Mail Blaster, the struct contains the recipient list, the HTML contents of the e-mail, and a few other bits of information such as the administrator and sender's e-mail address and a path to which a log file is written. See Listing 1 for the complete AsynchE-mailer.cfc code.
Step Two: Register AsynchE-mailer.cfc in the Event Gateway Administrator
Once the CFC is created, registering it for use via the asynchronous gateway is a snap. First, log into the ColdFusion administrator and click on the Event Gateways link on the left. The Gateway Types area is where you define the various gateways to which the ColdFusion server has access, and you'll see that one of these is the asynchronous CFML gateway. You don't need to do any configuration on this page in the administrator, just be aware that this is where the asynchronous CFML gateway is registered with the ColdFusion server.
Click on Gateway Instances to be taken to the form you will use to configure the AsychMailer.cfc to run as a gateway. You'll see the following fields:
- Gateway ID: This is the handle or name by which you will refer to the gateway instance in your ColdFusion code, and can more or less be anything you want. I named this gateway "Asynch E-mailer."
- Gateway Type: This lists the gateway types that are registered on the server. In this case you'll want to choose "CFML - Asynchronous Events via CFML."
- CFC Path: This is the physical path on the server to the CFC that you want to use as the gateway.
- Configuration File: This tells ColdFusion where the configuration file for the gateway is, but we don't need one for this CFC so we leave that field blank.
- Startup Mode: This tells the ColdFusion server whether you want this gateway instance to start up automatically (i.e. when ColdFusion starts), manually, or that the gateway is disabled altogether. If it's a gateway you're going to use in a production environment, obviously you'll want it to start automatically.
Step Three: Call the Asynch E-mailer Gateway from the E-Mail Blaster Application
Calling the asynchronous gateway is as simple as calling the SendGatewayMessage() function, which takes two arguments: the handle or name we gave our CFC in the ColdFusion administrator, and a struct containing the data that we want to pass into the gateway.
First let's build a struct to hold our data. Since we're using the gateway to send e-mails, the struct we pass to the gateway contains the recipient list, the HTML contents, the sender information such as name and e-mail, and a few other items used for housekeeping and error handling. This is just a plain old ColdFusion struct, so simply populate the struct in your CFML or CFC and pass it to the gateway. Since I've converted the original application into a more object-oriented model, I'm using an E-mailBlast Session bean to store the e-mail blast data prior to beginning the send process, so the code populating this struct looks like this:
e-mailBlastData.recipients = Session.e-mailBlast.getRecipientList();
e-mailBlastData.fromName = Session.e-mailBlast.getFromName();
e-mailBlastData.fromE-mail = Session.e-mailBlast.getFromE-mail();
e-mailBlastData.subject = Session.e-mailBlast.getSubject();
e-mailBlastData.content = Session.e-mailBlast.getContent();
Once the struct is populated, we simply make a call to the asynchronous gateway by using the SendGatewayMessage() function:
status = SendGatewayMessage("Asynch E-mailer", e-mailBlastData);
Taking another look at the AsynchE-mailer.cfc code, you will see that the gateway's onIncomingMessage function takes in a struct argument called CFEvent. You can call this anything, but CFEvent is the naming convention used in the ColdFusion documentation so I retained it here. Please note that once the struct is in the gateway, rather than calling the struct's members directly as you would in your application (e.g. e-mailBlastData.content) the struct members are called using CFEvent.Data.myStructMember notation. Using the previous example, the content data would come into the gateway as CFEvent.Data.content. Just be aware of the addition of "Data" to the struct.
Although the onIncomingMessage function within the CFC doesn't return anything, the SendGatewayMessage() function returns a boolean. The gateway itself is limited in providing feedback because of its asynchronous nature, so the status boolean that is returned is really an indication of whether or not the call to the gateway was successful; it does not indicate whether or not the gateway's process itself was successful. The success or failure of the process inside the gateway itself must be retrieved using one of the methods previously outlined.
Now here's where the asynchronous magic happens. Once you call SendGatewayMessage(), processing within your application doesn't stop and wait for a response. The application immediately proceeds past that point in the code, and no matter how lengthy the gateway process is, your application is free to proceed. For lengthy processes that would previously hang up your application this is just what the doctor ordered!
Conclusion
Event gateways open ColdFusion applications up to a whole new world of possibilities. The asynchronous CFML gateway is simple, elegant, tremendously powerful, and surprisingly simple to use. If you have long-running processes in your ColdFusion applications or want to add functionality to your application that you were afraid to attempt before due to potential issues with the traditional request/response model, fear no longer. Write a CFC to handle the processing, register it in the ColdFusion administrator, and take advantage of the power of asynchronous processing.
Resources
Corfield, Sean (2005, April 16). "Asynchronous CFML - Concurrency Library." http://corfield.org/blog/index.cfm?do=blog.entry&entry=4D121277-A559-411D-A0960C66A7E3BFCD
Corfield, Sean (2005, April 14). "Debugging and Caching in Event Gateways." http://corfield.org/blog/index.cfm?do=blog.entry&entry=3F160E0C-B987-C466-41E27E56503E3044
Forta, Ben (2005, March 16). "Understanding Asynchronous Processing." http://www.forta.com/blog/index.cfm?mode=e&entry=1541
Jordahl, Tom (2005, March 16). "Taking Advantage of ColdFusion MX 7 Event Gateways." Recorded Macrochat. http://www.macromedia.com/devnet/mx/coldfusion/articles/gateway_macrochat.html