Using the ColdFusion 8 step-through debugger for Eclipse

Additional Requirements

Eclipse 3.2+

• Learn More

ColdFusion 8 Extensions for Eclipse

• Learn More

If you are a veteran ColdFusion programmer you may remember a little-known feature of ColdFusion 4.5 and 5. Before ColdFusion MX was redesigned to take advantage of the J2EE platform, ColdFusion Studio (the official ColdFusion IDE from Allaire Corporation) included a step-through debugger. In the early days of ColdFusion development, the step-through debugger was essential in identifying how your code was being executed.

The need for the code debugger was greatly diminished in ColdFusion 5 with the addition of the cfdump tag. The cfdump tag offered developers an simple way to debug variables at any stage of execution by displaying variables inline as HTML. Today, developers are defining the next generation of rich Internet applications with ColdFusion, Flex, and Ajax. Most of these service-based applications may never generate HTML at all; thus, you need something more than the cfdump tag for complex debugging.

Adobe ColdFusion 8 reintroduces step-through debugging with a free extension for Eclipse. Originally developed by IBM, the open-source Eclipse project offers developers the freedom to customize their development environment. Adobe Flex Builder 2 is also built on Eclipse, which means you can integrate the ColdFusion 8 step-through debugger directly into Flex Builder or into a stand-alone installation of Eclipse.

Step-through debugging allows you to place a breakpoint on any line of CFML code. Upon execution, ColdFusion will pause the request when it reaches the breakpoint and report the current values of the existing variables along with other diagnostic information. You can step through multiple breakpoints to analyze the request at different lines of execution.
Because step-through debugging is integrated directly into the ColdFusion 8 server, you may have multiple debug sessions running concurrently, a feature not supported by other third-party debugging tools for ColdFusion. Another feature of the ColdFusion 8 step-through debugger is the ability to trigger debug sessions from outside of the IDE. This means you can set a breakpoint in a CFC that is being called from a rich Internet application such as Adobe Flex, Adobe Flash, and Ajax applications. The ColdFusion debug session will be triggered when Adobe Flash Player calls the CFC and reaches the breakpoint. You can also debug CFCs called as web services regardless of where the request originated from.

In this article you will learn how to set up and use the new ColdFusion 8 step-through debugger for Eclipse, as well as learn how to set breakpoints and step though your code.

Configuring ColdFusion to use the step-through debugger requires that you allow line debugging through the ColdFusion 8 Administrator; it may also be a good idea to enable a longer timeout limit for requests. To do so, use the following steps.

1. Log in to your ColdFusion 8 Administrator and select Debugging & Logging > Debugger Settings.
2. Select the Allow Line Debugging option. Click Submit Changes (see Figure 1).

