Advanced Free-Form Project Configuration

Free-form projects in NetBeans IDE provide a very powerful tool for Java developers who build and run their applications using an Ant script.

If you are comfortable working with Ant, you can edit your Ant script and the IDE project configuration file to achieve an even tighter integration between NetBeans IDE and your build process.

Note: For detailed information about free-form projects, see Creating Free-Form Projects in Developing Applications with NetBeans IDE.

This article assumes that you have already used the New Project wizard to set up a free-form project.

This article covers the following information:

You can also download Sample Ant Targets.

Managing the Classpath in Free-form Projects

In free-form projects, your Ant script handles the classpath for all of your source folders. To make project sources available to Ant, you need to specify the classpath for the project sources. If you have any custom tasks, you also need to add these tasks to Ant's classpath.

Specifying the Classpath for Project Sources

In free-form projects you tell the IDE what classes to make available for code completion and refactoring and specify the classpath for these project sources. You specify the classpath in the Java Sources Classpath settings in the Project Properties dialog box. You do this because by default the IDE ignores your environment's CLASSPATH variable whenever it runs Ant.

The classpath variable you set in the Project Properties dialog box does not affect the actual classpath of the project, which is specified in the Ant script. Declaring the classpath in the Project Properties dialog box does not change the actual compilation or runtime classpath of the source folders. However, the project classpath variable must match the classpath used by your Ant script in order to provide the correct information for code completion, error highlighting, and refactoring commands. You have to set an explicit classpath in your build scripts because the IDE ignores your environment's CLASSPATH variable whenever it runs Ant. If you change the classpath of one, you must change the class path of the other

Specifying the Classpath for Custom Tasks

In free-form projects, you can call up and run custom Ant tasks in your build script. For your Ant script to use customs tasks, you must include the tasks in the Ant script's classpath. For example, you may add a task to your build script to format your code with Jalopy. In order to do this, however, you have to add the Jalopy JAR file to Ant's classpath.

You can add custom tasks to Ant's classpath within the IDE by doing either of the following:

  • Providing an explicit classpath to the tasks in your build script. This is the recommended method for specifying the location of JAR files that contain custom tasks used by your Ant script, as it ensures that your build scripts will be fully portable. You can write your tasks and include instructions to compile them and produce a JAR file in the build file. To use these tasks, include the long form of taskdef, which includes a classpath. Here is a simple example of such a task:
<project name="test" default="all" basedir=".">
    <target name="init">
        <javac srcdir="tasksource" destdir="build/taskclasses"/>
        <jar jarfile="mytasks.jar">
            <fileset dir="build/taskclasses"/>
        </jar>
        <taskdef name="customtask" classname="com.mycom.MyCustomTask">
            <classpath>
                 <pathelement location="mytasks.jar"/>
            </classpath>
        </taskdef>
    </target>
</project>

The advantage of this method is that no special preparation is needed to begin using the script. The script is entirely self-contained and portable. This method also makes it easier to develop your tasks within the IDE, as the script compiles them for you automatically.

To make your build scripts even more robust, use a property instead of a hard-coded location to specify the classpath to your tasks. You can store the property in the build script itself or in a separate ant.properties file. You can then change the classpath setting throughout your script by simply changing the value of the specified property.

  • Configuring the Ant Classpath property in the Options window. If you cannot declare a classpath in your build script, or you are using third-party build scripts which you cannot alter, you can add tasks to Ant's classpath in the IDE in the Options window.

Note: If you modify the Ant classpath in the Options window, the task is on Ant's classpath for all projects when you run Ant in the IDE.

Mapping IDE Commands to Ant Targets

There are three ways to map an IDE command to a target in an Ant script:

  • By adjusting the settings in the Build and Run page of a project's Project Properties dialog box
  • By having the IDE generate a target for you and then customizing this target to your needs. This works for the Debug Project and Compile File commands. The IDE offers to generate these targets the first time you run those commands in the project.
  • By manually editing the project's project.xml file.

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)
  • profile.test.single - Profile the JUnit test for the selected file
  • profile - Run project in the profiler (Alt-F2)
  • profile.single - Profile the selected file
  • 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.

Editing the project.xml File

Each IDE project has a project.xml file that includes important information about the project, such as:

  • Mappings between project commands and targets in an Ant script
  • Information about the project's contents, classpath, and target Java platform. This information is used to visualize the project and enable code completion and refactoring

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:

Creating a Target to Debug Your Java SE Application

Similar to commands for compiling and running, debugging commands rely on various information, such as the location of your sources, the location of the compiled classes and other items on the classpath, and name of the project's main class.

In free-form projects, the IDE does not "know" about any of these things. When you run a command in the IDE (such as Build Project), the IDE simply calls a target in your build script and lets the script handle the command. Therefore, for debugging to work, you also have to have a build script target for debugging. The IDE provides some custom Ant tasks to work with the debugger and also can generate a basic debug target, which attempts to fill in important details based on other targets in your script.

To set up debugging in a free-form project, you need to do the following:

  • Make sure that your classes are compiled with debugging information included. For example, you might accomplish this in the compile target of your build script by including the argument debug="true" in the <javac> task.
  • If the output of a free-form project is on the classpath of another project, map the free-form project's source packages to their outputs. This ensures that you can use the debugger to step into the project's sources when you start a debugging session in a project that has a dependency on the free-form project. You can do this in the Output panel of the Project Properties dialog box for the free-form project. You can open the Project Properties dialog box by right-clicking the project's node in the Projects window and choosing Properties.
  • Create a target in your build script for debugging and map that target to the IDE's Debug Project command. The IDE can assist you by generating a basic target and mapping, but you might need to modify the target.

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: https://netbeans.org/kb/articles/freeform-config.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: https://netbeans.org/kb/articles/freeform-config.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 in the editor.
  2. Add the following to <ide-actions>:
      <action name="debug">
            <script>path_to_Ant_script</script>
            <target>target_name</target>
        </action> 
  3. 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.

Creating a Target to Debug Your Web Application

Now let's look at a target to attach a debugger to a web application. First, choose Run > Debug Main Project (F5). If you do not have a target mapped to the Debug command, you are prompted to let the IDE generate an IDE-specific debug target for you in the nbproject/ide-targets.xml file. When you click Generate, the debug-nb target is generated, together with the -load-props, -check-props, -init, and debug-display-browser targets, which support the debug target. The targets are displayed in the Source Editor as follows:

(Note: These targets are not generated in the IDE. Therefore, you need to change the generated code so that it looks as follows.)

    <target name="-load-props">
       <property file="nbproject/project.properties"/>
    </target>

    <target name="-check-props">
       <fail unless="session.name"/>
       <fail unless="jpda.host"/>
       <fail unless="jpda.address"/>
       <fail unless="jpda.transport"/>
       <fail unless="web.docbase.dir"/>
       <fail unless="debug.sourcepath"/>
       <fail unless="client.url"/>
    </target>

    <target depends="-load-props, -check-props" name="-init"/>

    <target depends="-init" name="debug-nb" description="Debug Project">
       <nbjpdaconnect address="${jpda.address}" host="${jpda.host}"
        name="${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>

There's no need for you to customize the generated targets. All you have to do is set the properties that the IDE requires to use the targets it generated. For example, you need to tell the IDE where your application's sources are. To do this, you will set properties in the nbproject/debug.properties file that the IDE created for you when it generated the debug-nb target above. Using the -load-props target above, the IDE will load the properties when you run the debug-nb target

(Note: This file is not generated in the IDE. You need to go to the Files window, expand the project node, right-click the nbproject folder, and choose New > File/Folder. Choose Other > Properties File, name the file debug, and click Finish. In the new debug.properties file, add the following properties.)

  jpda.session.name=MyProject
  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

The table below explains the properties defined above.

Property Value Notes
jpda.session.name   The display name given in the Sessions window when you debug the project.
jpda.host   The host that the application to be debugged uses to connect to the debugger, such as localhost.
jpda.address The bundled Tomcat Web Server defaults are 11555 for socket connections and tomcat_shared_memory_id for shared memory connections. To set a different address, right-click the Tomcat node in the Services window and choose Properties. In the Properties sheet, change the Debugging Port property (for socket connections) or Name property (for shared memory connections). Then close the Properties sheet. Now stop and restart the Tomcat Web Server, if you had already started it.
jpda.transport dt_socket (for socket connections) or shmem (for shared memory connections) To set a different transport, right-click the Tomcat node in the Services window and choose Properties. In the Properties sheet, change the Debugging Type. Then close the Properties sheet. Now stop and restart the Tomcat Web Server, if you had already started it.
web.docbase.dir
src.folders
The location of your web root (web.docbase.dir) and Java source files (src.folders). Multiple source roots can be included in the sourcepath by means of the ":" delimiter. Note that the Java source folders must be specified as Source Package Folders in the Java Sources panel of the Project Properties dialog box. (Right click the project, choose Properties, then click Java Sources in the Project Properties dialog box.)
client.url   The URL that should be opened in the IDE's default browser, such as http://localhost:8084/MyProject.

