9 Testing and Profiling Java Application Projects

9.2.1 Test Types in the IDE

You can use the IDE to create the following:

• Empty Tests. Test skeletons without testing methods, for which no class has been designated to be tested.

• Tests for Existing Classes. Classes containing the actual testing methods which mirror the structure of the sources being tested.

• Test Suites. Groups of test classes clustered to permit testing of an entire application or project.

You can generate tests and test suites by selecting any class or package node in the Projects window and choosing Tools > Create/Update Tests from the main menu.

9.2.2 Unit Test Structure

The IDE represents unit tests as subtrees which mirror the project's Java package structure. By default, when the IDE generates tests each test class has the name of the class it is testing appended by the word Test (for example, MyClassTest.java).

Each standard project has a default test folder that is used to store the unit tests and test suites. This folder is displayed as the Test Packages node in the Projects window. You can add any number of test folders to your project. Test files and the source files they test cannot be located in the same source tree.

9.3.1 Changing the JUnit Version

You can update support for the JUnit versions by updating the JUnit libraries in the project's Test Libraries node. View the project's JUnit libraries by expanding the project's Test Libraries node in the Projects window.

To add a new library, right-click the Test Libraries node in the Projects window and choose Add Library and select the library in the Add Library dialog box. To remove a library, right-click the library and choose Remove.

9.3.2 How to Create a Unit Test

Generated tests are distinguished by appending Test to the tested classes' names (for example, MyClassTest.java).

To create a test, the project must have a test directory for the tests. The IDE creates a Test Packages directory by default when you create a project. If no test directory exists in your project or you want to specify a different directory for your test, you can specify a test directory in the project properties dialog.

To create a test for a single class:

1. Right-click the class in the Projects window and choose Tools > Create/Update Tests (Ctrl+Shift+U) to open the Create Tests dialog box.

   You can modify the default name of the test class, but some of the navigation in the IDE between classes and test classes might not function if the name of the test class does not contain the name of the class that is tested.

2. Select a unit test framework.

3. Select the desired code generation options and click OK.

   Alternatively, you can create a test by choosing File > New File, selecting the Unit Tests category, and selecting JUnit Test or TestNG Test Case in the File Types pane.

To create a test suite:

1. Right-click the package node containing the source files for which you want to generate the test suite in the Projects window and choose Tools > Create Tests (Ctrl+Shift+U) from the context menu.

2. Select a unit test framework.

3. Select the Generate Test Suites checkbox.

4. Select the desired code generation options and click OK.

The IDE generates test classes for all enclosed classes and stores them in the project's Test Packages node. If any of the test classes already exist, those classes are updated. By default the IDE includes all the test classes as part of the generated test suite.

Alternatively, you can create a test suite by choosing File > New File, selecting the Unit Test category, and selecting Test Suite or TestNG Test Suite in the File Types pane.

To create an empty test:

1. Choose File > New File from the main menu.

2. In the New File wizard, select the Unit Test category and JUnit Test or TestNG Test Case in the File Types pane. Click Next.

3. Specify the test class name, folder and package.

4. Select the desired code generation options and click Finish.

When you create an empty test the IDE generates a test class that does not contain any skeleton methods. The IDE creates the test suite class based on the parameters you have specified and opens the class in the editor. The test suite class then appears in the Projects window under the package-name node in the test folder.

To create a new test for an existing class:

1. Choose File > New File from the main menu.

2. In the New File wizard, select the Unit Test category and Test for Existing Class in the File Types pane. Click Next.

3. Specify the test class name and folder.

4. Select the desired code generation options and click Finish.

When you create a test for an existing class, you specify the class that you want to test and the IDE generates a test class that contains skeleton methods based on the methods in the specified class. The IDE opens the class in the editor. The test class then appears in the Projects window in the test folder. The IDE creates the test class under the package-name node that replicates the package structure of the tested class.

To specify a test directory:

1. Right-click the project node in the Projects window and choose Properties.

2. In the Properties window, select Sources in the Categories pane.

3. Define the properties of the test packages folder in the Test Package Folders list.

   You can add or remove the folders that are used for test packages and modify the names of the test packages folder as it appears in the Projects window.

