Approaches to Debugging Java CFXs

Java CFXs are not standalone applications that run in their own process like typical Java applications. Rather, they are created and invoked from an existing process - ColdFusion Server. This makes debugging Java CFXs 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 two techniques:

Debug the CFX while it is running within ColdFusion Server by outputting debug information as needed.
Debug the request in an interactive debugger offline from ColdFusion Server using the special com.allaire.cfx debugging classes.

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

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

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

Using the debugging classes

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

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

To use the debugging classes:

Create a main method for your Java CFX class. You use this method as the testbed for your CFX.
Within the main method, initialize a DebugRequest and DebugResponse, and a DebugQuery if appropriate, with the attributes and data you want to use for your test.
Create an instance of your Java CFX and call its processRequest method, passing in the DebugRequest and DebugResponse objects.
Call the DebugResponse.printResults method to output the results of the request, including content generated, variables set, queries created, and so forth.

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

Debugging classes example

The following example demonstrates the use of 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 debug 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 ) throws Exception
   {
      // ...code for processing the request...
   }
}

LiveDocs comments are not longer enabled for ColdFusion 5.0. Please use one of the following resources instead.

Version 5.0

Developing ColdFusion Applications
Building Custom CFXAPI Tags