To install the ColdFusion Eclipse Extensions (download these from the Requirements section. Once you have downloaded the extensions, use the following steps to install them.

1. Open Eclipse.
2. Select Help > Software Updates > Find and Install.
3. Select the Search for New Features to Install option.
4. Click New Archived Site.
5. Browse to the file CF8-Extensions-for-Eclipse.zip. Click Open.

   Note: If you installed ColdFusion 8 with the default setup, there is a folder under c:\coldfusion8\extras that contains this file.

6. Select the CF8-Extensions-for-Eclipse.zip and click Next.
7. Accept the License Agreement and click Next.
8. Click Finish and select the option to install all.
9. After the installation is completes, restart Eclipse or Adobe Flex Builder, whichever you happen to be using.

Configuring ColdFusion to use the step-through debugger requires that you allow line debugging through the ColdFusion 8 Administrator; it may also be a good idea to enable a longer timeout limit for requests. To do so, use the following steps.

1. Log in to your ColdFusion 8 Administrator and select Debugging & Logging > Debugger Settings.
2. Select the Allow Line Debugging option. Click Submit Changes (see Figure 1).

3. It may be a good idea to enable a longer timeout limit for requests. The reason for allowing the longer timeout is that when the step-though debugger stops at a breakpoint, the request is held open with the ColdFusion server. You may want to specify a time period longer then 60 seconds while you are evaluating the debug output before the request times out. To enable timeout limits for requests, use the following steps:
1. Select Server Settings > Settings.
2. Select the Timeout Requests option and set it to 300 seconds; then click Submit (see Figure 2).

1. 3. Restart ColdFusion.

Note: Running a ColdFusion server in Debug mode in a production environment is not recommended as a best practice. However, since ColdFusion 8 supports multiple debug sessions, you are able to debug in production without hindering application availability. This is an important benefit as third-party debugging tools for ColdFusion only allow one debug session at a time.

Now you have to tell Eclipse where your ColdFusion server is located. You have the ability to add as many servers as you wish. They can be local (your machine) or a remote server(s). The servers against which you wish to debug must all have debugging enabled, and you must have RDS access as well.

1. With Eclipse open, select Window > Preferences.
2. In the tree menu select the RDS Configuration option (see Figure 3).
3. Enter any description you wish.
4. If your ColdFusion server is running locally, enter 127.0.0.1 for the Host Name.
5. If you installed ColdFusion in a stand-alone configuration, enter 8500 for the port number of the server.

   Note: If you installed ColdFusion in multiserver configuration locally with JRun, your default ColdFusion instance port will be 8300.

6. Enter the username and password you created when installing ColdFusion 8.
7. Click the Test Connection button. See the dialog box in Figure 4 showing that Eclipse can connect to your ColdFusion server.

Now that you have connected to your ColdFusion 8 server, you can view the defined data sources and browse database tables, view all CFCs available to you, and take advantage of the ColdFusion wizards for rapid application development.

Now you have to set up the ColdFusion server you wish to debug code against. In the menu at the top of the Eclipse editor you will see a debug icon that looks like a small bug (see Figure 5).

1. Click the down arrow next to the debug icon and select "Debug" (see Figure 6).

2. Select ColdFusion Application. Next, click the New Launch Configuration button (see Figure 7).

3. Enter a name for your ColdFusion server (see Figure 8). Set the debug homepage URL to http://localhost:8500 if you are running ColdFusion in the stand-alone configuration, or http://localhost:8300 for the default ColdFusion multiple server instance configuration.
4. Click Apply and then click Debug.

If Eclipse did not switch or ask you to switch to the debug view, use the following steps:

1. Select Window > Open Perspective > Other.
2. Select Debug and click OK.

You should now be in the Debug perspective and see the following in the Debug window (see Figure 9).

See that Eclipse is connected to your ColdFusion server. If it isn't, click the down arrow next to the debug button, and then click the name of the debug setting you gave when you set up the debug mappings (see Figure 8).

Now, you will test the debugger by writing some code and setting breakpoints.

1. Put a file on the root of your ColdFusion server.
2. Enter some test code such as the following:

3. Double-click or right-click next to a line of code, and then select "Toggle breakpoint" (see Figure 10). This halts processing at the line, enabling you to inspect variables at that point in the processing of your ColdFusion template. A small blue dot will appear on each line you set a breakpoint to. To remove a breakpoint, simply double-click the breakpoint dot.

4. Browse to the file you just created. In your Eclipse Debug perspective, in the Variables view, you will see output like that shown in Figure 11 when the breakpoint is hit. Here you see all variables that have been created up to the breakpoint you set.

1. If you wish to see more variables than just the local variables, request variables, and argument variables, you must enable additional scopes:

5. Select Window > Preferences.
6. In the tree on the left side, expand the ColdFusion node and select Debug Settings. See the screen shown in Figure 12.

After enabling more scopes for inspection, run your code again to see the changes. Figure 13 shows an example Variables view after enabling the application, server, and session scopes.

In the top of your Debug view (see Figure 14) you will see the following icons that enable you to control how the debugger steps through the code.

Conclusion

Now that you are all hooked up, you can easily use the step-though debugger to get important insight into how your ColdFusion applications are executing.

With everything configured, the next time you start Eclipse, your settings will be in place so that you can start debugging your ColdFusion code right away.