4. Click Close.

Your project must have a test package folder to generate unit tests. If the test packages folder for your project is missing or unavailable, create a new folder in your project and then designate the new folder as the test packages folder in the project's Properties window.

9.4.1 How to Run a Unit Test

You can run unit tests for a specific class or method or for a project.

To run tests for an entire project:

1. Select any node or file in the project you want to test in the Projects or Files window.

2. From the main menu, choose Run > Test Project project_name (Alt+F6).

   The IDE executes all of the project's tests.

If you want to run a subset of the project's tests or run the tests in a specific order, you can create test suites that specify the tests to run as part of that suite. After creating a test suite you run the suite in the same way you run a single test class.

You can select multiple projects in the Projects window and run tests for them at once by choosing Run > Test number_of_selected_projects Projects (Alt+F6) from the main IDE's menu. If you want to run a subset of the project's tests or run the tests in a specific order, you can create test suites that specify the tests to run as part of that suite. After creating a test suite you run the suite in the same way you run a single test class.

To run a test for a single class:

1. Select the node of the class for which you want to run a test in the Projects or Files window.

2. From the main menu, choose Run > Test File (CtrlF6).

You can also run a class's test by right-clicking the test class node itself in the Projects window and choosing Test File (Ctrl+F6).

To run a single test method:

1. Run the test class or suite containing the test method.

2. In the Test Results window, right-click the test method and choose Run Again.

To run a single test method the method must be listed in the Test Results window.

9.4.2 Working with Unit Test Output

When you run a test, the IDE shows the following test results in two panes in the Test Results window:

• A summary of the passed and failed tests and the description of failed tests are displayed in the left pane of the window. You can use the filter icons in the left side of the window to filter the test results.

• The textual output from the unit tests themselves is displayed in the right pane of the window.

The output from the process that builds and runs the test is displayed in the Output window. you can double-click any error to jump to the line in the code where the error occurred.

After you run a test class, you can right-click any test method displayed in the Test Results window and choose Run Again from the context menu to run the individual test method again or Debug to debug the test.

9.6.1 How to Edit Unit Test Settings

Modify the test settings to create a custom tests.

To edit unit test settings as you create tests:

1. Right-click the sources for which you wish to create tests.

2. Choose Tools > Create Tests (Ctrl+Shift+U).

3. Select a unit test framework.

4. In the Create Tests dialog box, select the Code Generation options you require for the tests.

The IDE creates the tests with the specified options.

9.6.2 How to Edit the Classpath for Compiling or Running Tests

Edit the classpath as needed to include specific projects, libraries, or JAR files.

To edit the classpath for compiling or running tests:

1. Right-click the project's Test Libraries node and choose one of the following:

   • Add Project. The build output, source files, and Javadoc files of another IDE project.

   • Add Library. A collection of binary files, source files, and Javadoc files.

   • Add JAR/Folder. A JAR file or folder somewhere on your system.

2. Click OK.

The IDE adjusts and stores the classpath priorities based on the new settings. For information on setting the classpath for a project, see Section 6.2.3.1, "Managing the Classpath."

9.9.1 How to Profile a Project

To profile an individual project:

1. Right-click a project in the Projects window and choose Profile.

   Alternatively, you can select a project in the Projects window and choose Profile > Profile Project from the main menu.

2. On the main window click the Configure Session button and select a profiler mode by clicking on it. You can change the profiler mode at any point by clicking the Profile drop-down arrow.

3. On the main window, click the Profile button. The application and the profiling session are started.

If a project is set as the main project, the Profile Project command in the Profile menu always profiles the main project.

To profile a specific class:

1. In the Projects window, select the class that you want to profile. (This class must contain a runnable method.)

2. Choose Profile > Profile File from the main menu.

3. On the main window, click the Profile button. The profiling session is started.

For information on profiling an application that you started outside the IDE, see Section 9.11, "Attaching the Profiler."

For information on monitoring an application thread activity, see Section 9.20, "Profiling Threads". For information on examining CPU performance and memory usage, see Section 9.17, "Profiling Telemetry".