Note that the debug-nb target is automatically mapped to the Debug Project command. However, if you keep this target in a different Ant script, open the project's project.xml file and change the script element in the ide-actions section:

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

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 Services 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 Services 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.

Has the web application been correctly deployed?

Check that the web application has been deployed:

  1. In the Services window, expand the Servers node, start the server (if not started), expand the server's instance node, and expand the Web Applications node.
  2. If you do not see your application's context (/MyProject, for the application in this document), it has not been correctly deployed.
  3. Deploy the application.

Are you behind a firewall?

Check that your proxy settings are correct. Depending on your proxy type do the following:

  • HTTP Proxy. Choose Tools > Setup Wizard. In the wizard, select the Use HTTP Proxy Server checkbox. Type the proxy host name in the Proxy Server Name field and the port number in the Port field. Click Finish.
  • SOCKS Proxy. You must pass the SOCKS proxy host and proxy port parameters to the JVM software when you start the IDE. On Microsoft Windows machines, use the IDE-HOME/etc/netbeans.conf file to pass the parameters. On UNIX and Linux machines, you can write a wrapper shell script. Go to Help > Help Contents for details.

Is the server running in debug mode?

Check that the server has been started in debug mode:

  1. In the Services window, expand the Servers node and check that the server is running. Note that even if it is running, it may not be running in debug mode.
  2. If it is not running, right-click it, choose Start/Stop Server, and click Start Server (Debug). If it is running, but you are not sure that it is running in debug mode, stop the server and restart it in debug mode.

Are the server's port and address set correctly?

Check that the jpda.address set in debug.properties matches the server's settings:

  1. Right-click the server's node in the Services window and choose Properties.
  2. In the Properties sheet:
    • Check the Debugging Port property (for socket connections). By default, it should be 9009 for the SJS Application Server or 11555 for the Tomcat Web Server.
    • Check the Name property (for shared memory connections). By default, it should be localhost4848 for the SJS Application Server or tomcat_shared_memory_id for the Tomcat Web Server.
    If you change the server's Debugging Port property or Name property, make sure that it matches the related property in the debug.properties file.
  3. Close the Properties sheet and stop and restart the server, if you had already started it.

Check that the jpda.transport set in debug.properties matches the server's settings:

  1. Right-click the server's node in the Services window and choose Properties.
  2. In the Properties sheet, check the Debugging Type property:
    • dt_socket for socket connections
    • dt_shmem for shared memory (Windows)
    If you change the server's Debugging Type property, make sure that it matches the related property in the debug.properties file.
  3. Close the Properties sheet and stop and restart the server, if you had already started it.

Unable to step through your code?

If you are unable to step from line to line in your code, but only from breakpoint to breakpoint, the IDE has not been able to find your sources. This is because you have not specified your sources correctly.

  • Servlets: Choose Window > Debugging > Sources. The Sources window displays all the Java source folders that are available for debugging. If you want to debug a source folder that is not available in the Sources window, specify it in the Project Properties dialog box:
    1. Right-click the project node, choose Properties, click Java Sources.
    2. Add the source folders to be debugged to the Source Package Folders table or to the Test Package Folders table.
    Note that the target you use for compiling servlets must specify debug="true" when calling the javac task. If a servlet is compiled without debug info, the debugger will not stop on its breakpoints.
  • JSP pages: Make sure that you have defined a context path for the project:
    1. Right-click the project node, choose Properties, click Web Sources.
    2. Type the context path. For example, type /MyProject in the Context Path field.

    Note that if you have set your breakpoints before specifying the context path, you must remove and reset the breakpoints after specifying the context path. In other words, the context path must be set first.

Also make sure that the sources are correctly specified in the debug.properties file and in the debug-nb target. Note that if your nbproject folder is not housed within the folder that houses your sources folder, you should set the following properties for your src.folder and web.docbase.folders properties:

  • src.folders=${project.dir}/src
  • web.docbase.dir=${project.dir}/web

Back to top

Creating a Target to Profile Your Java SE Application

