Setting up the Debug Project Command for a Web Application

To get debugging to work with a free-form web project, you need to:

• Make sure that the target you use for compiling specifies debug="true" when calling the javac task.

• Create a mapping in the IDE between the project's sources and the project's outputs so that the debugger knows which sources to display when you are stepping through the running program.

• Add a target to your Ant script for attaching the debugger to a running web application, making sure that all necessary path elements for the command are defined, either in the build script or in a .properties file that is called by the script.

• Make sure your server is started in debug mode.

• Make sure your web application is already deployed. (To be able to deploy your application with the IDE's Run Project command, you need to have a target in your build script for deploying your web application and have that target mapped to the Deploy command. You can provide this mapping in the wizard when creating the project or on the Build and Run page of the Project Properties dialog box.)

You can have the IDE generate a debug target for you by running the Debug Main Project command (assuming you have set the free-form project as your main project) or Debug Project command and then clicking the Generate button in the dialog box that appears.

When you generate the debug target, it appears (along with four supporting targets) in a file called ide-file-targets.xml, which imports your main build script. This enables you to have IDE-only targets separate from other targets but still allow the IDE-specific targets to reference targets and properties in your main build script. You can find this file in the project's nbproject folder, which you can access through the Files window.

The generated targets should look something like the following:

<target name="-load-props">     <property file="nbproject/debug.properties"/> </target> <target name="-check-props">     <fail unless="jpda.session.name"/>     <fail unless="jpda.host"/>     <fail unless="jpda.address"/>     <fail unless="jpda.transport"/>     <fail unless="debug.sourcepath"/>     <fail unless="client.url"/> </target> <target depends="-load-props, -check-props" name="-init"/> <target depends="-init" if="netbeans.home" name="debug-nb">     <nbjpdaconnect address="${jpda.address}" host="${jpda.host}"         name="${jpda.session.name}" transport="${jpda.transport}">         <sourcepath>             <path path="${debug.sourcepath}"/>         </sourcepath>     </nbjpdaconnect>     <antcall target="debug-display-browser"/> </target> <target name="debug-display-browser">     <nbbrowse url="${client.url}"/> </target>

In addition, a file called debug.properties is generated. This file should look something like the following:

jpda.session.name=My_Project jpda.host=localhost # Sun Java System Application Server using shared memory (on Windows) # jpda.address=localhost4848 # jpda.transport=dt_shmem # Sun Java System Application Server using a socket # jpda.address=9009 # jpda.transport=dt_socket # Tomcat using shared memory (on Windows) # jpda.address=tomcat_shared_memory_id # jpda.transport=dt_shmem # Tomcat using a socket jpda.address=11555 jpda.transport=dt_socket src.folders=src web.docbase.dir=web # you can change this property to a list of your source folders debug.sourcepath=${src.folders}:${web.docbase.dir} # Client URL for Tomcat client.url=http://localhost:8084/myproject # Client URL for Sun Java System Application Server # client.url=http://localhost:8080

You should be able to get the generated target to work merely by making appropriate edits to the debug.properties file. After being customized for your environment, the generated target can be used in your project. See Table 16-4 for further details on the debug.properties file and Table 16-5 for details on the debug targets.

Table 16-4. Details of the debug.properties File for a Web Application

Debug Property	Description
jpda.session.name	The name that appears in the Sessions window when you debug the application.
jpda.host	The hostname of the machine that the debugged application is running on.
jpda.address	The port that the debugger is listening on.
jpda.transport	The JPDA debugging transport protocol to use. You can use dt_socket on all platforms. On Windows machines, you can also use dt_schem, though the IDE and the debugged application would both have to be running on the same machine.
src.folders	The location of your Java source files.
web.docbase.dir	The location of your web root.
debug.sourcepath	The location of the sources to be referenced when debugging. By default, the value is a reference to the src.folders and web.docbase.dir properties.
client.url	The web page to be opened in the default browser that is specified by the IDE.

Table 16-5. Details of the Debug Target for a Web Application

Target, Task, Attribute, or Property	Description
depends	Attribute where you specify targets that need to be run before the current target is run.
netbeans.home	Ant property that is loaded by any instance of Ant that runs inside of the IDE. The if="netbeans.home" attribute ensures that the target is run only if it is called from within the IDE.
nbjpdaconnect	A special task bundled with the IDE to enable attaching the JPDA debugger to a running application.
host	An attribute of nbjpdaconnect that specifies the hostname of the machine that the debugged application is running on. In this example, the jpda.host property is used. The value of this property is defined in the debug.properties file that is referenced by the build script.
address	An attribute of nbjpdaconnect that specifies the port that the debugger is listening on. In this example, the jpda.address property is used. The value of this property is defined in the debug.properties file.
transport	An attribute specifying the JPDA debugging transport protocol to use. You can use dt_socket on all platforms. On Windows machines, you can also use dt_schem, although the IDE and the debugged application would both have to be running on the same machine.
classpath	An optional attribute of nbjpdaconnect that represents the classpath used for debugging the application.
sourcepath	An attribute of nbjpdaconnect used to specify the explicit location of source files that correspond to JAR files in your classpath.
nbbrowse	Element that specifies a web page to be opened in the default browser that is specified by the IDE. In this example, the client.url property is used. The value of this property would need to be defined elsewhere in the build script or in a .properties file that is referenced by the build script.