Adobe ColdFusion 8

Approaches to debugging Java CFX tags

Java CFX tags are not stand-alone applications that run in their own process, like typical Java applications. Rather, they are created and invoked from an existing process. This makes debugging Java CFX tags more difficult, because you cannot use an interactive debugger to debug Java classes that have been loaded by another process.

To overcome this limitation, you can use one of the following techniques:

  • Debug the CFX tag while it is running within ColdFusion by outputting the debug information as needed.
  • Debug the CFX tag using a Java IDE (Integrated Development Environment) that supports debugging features, such as setting breakpoints, stepping through your code, and displaying variable values.
  • Debug the request in an interactive debugger offline from ColdFusion using the special com.allaire.cfx debugging classes.

Outputting debugging information

Before using interactive debuggers became the norm, programmers typically debugged their programs by inserting output statements in their programs to indicate information such as variable values and control paths taken. Often, when a new platform emerges, this technique comes back into vogue while programmers wait for more sophisticated debugging technology to develop for the platform.

If you need to debug a Java CFX tag while running against a live production server, this is the technique you must use. In addition to outputting debugging text using the Response.write method, you can also call your Java CFX tag with the debug="On" attribute. This attribute flags the CFX tag that the request is running in debug mode and therefore should output additional extended debugging information. For example, to call the HelloColdFusion CFX tag in debugging mode, use the following CFML code:

<cfx_HelloColdFusion name="Robert" debug="On">

To determine whether a CFX tag is invoked with the debug attribute, use the Request.debug method. To write debugging output in a special debugging block after the tag finishes executing, use the Response.writeDebug method. For information on using these methods, see "ColdFusion Java CFX Reference" in CFML Reference.

Debugging in a Java IDE

You can use a Java IDE to debug your Java CFX tags. This means you can develop your Java CFX tag and debug it in a single environment.

  1. Start your IDE.
  2. In the project properties (or your IDE's project setting), make sure your CFX class is in the web_root\WEB-INF\classes directory or in the system classpath.
  3. Make sure the libraries cf_root/wwwroot/WEB-INF/lib/cfx.jar (cf_webapp_root/WEB-INF/lib/cfx.jar in the J2EE configuration) and cf_root/runtime/lib/jrun.jar (server configuration only) are included in your classpath.
  4. In your project settings, set your main class to jrunx.kernel.JRun and application parameters to -start default.
  5. Debug your application by setting breakpoints, single stepping, displaying variables, or by performing other debugging actions.

Using the debugging classes

To develop and debug Java CFX tags in isolation from the ColdFusion, you use three special debugging classes that are included in the com.allaire.cfx package. These classes lets you simulate a call to the processRequest method of your CFX tag within the context of the interactive debugger of a Java development environment. The three debugging classes are the following:

  • DebugRequest: An implementation of the Request interface that lets you initialize the request with custom attributes, settings, and a query.
  • DebugResponse: An implementation of the Response interface that lets you print the results of a request once it has completed.
  • DebugQuery: An implementation of the Query interface that lets you initialize a query with a name, columns, and a data set.

Implement a main method

  1. Create a main method for your Java CFX class.
  2. Within the main method, initialize a DebugRequest and DebugResponse, and a DebugQuery. Use the appropriate attributes and data for your test.
  3. Create an instance of your Java CFX tag and call its processRequest method, passing in the DebugRequest and DebugResponse objects.
  4. Call the DebugResponse.printResults method to output the results of the request, including content generated, variables set, queries created, and so on.

After you implement a main method as described previously, you can debug your Java CFX tag using an interactive, single-step debugger. Specify your Java CFX class as the main class, set breakpoints as appropriate, and begin debugging.

Example:debugging classes

The following example demonstrates how to use the debugging classes:

import java.util.Hashtable ;
import com.allaire.cfx.* ;

public class OutputQuery implements CustomTag {
    // debugger testbed for OutputQuery
    public static void main(String[] argv) {
        try {
            // initialize attributes 
            Hashtable attributes = new Hashtable() ;
            attributes.put( "HEADER", "Yes" ) ;
            attributes.put( "BORDER", "3" ) ;
 
            // initialize query
 
            String[] columns = { "FIRSTNAME", "LASTNAME", "TITLE" } ;
 
            String[][] data = {
                { "Stephen", "Cheng", "Vice President" },
                { "Joe", "Berrey", "Intern" },
                { "Adam", "Lipinski", "Director" },
                { "Lynne", "Teague", "Developer" } };
 
            DebugQuery query = new DebugQuery( "Employees", columns, data ) ; 

            // create tag, process debugging request, and print results
            OutputQuery tag = new OutputQuery() ;
            DebugRequest request = new DebugRequest( attributes, query ) ;
            DebugResponse response = new DebugResponse() ;
            tag.processRequest( request, response ) ;
            response.printResults() ;
        }
        catch( Throwable e ) {
            e.printStackTrace() ;
        }
}

    public void processRequest(Request request, Response response) throws Exception {
        // ...code for processing the request...
    }
}