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 it is not possible to 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:

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 be brought to 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 simply outputting debug text using the Response.write method, you can also use the DEBUG attribute in your Java CFX. 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, you would use the following CFML code:

<CFX_HelloColdFusion" NAME="Robert" DEBUG="On">

To determine if a CFX has been invoked with the DEBUG attribute, you use the Request.debug method. To write debug output which will be printed in a special debug block after the tag finishes executing, you use the Response.writeDebug method. See the "Java CFX Reference" for details on using these methods.

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:

Note To use the debugging classes:
  1. Create a main method for your Java CFX class. This method will be used as the testbed for your CFX.
  2. 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.
  3. Create an instance of your Java CFX 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 forth.

Once you have implemented a main method as described above, 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...
   }
}

Debugging Classes Reference

The specific constructors and methods supported by the DebugRequest, DebugResponse, and DebugQuery classes are as follows. Note that these classes also support the other methods of the Request, Response, and Query interfaces, respectively.

DebugRequest

// initialize a debug request with attributes
public DebugRequest( Hashtable attributes ) ;

// initialize a debug request with attributes and a query
public DebugRequest( Hashtable attributes, Query query ) ;

// initialize a debug request with attributes, a query, and settings
public DebugRequest( Hashtable attributes, Query query, 
                     Hashtable settings ) ;

DebugResponse

// initialize a debug response
public DebugResponse() ;

// print the results of processing 
public void printResults() ;

DebugQuery

// initialize a query with name and columns
public DebugQuery( String name, String[] columns ) 
   throws IllegalArgumentException ;

// initialize a query with name, columns, and data
public DebugQuery( String name, String[] columns, String[][] data ) 
    throws IllegalArgumentException ;