Similar to the commands for compiling and running, profiling commands rely on information such as the location of the sources, compiled classes and other items on the classpath and the name of the project's main class.

In free-form projects the IDE does not "know" about any of these things. When you run a command in the IDE (such as Build Project), the IDE simply calls a target in the build script and lets the script handle the command. Therefore, for debugging to work you need to have a build script target for debugging. The IDE provides some custom Ant tasks to work with the profiler, and the IDE can generate a basic profile target and attempt to determine the important details for the profile target based on other targets in the script.

To set up profiling in a free-form project you need to create a target in your build script for profiling and map that target to the IDE's Profile Project command. The IDE can assist you by generating a basic target and mapping, but you might need to modify the target.

Creating the Profile Target

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

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

Perform the following steps to create a profile target for a free-form project.

  1. Select the project node in the Projects window.
  2. In the main menu choose Run > Set Main Project and select the project name.
  3. Choose Profile > Profile Main Project.
  4. Click Generate in the Profile Project dialog box.
    screenshot of Profile Project dialog box

    When you click Generate a target named profile-nb is created in the ide-targets.xml XML file. The generated ide-targets.xml file is a build script that imports your main build.xml file. This enables your profile target to 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 when you choose the Profile Project command in the IDE. If you write the target from scratch you also need to create this mapping yourself. See Manually Mapping a Target to a Menu Item.

  5. Verify that the generated profile-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.

After the target is created you can start profiling. Perform the following steps to start profiling.

  1. Right-click the project's node and choose Profile Project.
  2. Configure the profiling session and confirm the settings.

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

A Typical Free-Form Project Profile Target

The generated Ant target does the following:

  • Starts the profiler with the startprofiler task. Setting the freeform attribute to true will force displaying the profiling session configuration dialog.
  • The previous task sets the profiler.configured to true if the configuration was confirmed. It also stores the profiler agent JVM arguments in the agent.jvmargs property.
  • Establishes the runtime classpath. If the IDE is not able to determine your runtime classpath the IDE adds placeholders to the script which you need to fill in yourself.
  • Runs the application in profile 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 profile target where the IDE is able to guess the runtime classpath will look similar to the following (where the italicized items would have values specific to your project).