9.9.2 How to Calibrate the Profiler

You must calibrate the IDE before you can use the IDE to profile an application. You must run the calibration process for each JDK that you use for profiling. You do this because instrumenting the bytecode of the application imposes some overhead, and the time spent in code instrumentation needs to be "factored out" to achieve more accurate results.

You only have to calibrate the IDE once for each JDK that you use. However, you should run the calibration process again when anything changes on your local or remote configuration that could affect system performance. The following could affect system performance:

• Any hardware upgrade

• Any significant change or upgrade of the operating system

• An upgrade of the Java platform used for profiling

To calibrate the IDE to the local system:

1. Close any other programs that are running.

   The IDE runs the calibration if other applications are running, but running any CPU-intensive programs when performing the calibration might affect the accuracy of profiling results.

2. Go to Tools > Options > Java > Profiler.

3. Select the General category and click Manage in the Profiling specific options. The Manage Calibration Data dialog box displays.

4. Select the Java Platform to be used for profiling. Click Calibrate.

   You can click Java Platforms to open the Java Platform Manager to add a new Java platform. The Manage Calibration Data dialog box displays the date that the most recent calibration was performed.

When you click Calibrate, the IDE collects calibration data on the selected Java platform. When the calibration process is complete you can start using the IDE to profile your applications.

Do not share calibration data between various computers or systems.

You cannot perform a calibration of a remote platform from the Manage Calibration Data dialog box. Calibration of a remote platform is performed the first time that you profile an application on the remote platform.

To calibrate the IDE to a remote system:

• To calibrate the IDE to a remote system, see the NetBeans FAQ at http://wiki.netbeans.org/wiki/view/FaqProfilerCalibration.

9.9.3 Understanding the Toolbar Icons

Table 9-2 contains the various icons used when profiling. These icons are available from areas in the NetBeans user interface, including Profile window with Methods, Profile window with Threads, Profile window with Objects, Profile window with Telemetry, and Profile window with Locks.

9.10.1 How to Select a Profiling Task

Each time you start or modify a profiling session, you first select a profiling task. You cannot run more than one profiling session at one time. You can profile a project or an individual file if the file has a runnable method. You can also profile test classes.

To select a profiling task:

1. Select a project or file in the Projects window and choose Profile > Profile Project from the main menu.

   Alternatively, you can right-click a project node in the Projects window and choose Profile, or right-click a file and choose Profile File or Profile Test File.

2. (Required when you run a profiling session for the first time only.) Select a profiling task by clicking one of the tasks in the Configure Section drop-down list.

3. Click Profile.

9.10.2 Using a Load Generator Script

The IDE supports using a load generator to replay previously saved load testing scripts. By using a load testing script, you can simulate a heavy load on your server or application to achieve more accurate results when testing application performance.

The IDE supports the Apache JMeter load testing tool. To work with the Apache JMeter load testing tool in the IDE, use the Plugins manager download and install the JMeter plugin from the Update Center by choosing Tools > Plugins from the main menu. This plugin installs additional Load Generator and Profiler/Load Generator Bridge plugins. A sample JMeter script is downloaded as a part of the JMeter plugin. The sample script is available in userdir/modules/jmeter/extras/Test.jmx.

Once you install the JMeter integration, a new Plugins section with a Load Generator item appears in the Profile or Attach drop-down menu. Choose Load Generator to start a JMeter script when starting the profiling session.

To create a new load testing script:

1. Choose File > New File from the main menu.

2. Select Load Testing Scripts > JMeter Plans in the Categories list and New JMeter Plan in the New File dialog and click Next.

3. In the Name and Location panel of the dialog specify the name of the new test jmx file and its location. Click Finish.

For more about using Apache JMeter, see http://jakarta.apache.org/jmeter/index.html.

9.11.1 How to Configure the Attach Settings

Before you can attach to an application, the startup options for the target application or server must be configured. You use the Attach Settings dialog box to specify the attachment settings for a project. You only have to configure the attachment settings once. The attachment settings are project specific, which means that each project has its own settings. You can open the Attach Settings dialog box at any time if you want to review or modify any of the attachment settings.

To configure the attach settings:

1. Choose Profile > Attach to Project or Profile > Attach to External Process ( ) from the main menu to open the Profile window.

2. Click the Attach button to display the Attach Settings dialog box and make the appropriate selections.

   Based on the attach mode you choose in the Profile drop-down list, the Attach Settings dialog box provides you with a set of instructions on how to configure the application so that you can attach the profiler.

3. Click OK.

The attach mode you choose depends on the type of profiling data you want to obtain and the details of the target JVM platform. Table 9-4 provides an overview of the attach modes:

To profile an applet using the Local Direct or Remote attach mode:

• Specify the agent parameters in the Java Control Panel and restart the browser.

9.11.2 How to Attach the Profiler to a Local Application

Use the attach mode to profile a local application when you must start the application outside of the IDE. For example, you may want to use the attach mode in the following cases:

• Your application needs to be started from the command line or uses a complex launch script.

• You want to obtain profiling data on the startup of the application or target JVM.

• You want to profile the application without restarting the application (Already running local Java process attach mode, requires JDK 1.6, 1.7, or 1.8).

To attach to a local application, you must first configure the attachment settings using the Attach Settings dialog box. These settings are associated with the project you are profiling. You only have to configure the attach settings for your project once, but you can modify the settings at any time in the Attach Settings dialog box.

When you configure the settings for attaching to a local application, you can choose from the following attachment modes:

• Already running local Java process. This mode allows you to detach from and attach to the application at any time without stopping the application. This mode requires JDK 1.6, 1.7, or 1.8 but does not require any additional configuration.

• Manually started local Java process. This mode enables you to obtain profiling data on the startup of the local application. This mode requires you to modify the startup script and start the application when you want to attach the profiler.

Once the connection is established and the profiler is attached to the target application, you can change the profiling task you are running on the target application without stopping or restarting the application.

To attach to a local application:

1. Choose Profile > Attach to Project ( ) from the main menu to open the Profile window.

2. Click the Attach button to open the Attach Settings dialog box.

3. Select either Already running local Java process or Manually started local Java process as the attach mode.

4. Follow the instructions in the Attach Settings dialog box for configuring the application, if necessary. Click OK.

   A profiling session tracking the running application is started.

To finish profiler session:

• Choose Profile > Finish Profiler Session from the main menu or click the Finish profiler button in the Profiler window.

When you finish profiler session, the connection to the target JVM is closed. You can re-attach to the application by choosing Profile > Attach to Project from the main menu.

To change the profiling task without finishing profiler session:

Click the Attach drop-down arrow to change the profiling mode at any point.

The target application is instrumented again without starting or stopping the application.

9.12.1 How to Attach to a Remote Application

To attach the profiler to a remote application you must configure the application to load some profiler libraries on startup to enable the profiling tool to attach to the application. You use the Attach Settings dialog box to specify the details of the remote system and to generate a Remote Profiler Pack archive that contains the necessary profiler libraries. You must copy the contents of the Remote Profiler Pack archive to the remote system and then configure the remote application to load the profiler libraries.

After you configure the remote application according to the instructions, you can start the remote application and attach the profiler. You only have to configure the attach mode once. The attachment settings are associated with that project. You can open the Attach Settings dialog box at any time to change the attachment settings.

To attach to a remote application:

1. Choose Profile > Attach to External Project from the main menu. The Profile External Process window displays.

2. Select the Configure Session button and select Setup Attach to Process. The Attach Settings dialog box displays.

3. Set the profiler mode to Manually started remote Java process in the Profile drop-down list.

4. Specify the Hostname and select the OS and JVM from the drop-down list.

5. Follow the detailed instructions in the Attach Settings dialog to start profiling.

6. Click OK.

After the IDE is attached to the remote application you can do the following:

• Detach from the remote application.

  When you detach from the remote application, the remote application does not stop but you stop receiving profiling data about the remote application. To attach to the remote application, use the startup options provided by the Attach Settings dialog box and start the remote application again.

• Modify the profiling session.

  You can modify the profiling session without detaching from the remote application. For example, you can change the profiling task to monitoring to reduce the profiling overhead, and then modify the task again later. This way you do not have to re-attach and restart the remote application.

9.12.2 Attaching to a Remote Server

Similar to attaching the profiler to a remote application, you must copy the profiler libraries in the Remote Profiler Pack to the remote system to attach the profiling tool to a remote server. You must also modify the server configuration files to specify the path to the JDK and to specify the path to the profiler agent. When you start the server using the modified startup script, the server waits until the profiler attaches to the server.

You can retrieve the path to the profiler agent when you use the Attach Settings dialog box to configure your attach settings. The path to the profiler agent is similar to the following path.

-agentpath:<remote>\lib\deployed\jdk16\windows\profilerinterface.dll=\lib,5140

The placeholder <remote> refers to the full path to the root directory containing the profiler libraries that you copied to the remote system. The number 5140 is the Communication Port that the profiling tool uses to connect to the application. Modify the port number in the Profiler tab in the Java category in the Options window.

Table 9-5 identifies the startup scripts and the parameters that must be modified to specify the paths to the JDK and the profiler libraries:

For the GlassFish server, set the path to the JDK in the asenv.bat/asenv.conf file and the path to the profiler agent in domain.xml.

For more details about configuring the servers for attaching the profiler tool, see the following NetBeans FAQ: http://wiki.netbeans.org/wiki/view/FaqProfilerAttachRemoteServer

For more details about modifying server startup scripts, consult the documentation for the server.

9.13.1 Profiling Free-form Web Projects

Typically the server is started using a startup script, not the java command directly. Therefore you cannot use the <jvmarg .../> element to pass additional argument to it. Instead, you have to modify the server startup script to configure it for profiling.

The recommended approach is to create a new script for starting the server for profiling and use it in the profile target. The Attach Settings dialog box can provide steps to help you modify the startup script. If your target server does not support automatic integration, you can create the script by following the integration steps described in the Attach Settings dialog box. You always have to set up the integration for Local Direct attach.

The other steps for profiling a free-form web project are the same as those above for profiling a standard J2SE projects.

<?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>

<?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>

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

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

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

9.14.1 Taking Snapshots During a Profiling Session

You may take a snapshot of the profiling data at any time during the profiling session by clicking the Snapshot icon shown in the figure below.

To control how the snapshots functionality behaves during a session, go to Tools > Options > Java > Snapshots > Profiler and click the When taking snapshots drop-down menu to see the following options:

Open Snapshot—it opens the snapshot right after clicking the Snapshot icon

Save Snapshot—it saves a new snapshot every time you click the Snapshot Icon

Save and open snapshot—it saves and opens a snapshot right after clicking the Snapshot icon.

You may take multiple snapshots during a profiling session and you will also be prompted to save a "final" snapshot at the end of the session.

You can only take a snapshot while a profiling session is in progress. You can take a snapshot manually or set a profiling point to take a snapshot automatically at a precise point in your application. When you use a profiling point to take a snapshot, you locate the point in your source code where you want to take a snapshot. For example, you may want to take a snapshot when a thread enters a specific method.

Perform the following steps to take a snapshot manually:

1. Start a profiling session.

   For information, see Section 9.9, "Starting a Profiling Session."

2. Do one of the following:

   • Click the Take Snapshot of Collected Results button in the Profiler window.

   • Select Profile > Take Snapshot of Collected Results from the main menu.

When you take a snapshot, the snapshot opens in the main editor window. You can then save the snapshot to your project.

To take a snapshot using a profiling point:

1. Open the source file containing the code where you want to place the profiling point.

2. Right-click in the line of code and choose Profile > Insert Profiling Point.

3. Select one of the snapshot options in the New Profiling Point wizard and click Next.

4. Modify any of the profiling point properties in the Customize Properties page of the wizard. Click Finish.

If you use a profiling point to take a snapshot, you can choose from the following snapshot options:

• Load Generator. Choose this if you want the IDE to take a snapshot to start and stop a load generator script at the given source code location.

• Reset Results. Choose this if you want the IDE to take a snapshot to reset currently collected profiling results.

• Stopwatch. Choose this if you want the IDE to take a snapshot to measure time between start and stop locations to obtain the execution time of a method fragment.

• Take Snapshot. Choose this if you want the IDE to take a snapshot when an application thread enters or leaves the specified line of code.

• Timed Take Snapshot. Choose this if you want the IDE to take a snapshot at a specific time and date. You can also configure the IDE to take snapshots at a specified interval.

• Triggered Take Snapshot. Choose this if you want the IDE to take a snapshot when the specified condition is met. You specify the condition by choosing one of the available triggers.

For each snapshot option you can choose to save the snapshot to your project or you can specify a location.

To save a snapshot;

• Click Save Snapshot to Project in the snapshot toolbar.

  You can also use the Options window to configure the IDE behavior when taking a snapshot.

You can save a snapshot to your project or you can save the snapshot to a location on your local file system. When you save a snapshot to your project, the snapshot is listed under Snapshots in the Snapshots window.

To distinguish a snapshot from other profiling snapshots you have taken of the project, you can rename it. Select a snapshot in the Snapshots section of the Snapshots window and click Rename selected snapshot to open the Rename Snapshot dialog box and enter a new name.

9.14.2 Taking Snapshots at the End of a Profiling Session

When closing a profiled application, or if it finishes on its own, while the profiling session is in progress, the profiler asks you whether to take a snapshot of the results collected so far by displaying the Application Finished dialog.

Click Yes to save the snapshot.

9.14.3 Starting and Stopping the Application Finished Dialog

When the Application Finished dialog appears at the end of the profiling session, if you select the Do not show this message again checkbox the dialog would not display again. If at a later time you want to reactivate the display of this dialog, go to Tools Options > Java > Snapshots > Profiler > General > Miscellaneous and click the Reset button.

9.14.4 Accessing Snapshots

You may access you profiling session snapshots by going to Window > Profiling > Snapshots. The Snapshots window appears.

At the bottom of the Snapshots window there are icons that allow you to export, open, rename, and delete selected snapshots.

9.15.1 How to Take a Heap Dump

You can take a heap dump manually or set a profiling point to take a heap dump automatically at a certain point in your application. In the Options window, you can also set the IDE to automatically take a heap dump on OutOfMemory error.

To take a heap dump manually:

1. Start a profiling session.

2. Choose Profile > Take Heap Dump in the main menu.

When you take the heap dump, you are prompted to specify where you want to save the heap dump. You can save the heap dump snapshot to your project or to any location on your local file system.

To take a heap dump using a profiling point:

1. Open the source file containing the code where you want to place the profiling point.

2. Right-click in the line of code where you want to place the profiling point and choose Profile > Insert Profiling Point.

3. In the New Profiling Point wizard, select one of the following snapshot options and click Next.

   • Take Snapshot

   • Timed Take Snapshot

   • Triggered Take Snapshot

4. In the Customize Properties page of the wizard, select Heap Dump as the type of snapshot and modify any additional settings. Click Finish.

When you use a profiling point to take a heap dump, you specify the point in your source code where you want to place the profiling point. For example, you may want to take a heap dump when a thread enters a specific method.

To take a heap dump on OutOfMemory error:

1. Choose Tools > Options from the main menu, click the Java category and then click the Profiler tab.

2. Choose the Snapshots category.

3. In the On OutOfMemoryError list, select an option from the drop-down list to specify what the IDE does when an OutOfMemoryError is encountered.

   The default behavior is to save the heap dump to the profiled project.

9.15.2 How to Analyze a Heap Dump Using Object Query Language (OQL)

OQL is a SQL-like query language to query a Java heap that enables you to filter/select information wanted from the Java heap. While pre-defined queries such as "show all instances of class X" are already supported by the tool, OQL adds more flexibility. OQL is based on JavaScript expression language.

When you load a Java heap in the Heap window, you can click the OQL Console tab of the window to open the OQL editor. The OQL Console contains an OQL editor, a saved OQL queries window and a window that displays the query results. You can use any of the sample OQL queries or create a query to filter and select heap data to locate the information that you want from the Java heap. After you choose or write a query, you can run the query against the Java heap and view the results.

An OQL query is of the following form:

select <JavaScript expression to select>
[ from [instanceof] <class name> <identifier>
[ where <JavaScript boolean expression to filter> ] ]

where class name is fully qualified Java class name (example: java.net.URL) or array class name. char[] (or [C) is char array name, java.io.File (or [Ljava.io.File;) is name of java.io.File[] and so on. Note that fully qualified class name does not always uniquely identify a Java class at runtime. There may be more than one Java class with the same name but loaded by different loaders. So, class name is permitted to be id string of the class object. If instanceof keyword is used, subtype objects are selected. If this keyword is not specified, only the instances of exact class specified are selected. Both from and where clauses are optional.

In select and (optional) where clauses, the expression used in JavaScript expression. Java heap objects are wrapped as convenient script objects so that fields may be accessed in natural syntax. For example, Java fields can be accessed with obj.field_name syntax and array elements can be accessed with array[index] syntax. Each Java object selected is bound to a JavaScript variable of the identifier name specified in from clause.

select s from java.lang.String s where s.count >= 100

select a from int[] a where a.length >= 256

select {instance: s, content: s.toString()} from java.lang.String s
    where /java/(s.toString())

select file.path.toString() from java.io.File file

select classof(cl).name 
    from instanceof java.lang.ClassLoader cl

select o from instanceof 0xd404b198 o

select { name: t.name? t.name.toString() : "null", thread: t } 
from instanceof java.lang.Thread t

select map(sort(map(heap.objects('java.lang.ClassLoader'), 
'{ loader: it, count: it.classes.elementCount }'), 'lhs.count < rhs.count'),
'toHtml(it) + "<br>"')

select map(heap.objects('java.lang.ClassLoader'),
      function (it) {
         var res = '';
         while (it != null) {
            res += toHtml(it) + "->";
            it = it.parent;
         }
         res += "null";
         return res + "<br>";
      })

select map(filter(heap.findClass('java.lang.System').props.table, 'it != null && it.key != null && it.value != null'),
            function (it) {
                var res = it.key.toString() + ' = ' + it.value.toString();
                return res;
            });

9.16.1 How to Set Profiling Points

Once you set a profiling point it becomes part of the project until you delete it. You can view, modify and delete the Profiling Points in your projects in the Profiling Points window. The Profiling Points window displays all profiling points in open projects. You can select a profiling point and then use the toolbar to edit, remove, enable and disable the profiling point.

To open the New Profiling Points window:

• Choose Profile > Insert Profiling Points in the main menu

To set a profiling point:

1. Locate the class where you want to add the profiling point and open the class in the Source Editor.

2. In the Source Editor, right-click in the line where you want to add the profiling point and choose Profiling > Insert Profiling Point to open the New Profiling Point wizard.

3. Select a profiling point type and the project and click Next.

4. Customize the properties of the profiling point, if necessary and click Finish.

When you click Finish, an icon representing the profiling point type appears in the sidebar of the Source Editor next to the line where you inserted the profiling point.

To enable and disable a profiling point:

1. Locate the class containing the profiling point and open the class in the Source Editor.

2. In the Source Editor, right-click in the left margin of the line containing the profiling point and choose Profiling Point > Disabled or Enabled.

To enable, disable, or customize the settings of a profiling point:

• Choose Window > Profiling > Profiling Points.

To view details about a profiling point:

You can view information about a profiling point in the Profiling Points Report window. The information displayed is dependent on the profiling point type. Right-click a profiling point in the Profiling Points window and choose Show Report in the context menu to open this window.

9.16.2 How to Reset Profiling Results

You can use a profiling point to reset the collected profiling results each time that a thread in the application hits the profiling point. You can then use this profiling point to gather results deltas when combined with the Take Snapshot profiling point.

To reset a profiling point:

1. Click Add Profiling Point or Edit Profiling Point in the Profiling Points window.

2. Select the Reset Results profiling point type and select the desired project.

3. Click Next.

4. Specify a name that identifies that profiling point.

5. Specify the line number containing the profiling point and whether the profiling point is hit when a thread hits the beginning or end of that line (the file name is automatically filled in).

6. Click Finish.

9.16.3 How to Set a Stopwatch Profiling Point

You can obtain a timestamp each time that a profiling point is hit instead of calling the System.currentTimeMillis() method. Setting a Stopwatch profiling point lets you measure the time between the start and stop locations to obtain the execution time of a method fragment.

To set a Stopwatch profiling point:

1. Choose Window > Profiling > Profiling Points.

2. Click Add Profiling Point in the Profiling Points window.

3. Select the Stopwatch profiling point type and select the desired project.

4. Click Next.

5. Specify a name that identifies that profiling point.

6. Select whether you want to obtain a timestamp or a timestamp and the execution duration.

7. Specify the file in which to set the profiling point.

8. Specify the line number containing the profiling point at which point time measurement begins (the file name is automatically filled in).

9. If you selected Timestamp and duration, specify the line at which to stop the measurement (the file name is automatically filled in).

10. Click Finish.

9.18.1 Basic Methods Profiling Mode

The methods mode is designed to provide profiling data from all classes and methods without any initial setup. The methods mode provides metrics for methods and classes. The methods report allows you to view the data by Forward Calls, Hot Spots, and Reverse Calls by clicking on the appropriate icons.

Table 9-6 lists three different views on the methods data collected by the profiler.

You may also choose to Show Delta Values and Select Threads.

• Show Delta Values. Switches from absolute values to incremental values. The values displayed prior to switching the view are remembered but the new view displays changes starting at the moment the new selection was made. Clicking this icon again resets the results back to absolute values.

• Select Threads. Shows threads available in live results or a saved snapshot and allows you to select specific threads for displaying results. This feature is useful when tracking EDT slowness in desktop applications or analyzing worker threads in server applications. This feature merges results from the selected threads to a single tree.

Additionally, you may select the columns to be displayed; the options are Total Time, Total Time (CPU), Selected, and Hits/Invocations (depending on the session configuration).

9.18.2 Advanced Methods Profiling Mode

To change the profiling modes and settings in the Settings pane, press the Settings switch in the Profiler window toolbar.

Table 9-7 lists the profiling modes the profiler offers with different profiling techniques and settings.

For more information on profiling methods in NetBeans IDE, see http://wiki.netbeans.org/ProfilerMethods.

9.18.3 Selecting Classes And Methods For Profiling

Selected classes or methods instruct the profiler from where to start collecting the profiling data. Once a JVM executes a selected method or the method of a selected class, the profiler starts collecting data of this method and all methods called by this method, transitively.

A class or method for instrumented profiling can be selected via:

• Select Class or Select Method dialog. Allows to select one or several classes or methods from a project or .class/.jar file. Can be opened directly from the Methods Settings pane.

• Code editor context menu. Provides Profile | Profile Class and Profile | Profile Method actions.

• Navigator context menu. Provides Profile | Profile Class and Profile | Profile Method actions.

• Profiling results. Live or saved Methods results provide Profile Class and Profile Method actions in the context menu. The Selected column is available to select methods for profiling. The column can be displayed using the right corner button in the view header by clicking the drop-down arrow (or right clicking the header on Mac OS X).

For more information on profiling methods in NetBeans IDE, see http://wiki.netbeans.org/ProfilerMethods.

9.18.4 Configuring Additional Options

Additional options define where to stop collecting the profiling data in order to lower the overhead and keep the profiling data clear and focused.

By default the profiler offers a limited subset of customizable options for an instrumented profiling session.

To enable the expert mode:

1. Choose Tools > Options > Java > Profiler > General from the main menu.

2. Select the Enable manual setup for Methods and Objects (expert users) checkbox.

For more information on the expert mode of profiling methods in NetBeans IDE, see http://wiki.netbeans.org/ProfilerExpertFeatures.

9.19.1 Basic Profiling

The Objects mode provides profiling data from all classes without any initial setup. Click the Profile or Attach button in the toolbar to start a profiling session.

9.19.2 Advanced Profiling

To cover various use cases of objects profiling the profiler offers three profiling modes with different profiling techniques and settings. The modes and settings can be changed in the Settings pane which is displayed by pressing the Settings switch in Profiler window toolbar.