Mapping IDE Commands in the Project Properties Dialog Box

The Project Properties dialog box is the main tool for configuring free-form projects in the IDE. To open the dialog box, right-click the free-form project node (icon) in the Projects window and choose Properties. In the Build and Run page, you can set the Ant target to run for the following commands:

• Build Project
• Clean Project
• Generate Javadoc
• Run Project (free-form Java projects)
• Deploy Project (free-form Web projects)
• Test Project

Note: If your Ant script uses an import statement to import targets from another Ant script, the targets do not show up in the drop-down lists in the Project Properties dialog box. To map commands to these targets, you have to type the names of the targets into the drop-down lists.

You can also add shortcuts for any target in your Ant script to the contextual menu of the project's node in the Custom Menu Items list.

Mapping IDE Commands in project.xml

Each IDE project has a project.xml file that contains important metadata about your project's contents, the location of the project's Ant script, which targets to run for IDE commands, and other information. If you want to map commands that work on the presently selected files in the IDE, or if you want to map a command to a target in a separate Ant script, you have to edit the project.xml file by hand. In the Files window, expand the root folder for your project and the nbproject folder, then double-click project.xml.

The ide-actions element holds the mappings for IDE commands. You enter an action element with the name for any of the standard IDE actions and define the script and target to which you want to map the command.

The standard IDE actions that are available are as follows:

• build - Build project (F11)
• rebuild - Clean and build project (Shift-F11)
• compile.single - Compile selected file (F9)
• clean - Clean project
• run - Run project (F6)
• run.single - Run selected file (Shift-F6)
• redeploy - For Web application projects, build project, undeploy project from server, and deploy project to server
• test - Run JUnit tests for project (Alt-F6)
• test.single - Run the JUnit test for selected file (Ctrl-F6)
• debug.test.single - Debug the JUnit test for selected file (Ctrl-Shift-F6)
• debug - Run project in the debugger (F5)
• debug.single - Debug selected file (Ctrl-Shift-F5)
• debug.fix - Run the Apply Code Changes command to reload the selected file during a debugging session
• debug.stepinto - Execute one line of the project main class in the debugger and pause (F7)
• javadoc - Generate Javadoc for project

For example, the following maps the Debug Project to the debug-nb target of the project's Ant script:

  <action name="debug">
    <target>debug-nb</target>
  </action>

The Ant targets for NetBeans IDE commands do not have to live in the same Ant script that you use to build and run the project. This is useful for users who cannot alter their Ant script. The following maps the Debug Project to the debug-nb target in a separate Ant script:

  <action name="debug">
    <script>path/to/my/nbtargets.xml</script>
    <target>debug-nb</target>
  </action>

Note: <script> must precede <target>.

You can also configure a command to run multiple targets. The targets are run in the order they appear in the action. For example, the mapping for the Clean and Build Project command looks like this:

   <action name="rebuild">
        <target>clean</target>
        <target>compile</target>
    </action>

Adding Shortcuts to Project Node Contextual Menu

project.xml also has a context-menu element that controls the contents of a project node's contextual menu. If you manually add an action that is run on the project, make sure you register the action name in <context-menu> as well. If you use the Project Properties dialog box to configure a standard project command, the IDE automatically adds the command to the project's contextual menu.

Back to top

Using Properties in the project.xml File

You can define properties inside the project.xml file itself or store them in a separate .properties file. One way of keeping your project.xml file synchronized with the information in your Ant script is to import properties into project.xml from the same .properties file that is used by your Ant script.

