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
• Debug 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 - 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

Compiling the Selected Files

Let's demonstrate how this works with compilation. A typical target for compiling all project sources usually looks something like the following:

  <target name="compile" depends="...">
    <mkdir dir="${classes.dir}"/>
    <javac srcdir="${src.dir}" destdir="${classes.dir}">
      <classpath refid="javac.classpath"/>
    </javac>
  </target>

The target compiles all files from src.dir. To compile a single file (or the list of selected files), you need to modify the above target to the following:

  <target name="compile-selected-files" depends="...">
    <fail unless="files">Must set property 'files'</fail>
    <mkdir dir="${classes.dir}"/>
    <javac srcdir="${src.dir}" destdir="${classes.dir}" includes="${files}">
      <classpath refid="javac.classpath"/>
    </javac>
  </target>

The files property is a newly defined property that holds the file (or files) that you want to compile. The javac task accepts a comma-separated list of file names. The file names are specified relative to the directory specified in the srcdir attribute (for example, org/nb/Foo.java,org/nb/Bar.java).

Getting a Reference to the Currently Selected File in the IDE

Once you have an Ant script that supports single file compilation, you have to get a reference to the currently selected file in the IDE and store it in a property. For example, the compile-selected-files target above looks for the currently selected files in the files property.

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

  <ide-actions>
    <action name="compile.single">
      <target>compile-selected-files</target>
      <context>
        <property>files</property>
        <folder>${src.dir}</folder>
        <pattern>\.java$</pattern>
        <format>relative-path</format>
        <arity>
          <separated-files>,</separated-files>
        </arity>
      </context>
    </action>

Now let's take a look at how it works.

<action name="compile.single">
      <target>compile-selected-files</target>

• Maps the Compile File command and the F9 shortcut to the compile-selected-files target.

      <context>
        <property>files</property>

• <context> sets the context on which the Ant target is executed. In this case, it is the name of files that you want to compile.
• files 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.

        <folder>${src.dir}</folder>
        <pattern>\.java$</pattern>
        <format>relative-path</format>
        <arity>
          <separated-files>,</separated-files>
        </arity>
      </context>
    </action>

• <arity> specifies that files can hold multiple files and that the separator is a comma. If your target accepts only one file at time then change the declaration to:

  <arity>
    <one-file-only/>
  </arity>

• <format>relative-path</format> specifies that instead of passing the selected file's absolute file name to the Ant target, the IDE should pass the relative file name. Other formatting options are:
  • 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
  • java-name - Same as relative-path-noext, but a dot character (.) is used instead of a slash (/)
• <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.

Note: You can configure multiple compile.single actions to overload the F9 shortcut and menu command with different functionality depending on what file is selected. For example, you could set up a separate compile-selected-files target for JUnit test classes, then map compile.single to that target for all sources in JUnit test directories. Or you could change the pattern to \.xml$ and map F9 to a Validate XML target for all XML files.

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.

Running the Selected File

The run-selected-files target looks something like this:

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

And you hook it up to the Run File command and the Shift-F6 shortcut with the following action:

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

Back to top