Configuring ColdFusion and FusionDebug
Your next step is to set up ColdFusion to allow for debugging requests. In reality, you're setting up the Java server, which underlies your ColdFusion installation, and not making any direct changes to ColdFusion settings. You need to change the arguments that are used when launching the JVM. In most ColdFusion installations, you'll be using JRun, and the JVM settings are located in a jvm.config file. For Windows installations, this file is located in the CF install directory under "runtime/bin". For Unix, it's just in "bin" under your CF install directory. If you are using CF in any sort of multiserver configuration, your location may vary slightly. Before editing the file, you may want to save a copy of the current file, in case anything goes wrong with the one-line edit I'm about to describe.

Find the "java.args" line of the config file and remove this argument:

-XX:+UseParallelGC

Then add these options:

-Djava.compiler=NONE

-Xnoagent

-Xdebug

-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000

Make sure that all the options are on the same line. For ease, you can copy these lines out of the FusionDebug documentation. Note the port 8000 that's used. If you know that port to be used is already in your system, choose a number that's not in use. I'll explain its use shortly. Save the file and restart your ColdFusion services. If it fails to start, revert to the saved copy from above and study your changes to make sure you followed the instructions carefully.

The final step in getting yourself set up is to create an instance of FusionDebug that points to the server you set up for debugging:

1. Load up Eclipse, and select a project you want to debug with. (If you don't have any Eclipse projects, see the FusionDebug User Guide for more information on creating one for the first time.) Select "Debug" from the Run menu.
2. Select FusionDebug from the menu and Click New to create a new FusionDebug instance. This will bring up a dialog similar to Figure 1.
3. Enter a name for the FusionDebug instance. This can be anything you want it to be. Specify the Web server folder. I used the same folder as the project root for my Eclipse Project.
4. Specify the host and port. Note that the hostname can be localhost or indeed any server you have access to, which has been configured as per the steps above. Yes, FusionDebug can debug remote servers. The port is not your Web server port, but the port you specified in the Java arguments. It is 8000 by default. If you followed my instructions above, that didn't change.
5. Select your other options. In my case, my CF Server is on Windows, I want CF to compile pages in debug friendly mode, and my Eclipse folder mirrors the Web server. I have not yet experimented with the "Detailed Java Information" option, soI left that unchecked. These are explained in the User Guide.

Now you are good to go, ready to debug.

You're First Debugging Session
If you've read my two articles on creating an RSS Aggregator, you probably noticed that I found a bug between part one and part two. The code I wrote in part 1 (http://coldfusion.sys-con.com/read/235976.htm ) supported only RSS 2. It turns out that the Macromedia XML News Aggregator (http://weblogs.macromedia.com/mxna/) was only providing an RSS 1.0 feed. The XML was different in each feed. In part 2 (http://coldfusion.sys-con.com/read/264745.htm ), I described the error and explained the fix. I thought I'd step you through the process I used to diagnose and fix the problem (without FusionDebug) and then step you through the process using FusionDebug. In my test database for the MyFriend RSS aggregator, I have two RSS URLs. One points to my blog and the other to MXNA. When trying to process the MXNA URL (by manually loading the scheduled task), I was seeing an error, as shown in Figure 2. I wasn't sure why I was receiving the error, since all RSS feeds should contain an item as part of the channel (right?). The first thing I did was add a cfdump tag to see why "xmlroot.channel.item" did not exist. I reloaded and got nothing [insert two head scratches and one look of utter confusion here]. Why wasn't I seeing any debug output? It turns out the CFFUNCTION had its OUTPUT attribute set to false. No output means no output and the cfdumps weren't being sent back to the browser. I changed that attribute to true and reloaded. Okay, now with the cfdump I could drill down into the XML and see the problem. Items (AKA Blog Posts) are stored differently in RSS 1 vs RSS 2. And the root elements are different.

Where would the debugger have helped? To debug this code inside a component, I'm changing code. It's one thing to add a variable output or cfdumps so you can view variables. Those are easy enough to comment out later. It's quite another to have to change code, such as the output parameter from false to true. I don't want to have different code for "production" versus "development." That defeats the purpose and allows too much margin for error. How many of these output attributes have I forgotten to change back? I have no idea. The problem gets worse when you are dealing with nested components, because you have trickle back up to the top of the tree and set all outputs to true. Still another situation occurs with code within CFSILENT, which I would have to find and remove to see any debugging output. These are situations where an interactive debugger offers benefit. To get to the root of the problem I don't have to change any code.

This is how I'll debug this in FusionDebug:

1. First, I'm going to open up the project in Eclipse, and switch to the debug perspective. You can switch perspectives using "Window --> Open Perspective and selecting "Debug." You should see something similar to Figure 3. (Again, all this is described very well in the User Guide, for those new to Eclipse.)
2. Next, start a debugging session. You can re-open the debug window (see Figure 2), select your Debug instance, and select "Debug," or you can start the debug session by clicking the "debug" button from the toolbar. You should see the session started up in the debug window (top left).
3. Open up a page in the project that you want to debug, and set a breakpoint. (Note that if you open a file from the file system rather than from a project, the debugger won't enable you to step through code.) With MyFriend, I am opening up the scheduled task file (schedultedtask/scheduledtask.cfm) and putting a breakpoint on the first CF line of the page. You can add a breakpoint by selecting the line and choosing "Window --> Toggle Line Breakpoint" or using Control + Shift + B, or right-click the line and choose "Toggle Breakpoint." You'll now see the breakpoint was set because of the blue dot in the grey bar to the left of the line number. (You can see the dot on line 15 of Figure 3).
4. Open your favorite browser and launch the page you want to debug. FusionDebug will intercept the page at the first breakpoint. Again, note that you're not opening the page "in" the debugger but in whatever browser you want. There is a blue arrow in the same grey bar to show you which template you are currently running. (This is called the "Current Instruction Pointer.")
5. Click Step Over and you can step through the initialization code to watch the component being created. Continue to click Step Over until you reach the init method of the RSSAggregator component. Around line 75 you should see code like this:

   <cfset MyXMLVar = xmlparse(cfhttp.filecontent)>

6. Click past the line that parses the XML content. Now take a look at the variables tab shown in Figure 4. It should be in the upper-right corner of the screen. You can view all the variables available to the component. The one we care about most is the local function variable that holds the XML. The first time through the loop, you'll see that the XML is in proper RSS 2 format. The second time through you'll notice it uses "RDF" instead of XML. Drilling down, you'll realize that the items are different in the RDF format than they are in the RSS format. And that is the root of the problem.

The bug was easily solved by adding an if statement (explained in the previous article) to decide which RSS format to use, and how to access the item array. Both debugging methods can bring you to the same end result, but I personally find the use of FusionDebug to be much more elegant.
I mentioned near the start to favor Step Over versus Step Into, even on tags or function calls that don't open a file. The reason is that being a Java debugger, Eclipse will try to step through the underlying Java code. FusionDebug is configured to hide that by default, but the execution of the tag/function will take longer than if you'd used "Step Over."

What Next
The folks who created FusionDebug created some Captivate videos to help demonstrate what FusionDebug can do and some uses of it. It is one thing to read about how to do things, it is another to see it done, so I suggest checking them out at www.fusion-reactor.com/fusiondebug/gettingStarted.html. Charlie Arehart wrote a tips and tricks article for this edition of ColdFusion Developer's Journal. I've had a chance to preview it and it contains a lot of information beyond the scope of this article.

The product is available as a free 20-day trial. Pricing starts at US$299, with an 10% discount currently available with the code CFCOMMUNITY. Volume discounts are also available. The company offers free support, at support@fusion-reactor.com.

The RSSAggregator code is downloadable from my blog at www.jeffryhouser.com. I appreciate all the feedback I've received from it. Thanks for reading, and let me know what you think. I'll see you next month.