Note, however, that all file paths in project.xml are by default relative to the project folder. If your Ant script is not located in the project folder, a classdir property that points to build/classes/ does not point to the same directory for the Ant script and for the project.xml file. (The project folder is the folder that contains your nbproject folder, not the nbproject folder itself. By default, the new free-form project wizard makes your Ant script's parent folder the project folder.)

You can solve this problem by defining properties for important paths (like project.dir) and using these properties to be more exact (for example, classdir=${project.dir}/build/classes).

To create and import properties in project.xml, enter the following between the name element and the folders element:

<properties>
  <property name="name">value</property>
  <property-file>my-properties-file.properties</property-file>
  <property-file>another-properties-file.properties</property-file>
</properties> 

Note that the syntax is different than the syntax used in Ant scripts. Also note that you while you can add properties in any order, properties can only refer to other properties that have been defined previously in project.xml. The properties file path itself can also use property substitutions.

Validating the project.xml File

The IDE comes bundled with the XML schemas for free-form project.xml files and automatically validates a free-form project.xml file every time you edit and save it. You can view the XML schemas for the free-form project.xml file at the following locations:

• http://www.netbeans.org/ns/freeform-project/1.xsd. Controls the main section of the free-form project.xml (<general-data>).
• http://www.netbeans.org/ns/freeform-project-java/1.xsd. Controls the <java-data> section.
• http://www.netbeans.org/ns/freeform-project-web/1.xsd. Controls the <web-data> section (if you have one).

Back to top

Creating the Debug Target

If you do not have a debug target written for your project, the IDE will offer to generate a basic target for you when you first try to debug the project. You can then inspect the target and customize it for the project's specific requirements.

Note:Before you have the debug target generated, it is a good idea to first make sure that you have a target mapped to the Run Project command. When the IDE generates a debug target, it looks for information in the target you have mapped to the Run Project command to determine such things such as the run classpath and the project's main class. If you have a target mapped to the Run Project command, there is a good chance that the generated debug target will work without further customization.

To create a debug target for a free-form project:

1. In the Projects window, right-click the project's node and choose Set Main Project.
2. Choose Run > Debug Main Project.
3. In the Debug Project dialog box that appears, click Generate.

   A target called debug-nb is created in a file called ide-targets.xml. The generated ide-targets.xml file is a build script that imports your main build.xml file, so your debug target can take advantage of targets and properties set by or referenced by your main build script.

   In addition, a mapping for this target is created in the project.xml file so that the target is called whenever you choose the Debug Project command in the IDE. If you write the target from scratch, you need to also create this mapping yourself. See Manually Mapping a Target to a Menu Item.

4. Verify that the generated debug-nb target properly takes into account all of the elements of your project. In particular, you might need to modify the <classpath> argument in the target if it does not include all of the items in your run classpath.

Once the target is created, you can start debugging. To start debugging:

1. Set a breakpoint in your main class. You can do so by clicking in the left margin of the line where you want to set the breakpoint. The line with the breakpoint is highlighted in pink.
2. Once again, right-click the project's node and choose Debug Project.

   The target should run and start execution of the program. Progress of the running target is shown in the Output window and the status of the debugger is shown in the status bar at the bottom of the Output window.

A Typical Free-Form Project Debug Target

The generated Ant target does the following:

• Starts the debugger with the nbjpdastart task.
• Stores the address at which the debugger listens for the application in the jpda.address property (addressproperty="jpda.address"). You do not have to define the jpda.address property in your Ant script or properties file. It is defined by the IDE.
• Establishes the runtime classpath. If the IDE is not able to determine your runtime classpath, placeholders are put in the script, which you need to fill in yourself.
• Runs the application in debug mode. Setting (fork="true" ensures the process is launched in a separate virtual machine.

Note: You can add any additional JVM arguments or program arguments in the java task as well.

A generated debug target where the IDE is able to guess the runtime classpath looks something like the following (where italicized items would have values specific to your project):

<?xml version="1.0" encoding="UTF-8"?>
    <project basedir=".." name="YourProjectName">
    <import file="../build.xml"/>
    <!-- TODO: edit the following target according to your needs -->
    <!-- (more info: http://www.netbeans.org/kb/archive/index.html) -->
    <target name="debug-nb">
    <nbjpdastart addressproperty="jpda.address" name="NameOfProject" transport="dt_socket">
    <classpath path="ClasspathSpecifiedInYourRunTarget"/>
    </nbjpdastart>
    <java classname="MainClassSpecifiedInRunTarget" classpath="ClasspathSpecifiedInYourRunTarget" fork="true">
    <jvmarg value="-Xdebug"/>
    <jvmarg value="-Xnoagent"/>
    <jvmarg value="-Djava.compiler=none"/>
    <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
    </java>
    </target>
    </project>

If you do not have a run target mapped or the IDE otherwise can not determine the project's classpath or main class, the generated debug target includes "TODO" placeholders for you to fill in these values as in the example below.

<?xml version="1.0" encoding="UTF-8"?>
    <project basedir=".." name="YourProjectName">
    <!-- TODO: edit the following target according to your needs -->
    <!-- (more info: http://www.netbeans.org/kb/archive/index.html) -->
    <target name="debug-nb">
    <path id="cp">
    <!-- TODO configure the runtime classpath for your project here: -->
    </path>
    <nbjpdastart addressproperty="jpda.address" name="NameOfProject" transport="dt_socket">
    <classpath refid="cp"/>
    </nbjpdastart>
    <!-- TODO configure the main class for your project here: -->
    <java classname="some.main.Class" fork="true">
    <classpath refid="cp"/>
    <jvmarg value="-Xdebug"/>
    <jvmarg value="-Xnoagent"/>
    <jvmarg value="-Djava.compiler=none"/>
    <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
    </java>
    </target>
    </project>

To specify the runtime classpath, insert pathelement elements within the path element and point them to the directories that contain the items in your classpath. For example, you can use the location attribute of pathelement to specify the location of the classpath items relative to your project directory. The project directory is usually the one that contains the project's build.xml file. Below is an example:

<path id="cp">
    <pathelement location="libs">
    <pathelement location="build">
</path>

Manually Mapping a Target to a Menu Item

When you have the IDE generate a target, the IDE automatically provides the mapping between the target and the IDE command's menu item. However, if you have created the target manually, you need to also create the mapping manually.

To map the Debug Project command to a target in an external Ant script:

1. Open the project's project.xml file and add the following to <ide-actions>:

     <action name="debug">
           <script>path_to_Ant_script</script>
           <target>target_name</target>
           </action> 

2. Add the command to the project node's contextual menu, by adding the following line to the <context-menu> target:

     <ide-action name="debug"/>

   The IDE maps the Debug Project action to the specified target in the project's Ant script.

Using the Debug Target

Before you can use your debug target, you need to deploy your application. Therefore, start the server and run deploy the application. Note that the first time that you run the application per session, the Tomcat Web Server asks you for a username and password. The only acceptable username and password is that of a user with a "manager" role. This is defined in the conf/tomcat-users.xml file in the Tomcat Web Server's base directory. To identify the location of this directory, right-click the Tomcat Web Server instance node in the Runtime window and select Properties. In the Properties dialog box, the Base Directory property points to the Tomcat Web Server's base directory.

Once the application is deployed, stop the server and restart it in debug mode. The way this is done depends on the server:

• Bundled Tomcat Web Server

  Expand the Servers node in the Runtime window, right-click the Bundled Tomcat node, choose Start/Stop Server, and click Start Server (Debug).

• External Tomcat Web Server

  Run the following command:

    catalina jpda start 

Once the server has started in debug mode, choose Run > Debug Main Project (F5). The application is deployed and is attached to the debugger. The debugger stops at the first breakpoint, after which you can step into (F7) or over (F8) the code.

Troubleshooting the Debug Target

Even though the IDE does its best to generate a complete debug target for you, with properties that are tailored to your specific environment, you should always analyze and fine tune the debug process. Work through the questions below when you encounter problems while using an Ant debug target from the NetBeans IDE.

Back to top

Running the Selected File

Let's demonstrate how this works when you run a class. A typical target for running a project looks something like the following:

    <target name="run2" depends="...">
        <java fork="true" classname="MyMainClass" classpath="MyRunClasspath" />
    </target>
 

The target runs the file specified by classname. To run the currently selected file in the IDE, you need to modify the above target to something like the following:

  <target name="run-selected-file" depends="compile" description="Run Single File">
      <fail unless="runclass">Must set property 'classname'</fail>
      <java classname="${runclass}">
         <classpath refid="run.classpath"/>
      </java>
   </target>

Getting a Reference to the Currently Selected File in the IDE

Once you have an Ant target for running the selected file, you have to get a reference to that file in the IDE and store it in a property. For example, the run-selected-file target above looks for the currently selected file in the runclass property.

You store this reference in the same place where you map the build target (run-selected-file) to the IDE action. First we will look at how to do this and then we will explain it in detail:

    <action name="run.single">
        <target>run-single</target>
        <context>
            <property>runclass</property>
            <folder>${src.dir}</folder>
            <pattern>\.java$</pattern>
            <format>java-name</format>
            <arity>
                <one-file-only/>
            </arity>
        </context>
    </action>

The runclass property is a newly defined property that holds the file that you want to run and is referenced by the java task.

Now let's take a look at the following lines to see how it works.

<action name="run.single">
      <target>run-selected-file</target>
      <context>
        <property>runclass</property>

• <action name="run.single"> maps the Run File command and the F9 shortcut to the run-selected-file target.
• <context> sets the context on which the Ant target is executed. In this case, it is the name of file that you want to run.
• runclass is the name of the property that holds the context. You can choose any unique name for this property. This property must be set by the IDE before the target can be run.
• <arity> specifies that runclass can hold only one file. If you want the property to be able to hold more than one file (such as for the Compile File target), you can use the following, where the comma (,) is the separator between file names:

          <arity>
            <separated-files>,</separated-files>
          </arity>

• <format>java-name</format> specifies that the IDE should pass the relative file name to the target but delimited by periods (.) and without an extension. Other formatting options include the following:
  • relative-path - specifies that the IDE should pass the relative file name to the target
  • relative-path-noext - Same as relative-path, but the file's extension is removed
  • absolute-path - Absolute file name
  • absolute-path-noext - Same as absolute-path, but the file's extension is removed
• <folder>${src.dir}</folder> specifies that the file name should be relative to the src.dir directory and that this action is only enabled for the src.dir directory.

  Note: The IDE does not define the ${src.dir} property for you. You have to define the property or import the .properties file that the Ant is using in project.xml. See Using Properties in the project.xml File for more information.

• <pattern>\.java$</pattern> is the regular expression which the file names must pass. You use <pattern> to limit which files can be passed to the Ant target. In this case, you want the target be executed only with files that end in .java.

Debugging the Selected File

The process is basically the same for writing targets to debug and run a single file. The debug-selected-files target looks something like this:

    <target name="debug-selected-files" depends="compile" if="netbeans.home" description="Debug a Single File">
       <fail unless="classname">Must set property 'classname'</fail>
       <nbjpdastart name="${classname}" addressproperty="jpda.address" transport="dt_socket">
          <classpath refid="run.classpath"/>
          <!-- Optional - If source roots are properly declared in project, should
          work without setting source path.
          <sourcepath refid="debug.sourcepath"/> -->
       </nbjpdastart>
       <java classname="${classname}" fork="true">
          <jvmarg value="-Xdebug"/>
          <jvmarg value="-Xnoagent"/>
          <jvmarg value="-Djava.compiler=none"/>
          <jvmarg value="-Xrunjdwp:transport=dt_socket,address=${jpda.address}"/>
          <classpath refid="run.classpath"/>
       </java>
     </target>

• This is basically the same as the debug target. Instead of passing the program main class to java, you pass the classname property, which is set by the IDE to the currently selected file.

Then you map the debug-selected-files target to the debug.single action:

   <action name="debug.single">
      <target>debug-selected-files</target>
      <context>
         <property>classname</property>
         <folder>${src.dir}</folder>
         <pattern>\.java$</pattern>
         <format>java-name</format>
         <arity>
            <one-file-only/>
         </arity>
      </context>
   </action>

• <property> now stores the context in the classname property.
• Since java can only take single file, you set <arity> to <one-file-only>.
• Setting <format> to java-name and making it relative to src.dir creates a fully-qualified class name for the currently selected file.

  Note: The IDE does not define the ${src.dir} property for you. You have to define the property or import the .properties file that the Ant is using in project.xml. See Using Properties in the project.xml File for more information.

Back to top