<?xml version="1.0" encoding="UTF-8"?>
    <project basedir=".." name="YourProjectName">
        <import file="../build.xml"/>
        <target name="-profile-check">
            <startprofiler freeform="true"/>
        </target>
        <!-- TODO: edit the following target according to your needs -->
        <!-- (more info: https://netbeans.org/kb/articles/freeform-config.html#profilej2se) -->
        <target name="profile-nb" if="profiler.configured" depends="-profile-check">
            <java classname="${mainclass}" dir="." fork="true">
                <classpath>
                    <pathelement path="ClasspathSpecifiedInYourRunTarget"/>
                </classpath>
                <jvmarg line="${agent.jvmargs}"/>
            </java>
        </target>
    </project>

If you do not have a run target mapped or the IDE otherwise cannot determine the project's classpath or main class, the generated profile 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">
        <target name="-profile-check">
            <startprofiler freeform="true"/>
        </target>
        <!-- TODO: edit the following target according to your needs -->
        <!-- (more info: https://netbeans.org/kb/articles/freeform-config.html#profilej2se) -->
        <target depends="-profile-check" if="profiler.configured" name="profile-nb">
            <path id="cp">
                <!-- TODO configure the runtime classpath for your project here: -->
            </path>
            <!-- TODO configure the main class for your project here: -->
            <java classname="some.main.Class" fork="true">
                <classpath refid="cp"/>
                <jvmarg line="${agent.jvmargs}"/>
            </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 directory that contains the project's build.xml file. Below is an example of using the pathelement attributes.

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

Manually Mapping a Target to a Menu Item

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

To map the Profile Project command to a target in an external Ant script, perform the following steps.

  1. Open the project's project.xml file and add the following to <ide-actions>.
    <action name="profile">
        <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="profile"/>

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

Creating a Target to Compile a Single File

If you want to be able to select files in the IDE and compile them individually, you need an Ant target for the Compile File command. The IDE offers to generate a target the first time you choose the command. The generated target looks something like this:
 <?xml version="1.0" encoding="UTF-8"?>
<project basedir=".." name="MyProjectName">
    <!-- TODO: edit the following target according to your needs -->
    <!-- (more info: https://netbeans.org/kb/archive/index.html) -->
    <target name="compile-selected-files-in-src">
        <fail unless="files">Must set property 'files'</fail>
        <!-- TODO decide on and define some value for ${build.classes.dir} -->
        <mkdir dir="${build.classes.dir}"/>
        <javac destdir="${build.classes.dir}" includes="${files}" source="1.5" srcdir="src"/>
    </target>
</project>
In the generated target, you need to specify the directory where to put the compiled class or classes. You can do so by specifying a value for the build.classes.dir property in the generated target. For example, you might add the following line to the line above the <target name="compile-selected-files-in-src"> entry:
<property name="build.classes.dir"  value="build"/>

Alternatively, you can replace the value of the provided build.classes.dir or rewrite the target entirely.

The value of the includestt> parameter is the value of the generated files property. The IDE uses this property to store the name of the currently selected file (or files).

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.

Writing a Target to Run/Debug/Test a Single File

The IDE does not generate targets for the Run File, Debug File, Test File, and Debug Test for File commands, but you can create your own targets and map them to the following predefined actions:

  • run.single - Run selected file (Shift-F6)
  • debug.single - Debug selected file (Ctrl-Shift-F5)
  • test.single - Run the JUnit test for selected file (Ctrl-F6)
  • debug.test.single - Debug the JUnit test for selected file (Ctrl-Shift-F6)

Each of these actions contains a context element that gets a reference to the currently selected files and stores it in a property of your choice. You use this property in your Ant targets to specify which files to process.

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.

Profiling the Selected File

The process is basically the same for writing targets to debug and run a single file. The profile-selected-files target looks similar to the following:

    
<target name="-profile-check">
    <startprofiler freeform="true"/>
</target>
<!-- TODO: edit the following target according to your needs -->
<!-- (more info: https://netbeans.org/kb/articles/freeform-config.html#profile_sing) -->
<target depends="-profile-check" if="profiler.configured" name="profile-selected-file-in-src">
    <fail unless="profile.class">Must set property 'profile.class'</fail>
    <path id="cp">
        <pathelement location="build"/>
    </path>>
    <java classname="${profile.class}" fork="true">
        <classpath refid="cp"/>
        <jvmarg line="${agent.jvmargs}"/>
    </java>
</target>
  • This is basically the same as the profile target. Instead of passing the program main class to java you pass the profile.class property, which is set by the IDE to the currently selected file.

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

   <action name="profile.single">
      <target>profile-selected-files</target>
      <context>
         <property>profile.class</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 profile.class property.
  • Because java can only take a 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 need to define the property or import the .properties file that Ant is using in project.xml. See Using Properties in the project.xml File for more information.

Back to top

Writing a Target for the Apply Code Changes Command

The Apply Code Changes command allows you to make changes to your code during a debugging session and continue debugging with the changed code without restarting your program. The IDE contains a nbjpdareload task that you can use to write a target for the Apply Code Changes command.

A typical target for the fix command looks something like this:

  <target name="debug-fix">
    <javac srcdir="${src.dir}" destdir="${classes.dir}" debug="true" >
      <classpath refid="javac.classpath"/>
      <include name="${fix.file}.java"/>
    </javac>
    <nbjpdareload>
      <fileset dir="${classes.dir}">
        <include name="${fix.file}.class"/>
      </fileset>
    </nbjpdareload>
  </target>
  • The target compiles the currently selected file using the ${fix.file} property. (In the next section you will set up the IDE to store the name of the currently selected file in this property.)
  • The nbjpdareload task reloads the corrected file in the application.

To hook this target up to the Apply Code Changes command (the same as the Fix command in previous versions of the IDE), define the following action in <ide-actions> in project.xml:

  <action name="debug.fix">
    <target>debug-fix</target>
    <context>
      <property>fix.file</property>
      <folder>${src.dir}</folder>
      <pattern>\.java$</pattern>
      <format>relative-path-noext</format>
      <arity>
        <one-file-only/>
      </arity>
    </context>
  </action>
  • <property> now stores the context in the fix.file property.
  • Since you can only run the Fix command on one file at a time, you set <arity> to <one-file-only>.
  • You have to pass the full path to the .java file to the javac task and the full path to the .class file to the nbjpdareload task. You therefore set the <format> to rel-path-noext, then append .class or .java in the debug-fix target as necessary.

    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

Bookmark this page

del.icio.us furl slashdot technorati digg
get support for the NetBeans

Support


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2013, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo