13 Optimizing Java Projects

JDeveloper provides numerous features for optimizing, auditing, profiling, and unit testing Java projects.

Optimizing finds defects that make code difficult to improve and maintain. The JDeveloper optimizing tools help you find and fix defects so that Java programs run faster, are smaller in size, and easier to maintain.

JDeveloper's auditing tools help you find and fix such defects. Auditing is concerned with programming standards, rather than syntactic correctness. You can audit code even when it is not compilable or executable.

The profiler gathers statistics on your program that enable you to diagnose performance issues. It monitors and logs a running program's use of processor and memory resources. It also gathers statistics that enables you to more easily diagnose the performance issues and correct the inefficiencies in your code.

To test your application, JDeveloper provides JUnit wizards, accessible from the New Gallery, to create test fixtures, cases, and suites. Automated testing tools such as JUnit make it easier to perform regular, reliable unit testing. JUnit is an optional feature that can be installed and integrated with JDeveloper.

This chapter includes the following sections:

Section 13.1, "About Optimizing Java Projects"
Section 13.2, "Understanding Auditing"
Section 13.3, "Profiling a Project"
Section 13.4, "Unit Testing with JUnit"

13.1 About Optimizing Java Projects

JDeveloper provides a suite of tools for analyzing the quality and performance of your Java code. Use these tools to improve both the quality of your code and your own programming skills.You can use JDeveloper's Auditing feature to analyze Java code for conformance to programming standards.

Before optimizing, consider whether you need to optimize at all.

13.2 Understanding Auditing

Auditing is the static analysis of code for adherence to rules and metrics that define programming standards. A software code audit is a comprehensive analysis of source code in a programming project with the intent of discovering bugs, security breaches or violations of programming conventions.

A rule is a qualitative test for the presence or absence of some feature. For example, common Java coding style requires that class names be capitalized. A violation occurs when a rule is not adhered to.
A metric is a quantitative measurement of size or complexity. For example, a method that is too long, or covers too many cases should delegate some of its functionality to other methods. An over-threshold anomaly occurs when the specified upper bound is exceeded.

You can create and customize profiles, choose the rules to be used, and set parameters for individual rules. Browse the audit rules and metrics to learn more about them.

JDeveloper's audit and metrics features are extensible. Audit and metrics are two facets of a source code analysis and transformation framework that can be customized and extended. The public API for both audit and metrics is the oracle.jdeveloper.audit package.

To audit Java code:

Run the auditor on source files to produce an audit report. For more information, see Section 13.2.12, "How to Run Audit to Generate an Audit Report."
Use Code Assist to audit while editing. Code Assist enables background audits while you edit. Audit violations are highlighted as you edit. You can apply automated corrections.
Audit from the command line to produce an audit report. For more information, see Section 13.2.8, "Auditing Java Code from the Command Line."
Display the Issues window. The Issues Window is one of the JDeveloper features that helps you to audit your code. It displays audit violations in the document selected in the File List and provides information to help you resolve the issues.

An audit report displays rule violations and measurements organized as a tree. A row of the tree corresponds to either a construct or a violation, and includes any measured values for the construct or theoretical violation. A construct is a method, class, file, project, or workspace.

13.2.1 Understanding Audit Rules

Audit rules are static, qualitative, analyses of code.

In an auditing profile, individual rules can be enabled and configured by setting their properties. When a code construct does not satisfy a rule, a rule violation is reported. Some rules define automatic fixes that you can choose to apply.

The rules contain the properties shown in Table 13-1.

Table 13-1 Rule Properties

Property	Description
Default fix	The fix that will be used for violations of this rule are when Apply Default Fix is applied to a construct.
Pattern	A regular expression used as a filter to find unconventional identifiers.
Severity	Use to sort rule violations in the audit report.
Visibility	A threshold based on the accessibility keyword. Violations will be reported only if they occur in classes or methods having at least the chosen visibility.

13.2.2 Understanding Audit Metrics

Audit metrics are static, quantitative analyses of code.

In an auditing profile, individual metrics can be enabled and configured. Metrics are configured by setting a threshold: when a code construct exceeds the threshold, an over-threshold measurement is reported in the audit report.

JDeveloper measures the metrics shown in Table 13-2.

Table 13-2 Audit Metrics

Metric	Description
Depth of Inheritance Tree (DIT)	The depth of the inheritance tree of a class. By convention, j`ava.lang.Object` has DIT of 1, a class which directly extends j`ava.lang.Object` has DIT 2, and so on.
Number of Statements (NOS)	The size, in Java statements, of a method, class, or other construct.
Cyclomatic complexity (V(G))	The branching complexity of a method. Constructs which enclose methods, such as classes and projects, are assigned the maximum complexity measured for an enclosed method. Values above 10 are generally considered problematic.

13.2.3 Using the Auditing Tools

You can use auditing tools to view audit reports and to investigate and correct rule violations and over-threshold measurements. A new tab will be created in the Log window when auditing starts, and the audit report will be displayed in it.

Auditing is the static analysis of code for adherence to rules and metrics that define programming standards. Auditing finds defects that make code difficult to improve and maintain. The JDeveloper auditing tools help you find and fix such defects. Code can be audited even when it is not compilable or executable.

13.2.4 Using the Audit Window Report Panel

An audit report is a set of rule violations and metrics measurements presented as a tree organized into constructs. A construct is a method, class, package, file, project, or workspace. If the audit profile includes rules, the table will have a Severity column that shows the designated severity of the constructs. If the audit profile includes metrics, the table will have an additional column for each metric showing the measurements for the constructs.

To sort the report by the contents of a column, click the column header. To reverse the sort order, click again.

13.2.5 Using the Audit Window Toolbar

From the Log window toolbar you can perform the operations shown in Table 13-3.

Table 13-3 Audit Window Toolbar Icons

Icon	Name	Description
	Refresh	Click to rerun the audit on the same selection with the same profile.
	Cancel	Click to terminate a running audit. Note that this may give partial results.
	Export	Click to open the Export Results Dialog, from which you can save the report to a file. You may save the results in XML, HTML, or plain text.
	Expand All	Click to expand all the container nodes in the report, exposing all the rows.
	Collapse All	Click to collapse all the container nodes in the report, hiding all but the top-level constructs.
	Group Constructs By	Click to open the Group By dialog, from which you can specify the types of container constructs that will be shown. Grouping by constructs enables you to organize the results better, track defects and violations quickly, and analyze the results easily.
	Fix	Choose a fix for a rule violation from the dropdown menu. For an individual rule violation, choose among the fixes defined for that violation's type. For a group construct, the only choice is Apply Default Fixes, which applies the default fix defined for its type, if any.
	Show Over Threshold Only	Toggle the display of measurements that are within acceptable limits. The threshold is a settable property of metrics.

13.2.6 Using the Audit Window Context Menu

Select one or more constructs (container nodes) or rule violations (leaf nodes) and right-click to open the context menu. From the context menu you can perform the operations shown in Table 13-4 on the selected constructs or rule violations.

Table 13-4 Audit Window Context Menu Items

Name	Description
Apply Default Fixes	Choose to apply the default fix, if any, to each selected rule violation or to all the violations in the selected constructs. You can define the default fixes using the Tools > Preferences > Audit: Profiles page.
Apply <Fix>	Choose to apply this fix to the selected rule violation in the construct.
About <Rule>	Choose to display an explanation of the rule that applies to this rule violation.
Hide <Rule> Violations	Choose to remove all violations of the selected rule from the report.
Show Hidden Violations	Choose to restore all previously hidden violations.
Show Over Threshold Only	Click to toggle the display of measurements that are within acceptable limits.
Cancel	Choose to terminate a running audit.
Refresh	Choose to rerun the audit.
Group By	Choose to open the Group By dialog, from which you can specify the types of container constructs that will be shown.
Expand All	Click to expand all the container nodes in the report, exposing all the rows.
Collapse All	Click to collapse all the container nodes in the report, hiding all but the top-level constructs.
Go to Source	Choose to open the source file at the point of the rule violation. If you wish, you can edit the file and correct the violation.
Export	Choose to open the Export Results Dialog, from which you can save the report to a file.

13.2.7 How to Audit Java Code in JDeveloper

JDeveloper's auditing tools help you find and fix defects that make code difficult to improve and maintain. You can audit code even when it is not compilable or executable. The focus of an audit is defined by a profile, which is a set of audit rules and metrics.

To audit Java Code:

Create an Audit Profile that specifies the rules, code assists, and metrics used to analyze Java programs. In an Audit Profile, individual rules and metrics can be enabled and configured by setting their properties. When a code construct does not satisfy a rule, a rule violation is reported. For more information, see Section 13.2.9, "How to Create an Audit Profile."
Run the Audit Report.
- From the main menu, choose Build Audit.... For more information, see Section 13.2.12, "How to Run Audit to Generate an Audit Report."
- You can also audit Java code from the command line by invoking ojaudit.exe, which is included in your JDeveloper installation. For more information, see Section 13.2.8, "Auditing Java Code from the Command Line."
Inspect the completed Audit Report for rule violation. For more information, see Section 13.2.20, "How to Inspect an Audit Report Violation or Measurement."

An Audit Report displays rule violations and measurements organized as a tree. A row of the tree corresponds to either a construct or a violation, and includes any measured values for the construct or theoretical violation. A construct is a method, class, file, project, or workspace.
Fix an audit rule violation manually by editing the source, or for some rules, by selecting an automated fix. For more information, see Section 13.2.21, "How to Fix an Audit Rule Violation.".
If you want to run the audit again, you can modify an audit profile by enabling or disabling rules, code assists, and metrics, or by changing their configuration. For more information, see Section 13.2.9, "How to Create an Audit Profile."

You can save the finished audit report as an XML file or as a formatted HTML or text file. For more information, see Section 13.2.19, "How to Save an Audit Report." Formats are defined by XSL stylesheet files in the /jdev//audit/stylesheets directory (this directory is not created until audit is run). To create a custom format, adapt a copy of one of the predefined stylesheet files, and add it to the directory.

13.2.8 Auditing Java Code from the Command Line

You can audit a workspace, a project, or a source file from the command line by invoking ojaudit.exe, which is included in your JDeveloper installation, in the <jdev_install>/jdeveloper/jdev/bin directory.

Synopsis

ojaudit option... file...

Table 13-5 contains the parameters you can use during the audit.

Table 13-5 Command Line Parameters

Parameter	Description
`file`	The workspace (`.jws`), project (`.jpr`), or source (`.java`) file to be audited.
-`classpath` `path`	Set class path for files to audit, if a project is not being audited.
`-encoding` `code`	The character encoding for the report. If absent, the character encoding specified for the project is used (see the Compiler page of the project's Project Properties dialog).
`-disable` `rule`	Disable rule in profile. To supply multiple values, repeat this option.
`-enable` `rule`	Enable rule in profile. To supply multiple values, repeat this option.
`-fail` `severity`	Set the issue severity that the Auditor will regard as failure.
`-f[ix]`	Applies default fixes to the code. This option modifies source files.
`-h[elp]`	Prints help for the command help and exits.
`-o[utput]` `file`	The pathname of the output file. If omitted, output is written to standard output.
`-p[rofile]` `name`	(required) The profile to use. It is either one of the profiles defined in JDeveloper (as set in the Audit > Audit Profiles page of the Tools > Preferences dialog), or the path name of an exported Audit profile file. Case and whitespace are ignored when searching for a matching profile.
`-profilehelp`	Print defined profile names and exit.
-`project file`	The project context to use for parameters that are source files. If all parameters are projects or workspaces, this option is not required.
-`q[uiet]`	Suppresses the copyright message.
`-sourcepath` `path`	Set source path for files to audit, if a project is not being audited
`-s[tyle]` `file`	The XSLT stylesheet to apply to the report. The name can either be a style sheet defined in JDeveloper, or a pathname to a style sheet file. If absent, the output will be an XML file. Case and whitespace are ignored when searching for a matching predefined stylesheet.
`-stylehelp`	Print defined style sheet names and exit.
`-title` `text`	The title to use for the report. If absent when `-untitled` is not specified, a default title will be used.
`-untitled`	Causes the title to be omitted from the report.
`-v[erbose]`	Causes all execution messages to be displayed.
-`version`	Prints the command's version and exits.
`-w[orkspace`]	The workspace context to use for parameters that are not workspaces. If no workspace is designated, a default workspace is synthesized.
`workspace` `file`	Sets workspace context for files to audit.

13.2.9 How to Create an Audit Profile

An audit profile defines the focus of an audit by specifying the rules, code assists, and metrics that will be used to analyze Java code. You can activate and deactivate rules, code assists, and metrics for an audit profile from the Audit Profiles preferences page. While several profiles are predefined, you can create others by modifying an existing profile. You can modify an audit profile by enabling or disabling rules, code assists, and metrics, or by changing their configuration.

JDeveloper provides predefined profiles, each with different combinations of the available rules, code assists, and metrics:

ADF Best Practice Rules
All Metrics
All Rules
Audit Rules
Code Assist Rules
Compile Rules
Javadoc Rules

To create an audit profile:

From the main menu, choose Tools > Preferences.
Choose Audit > Profiles.
From the Profile dropdown menu, choose a profile to copy.

As shown in Figure 13-1, the selected profile's property names and current values display in the right panel. A description of the selected item displays in the Explanation box. Its properties and settings display in the right pane.

Figure 13-1 Audit Profiles Page
Select the rules, assists, and metrics to enable in the new profile.
Click Save As.
Enter a name for the new profile, and click Save.

Note:

Names are not case or space sensitive, though case and space are preserved. If the new name differs only in case or space from an existing name, a warning message appears to inform you of this.

The new profile name is shown in the in the Audit Profiles preferences page's Profile box.
Click OK.

13.2.10 How to Delete an Audit Profile

You can delete an existing audit profile, but not a predefined profile. If you select a predefined audit profile on the Audit - Profiles page, the Delete button is greyed out.

To delete an existing audit profile:

From the main menu, choose Tools >Preferences.

The Preferences dialog opens.
Choose the Audit - Profiles page.
From the Profile dropdown menu, choose a profile to be deleted.
Click Delete.

The profile's name will be removed from the Profile box.
Click OK.

13.2.11 How to Import or Export an Audit Profile

You can import or export audit profiles. This enables you to share profiles, for example, or to maintain a checked in profile used by ojaudit and a nightly build. Audit profiles are imported or exported as XML files.

To import or export an audit profile:

In the Tools menu, select Preferences to open the Preferences dialog.
Choose Audit > Profiles.
Click Import or Export, and select the profile you want to import or export.

13.2.12 How to Run Audit to Generate an Audit Report

When you audit your Java programs, you can generate an audit report. An audit report is a list of rule violations and over-threshold measurements. In the audit report, you can investigate these problems, and manually or automatically correct them.

To generate an audit report:

In the Applications window, select one or more applications, projects, or Java source files.

The Audit command also works for selections from other views, such as editors and the Structure window
From the main menu choose Build > Audit <target>, for example, Build > Audit helloWorld.java.
In the Audit <target> dialog, choose a profile to use in one of the two following ways:
- From the Profile dropdown menu choose a profile to use.
- Click Edit to create or modify a profile.
Click Run.

An audit report appears in the Log window, and the audit begins. If you wish to stop the audit, click the stop icon in the log's toolbar.

13.2.13 How to Audit Serializable Fields That Do Not Have The serialVersionUID

An object is marked serializable by implementing the java.io.Serializable interface, which signifies that the object can be flattened into bytes and subsequently inflated in the future.

There is an identifier called serialVersionUID that enables versioning.

You can run an audit that flags all classes that implement java.io.Serializable but do not also have the serialVersionUID.

To set audit rules:

From the main menu, choose Tools > Preferences > Audit > Profiles.

13.2.14 How to Audit Unserializable Fields

An object is marked serializable by implementing the java.io.Serializable interface, which signifies that the object can be flattened into bytes and subsequently inflated in the future.

To turn off serialization on a field of an object, tag the field of the class of the object with the Java's transient keyword. If a class is marked as serializable, but contains unserializable fields that are not marked as transient, then the class is not serializable. You can run an audit to detect these unserializable fields.

To set audit rules:

From the main menu, choose Tools > Preferences > Audit > Profiles.

13.2.15 Viewing an Audit Report

As shown in Figure 13-2, audit reports are displayed as tabbed panes of the Log window.

Figure 13-2 Audit Report

Use the audit report to investigate and correct rule violations and over-threshold measurements.

Use refresh to rerun an audit using the same profile. You may wish to perform a refresh after you have made changes and fixes to your code.

To refresh an audit report:

Click in the Log Window toolbar, or right-click and choose Refresh.

The Export Audit Results dialog clears, and a new audit begins. If you want to stop the audit, click in the Log's toolbar.

13.2.16 How to Organize Audit Report Columns

You can rearrange the audit report columns into left or right positions.

To organize audit report columns:

Drag the column headers left or right to your preferred position.

13.2.17 How to Organize Audit Report Rows

Audit report rows are rule violations or measurements, or groups of violations and measurements. The report is organized as a tree. A row of the tree corresponds to either a construct or a violation, and includes any measured values for the construct or a theoretical violation. A construct is a method, class, file, package directory, project, or workspace.

You can choose the constructs that are shown in the report.

To organize audit report rows:

Click the Group By icon in the Log window toolbar.
Select the constructs you want to see.
Click OK.
Click a column header to sort rows by that column.

To reverse the sort order, click again.

13.2.18 How to Use Filters

You specify filters to prune the set of Java classes whose violations are shown. You can filter by package names, class names, or both. A filter consists of one or more patterns separated by commas.

A pattern can contain the following special characters:

* matches any number of characters
? matches any single character
! at the beginning of a pattern denotes an exclusion pattern

The set of classes that passes a filter is determined by considering the patterns in order. A non-exclusion pattern adds all classes that match the pattern to the set, an exclusion pattern removes all classes that match the pattern from the set. Table 13-6 contains the filters you can specify

Table 13-6 Filters

Name	Description
Package	Enter filter patterns that will apply to all but the last element of fully qualified class names. If this field is empty it has no effect.
File	Enter filter patterns that will apply only to the last element of fully qualified class names. If this field is empty it has no effect.
Apply	Click to apply the given Package and File filters to the report's rows.
Clear	Click to erase the Package and File filters, and to restore the report's rows.

To filter audit report rows:

In the Package field of the audit log window, enter a sequence of patterns that will apply to all but the last element of fully-qualified class names. You can leave this box empty if you specify a File filter.
In the File field, enter a sequence of patterns that will apply only to the last element of fully-qualified class names. You can leave this box empty if you specify a Package filter.
Click Apply.

The report redisplays to show only the selected rows.
Click Clear to delete text from the Package and File boxes.

13.2.19 How to Save an Audit Report

You can save an audit report as an XML file or as a formatted HTML or text file.

Formats are defined by XSL stylesheet files in the <jdev_install>/jdev/< system>/audit/stylesheets directory (this directory is not created until audit is run). To create a custom format, adapt a copy of one of the predefined stylesheet files, and add it to the directory.

To save an audit report:

Click in the Log Window toolbar, or right-click and choose Export.

The Export Audit Results dialog display. Choose a title, format, and destination for the report, and click OK.

13.2.20 How to Inspect an Audit Report Violation or Measurement

JDeveloper generates a report of all audit rule violations. In this window, you can choose a fix for a rule violation from a dropdown menu. For an individual rule violation, choose among the fixes defined for that violation's type.

To inspect an audit rule violation:

In the audit report, select the construct you want to view.
Right-click and choose Go to Source, or double-click the construct.

An editor for the source file opens with the cursor positioned at the location of the rule violation or the code element measured
Right-click on a violation or anomaly, and select About to learn more about the rule that has been violated. A pop-up describing the rules displays, as shown in Figure 13-3.

Figure 13-3 About Pop-up

13.2.21 How to Fix an Audit Rule Violation

You can fix an audit rule violation manually by editing the source, or for some rules, by selecting an automated fix. For an individual rule violation, choose among the fixes defined for that violation's type. For a group construct, the only choice is Apply Default Fixes, which applies the default fix defined for its type, if any.

To fix an audit rule violation manually:

In the audit report, select the rule violation (a leaf node in the Constructs tree).
Right-click and choose Go to Source.

An editor for the source file opens with the cursor positioned at the location of the rule violation.
Edit the code to correct the cause of the violation.

To apply an automated fix to an audit rule violation:

In the audit report, select the rule violation (a leaf node in the Constructs tree).
Right-click, and choose an Apply <Rule> Fix menu item, if any.

or

Click in the Log window toolbar, and choose one of Apply <Rule> Fix menu items.

13.2.22 How to Fix a Construct's Audit Rule Violations

You can apply automated fixes to all the rule violations in a construct. Default fixes will be applied to each rule violation in the construct that has a Default Fix property with a value other than None.

To fix a construct's audit rule violations:

In the audit report, select the construct (a container node in the Constructs tree).
You can apply default fixes in one of the two following ways:
- Right-click, and choose Apply Default Fixes.
- Click in the Log window toolbar, and choose Apply Default Values.

13.2.23 How to Hide Audit Rule Violations

You can suppress the display of all the rule violations of a given type in the audit report. This may make the report easier to read, since it hides all violations of a particular rule. It is not possible to suppress individual rule violations.

To hide audit rule violations:

In the audit report, select a rule violation (a leaf node in the Constructs tree).
Right-click, and choose Hide < Rule> Violations.

All of the violations of <Rule> are removed from the audit report. The removed rules are not tallied in their parent construct's summaries. Empty constructs are removed if Show Over Threshold Only is enabled. If not, just the violations are removed.

To restore hidden audit rule violations:

In the audit report, right-click to open the context menu.
Choose Show Hidden Violations.

All of the previously hidden rule violations are restored to the audit report.

13.2.24 How to Hide Audit Report Measurements

Metrics reports display measurements for the constructs in the analyzed code. You can focus the report on over-threshold measurements by hiding the others. The threshold is a settable property of metrics.

To show only over-threshold measurements:

In the Log window toolbar, click the over threshold icon. Click again to show all measurements.

Removed measurements are not tallied in their parent construct's summaries. Empty constructs are removed if Show Over Threshold Only is enabled. If not, just the violations are removed.

13.3 Profiling a Project

JDeveloper provides three profiling modes:

Monitor for no-overhead monitoring including JVM telemetry graphs and threads timeline. Choose this to obtain high-level information about properties of the target JVM, including thread activity and memory allocations.
CPU for quick sampling or highly customizable performance profiling utilizing dynamic bytecode instrumentation. Choose this to obtain detailed data on application performance, including the time to execute methods and the number of times the method is invoked.
Memory profiling including the Surviving Generations metric for identifying certain types of memory leaks. Choose this to obtain detailed data on object allocation and garbage collection.

13.3.1 About the CPU Profiler

The CPU Profiler is used to analyze your application's impact on the processor. Use the CPU Profiler to test functions of your application, such as startup and initialization, repainting, and compiling. The CPU profiler gathers statistics related to CPU usage by the application.

The CPU Profiling enables you to identify the methods and threads in your program that consume most of the CPU time. The CPU Profiler displays statistical data about the performance of your application.

You can specify if you want the Profiler to sample CPU time usage by your application, or to count method calls. Note that you can choose one mode at a time, not both.

Note:

You can choose only one mode at a time and not both the modes simultaneously.

13.3.2 About the Memory Profiler

The Memory Profiler enables you to find out how your program is using the Java heap. You can find memory leaks, inefficient heap usage, and in general any suspect memory behavior. The profiler has two tools for memory profiling: Quick (sampled) and Advanced (instrumented):

Quick (sampled) - samples the application and takes a stack trace periodically. This option is less precise than instrumenting methods, but the overhead is lower. This option can help you locate methods that you might want to instrument.
Advanced (instrumented) - instruments all the methods of the profiled application. You can choose to limit the part of the application's code that is instrumented by defining root methods. This option can greatly reduce the profiling overhead.

13.3.3 How to Start a Profiling Session

If you have a project that is targeted to run on your local machine, you can profile the project without any additional configuration. When you profile a local project, you launch the project and start the profiling session from within JDeveloper.

If you want to profile a local application but you cannot or do not want to start the application from JDeveloper, you can profile the application by attaching the IDE to the application. For more information, see Section 13.3.14, "Profiling Using Attach Mode".

To profile a local project, the project must be open in the editor. Before you can use the profiler in the IDE, you need to calibrate the profiler. You only need to calibrate the profiler once. For more information, see The first time you profile a project, the IDE needs to modify the project build script to integrate the profiler. The IDE creates a backup of your project build script before it performs the modifications.

To start a profiling session:

From the main menu, click Run > Profiler <project_name>

To attach the profiler, from the main menu, click Run > Attach Profiler.

13.3.4 About Profiling Windows

When profiling an application, the IDE provides a set of windows that enable you to control the profiling process and to view the profiling results. You can open the following windows by choosing Window > Profiling > window-name (for example, Window > Profiling > Profiling Points).

The following windows enable you to control and configure the profiling session:

Profiler window - This window contains controls enabling you to start, stop and modify profiling sessions, to open windows that display profiling results, and to manage snapshots.
Profiling Points window - This window enables you to view and manage profiling points.

The Profiler uses the following windows to display profiling results:

Live Profiling Results
Telemetry Overview window
VM Telemetry window
Profiling Threads window
Snapshots window
Heap window

13.3.5 About Profiling Results

The profiling results obtained from a profiling session depend upon the profiling task you select. When a profiling session is in progress, you can see the live results of the profiling task. At any point during the profiling session you can capture and save the results.

Live Results

The live results windows show the results of the profiling task over time while the profiling session is in progress.

VM Telemetry - The VM Telemetry window displays high-level data on thread activity and memory heap and garbage collection in the VM.
Threads - The Threads window displays detailed information about application thread activity.
Telemetry Overview - The Telemetry Overview window displays smaller versions of the graphs that are presented in the VM Telemetry window.
Live Profiling Results - The Live Profiling Results window displays the live data from the running profiling session. The live results displayed depend on the selected profiling task. Note: The Live Profiling Results view is not available when you are monitoring an application.

You can open any of these windows by choosing Window > Profiling > window name from the main menu.

Captured Results

The captured results windows show profiling data at a certain point in time during the profiling session. You can capture results at any time during a profiling session and save the results to your project or local system. You do not need to be running a profiling session to view saved captured results.

Snapshot - This view displays the captured results of a profiling session. The data contained in the snapshot depends upon the profiling task that is running when the snapshot is taken.
Heap - This view displays a heap dump. In this view you can examine the contents of the heap.
Save view as image - You can save a .png image of the current view displayed in a results window using Save Current View to Image button in the toolbar. This button is available only if the profile view supports saving to an image.

13.3.6 How to Calibrate the Profiler

You need to calibrate the IDE before you can use the IDE to profile an application. You need to run the calibration process for each JDK you will 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" in order to achieve more accurate results.

To calibrate the IDE to the local system:

Close any other programs that are running.

The IDE will run the calibration if other applications are running, but running any CPU-intensive programs when performing the calibration may affect the accuracy of profiling results.
From the Main menu, choose Run > Profiler > Run Profiling Calibration.
Choose the Java Platform that will be used for profiling and click OK.

Note:

The Java Platform is available for calibration only if it is added to Java SE Definitions on Tools > Manage Libraries page.

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

You should not share calibration data between various computers or systems.
Note:

You only need to calibrate the IDE once for each JDK you will 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

13.3.7 How to Take a Heap Dump

You can take a heap dump when a profiling session is in progress. When you take a heap dump you are prompted to save the heap to your project or local file system. After you save a heap dump you can load the heap dump at any time and browse the objects on the heap, locate references to individual objects and compare heap dumps to view the differences between the snapshots. You do not need to have a running profiling session to load and browse the heap dump.

The application must be running on JDK 1.5.0_12 or higher to take a heap dump.

To take a heap dump using a profiling point:

Open the source file containing the code where you want to place the profiling point.
Right-click in the line of code where you want to place the profiling point and select Add Profiling Point.
In the Profiling Point Type list, select one of the following snapshot options and click Next:
- Take Snapshot
- Timed Take Snapshot
- Triggered Take Snapshot
In the Customize Properties page of the wizard, select Heap Dump as the type of snapshot and modify any additional settings. The Heap Dump option is available under Settings > Take.

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:

From the Main menu, select Tools > Preferences > Profiler.
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.

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

13.3.8.1 OQL Examples

Select all Strings of length 100 or more:

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

Select all int arrays of length 256 or more:

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

Show content of Strings that match a regular expression:

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

Show path value of all File objects:

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

Show names of all ClassLoader classes:

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

Show instances of the Class identified by given id string:

select o from instanceof 0xd404b198 o

0xd404b198 is id of a Class (in a session). This is found by looking at the id shown in that class's page.

13.3.8.2 OQL built-in objects and functions

Heap object

The heap built-in object supports the following methods:

heap.forEachClass - calls a callback function for each Java Class
```
heap.forEachClass(callback);
```
heap.forEachObject - calls a callback function for each Java object
```
heap.forEachObject(callback, clazz, includeSubtypes);
```
clazz is the class whose instances are selected. If not specified, defaults to java.lang.Object. includeSubtypes is a boolean flag that specifies whether to include subtype instances or not. Default value of this flag is true.
heap.findClass - finds Java Class of given name
```
heap.findClass(className);
```
where className is name of the class to find. The resulting Class object has following properties:
- name - name of the class.
- superclass - Class object for super class (or null if java.lang.Object).
- statics - name, value pairs for static fields of the Class.
- fields - array of field objects. field object has name, signature properties.
- loader - ClassLoader object that loaded this class.
Class objects have the following methods:
- isSubclassOf - tests whether given class is direct or indirect subclass of this class or not.
- isSuperclassOf - tests whether given Class is direct or indirect superclass of this class or not.
- subclasses - returns array of direct and indirect subclasses.
- superclasses - returns array of direct and indirect superclasses.
heap.findObject - finds object from given object id
```
heap.findObject(stringIdOfObject);
```
heap.classes - returns an enumeration of all Java classes
heap.objects - returns an enumeration of Java objects
```
heap.objects(clazz, [includeSubtypes], [filter])
```
clazz is the class whose instances are selected. If not specified, defaults to java.lang.Object. includeSubtypes is a boolean flag that specifies whether to include subtype instances or not. Default value of this flag is true. This method accepts an optional filter expression to filter the result set of objects.
heap.finalizables - returns an enumeration of Java objects that are pending to be finalized.
heap.livepaths - return an enumeration of paths by which a given object is alive. This method accepts optional second parameter that is a boolean flag. This flag tells whether to include paths with weak reference(s) or not. By default, paths with weak reference(s) are not included.
```
select heap.livepaths(s) from java.lang.String s
```
Each element of this array itself is another array. The later array is contains an objects that are in the 'reference chain' of the path.
heap.roots - returns an Enumeration of Roots of the heap.

Each Root object has the following properties:
- id - String id of the object that is referred by this root
- type - descriptive type of Root (JNI Global, JNI Local, Java Static, etc.)
- description - String description of the Root
- referrer - Thread Object or Class object that is responsible for this root or null

Examples

Access static field 'props' of class java.lang.System

select heap.findClass("java.lang.System").statics.props
select heap.findClass("java.lang.System").props

Get number of fields of java.lang.String class

select heap.findClass("java.lang.String").fields.length

Find the object whose object id is given
```
select heap.findObject("0xf3800b58")
```

Select all classes that have name pattern java.net.*

select filter(heap.classes(), "/java.net./(it.name)")

Functions on individual objects

allocTrace function

Returns allocation site trace of a given Java object if available. allocTrace returns array of frame objects. Each frame object has the following properties:
- className - name of the Java class whose method is running in the frame.
- methodName - name of the Java method running in the frame.
- methodSignature - signature of the Java method running in the frame.
- sourceFileName - name of source file of the Java class running in the frame.
- lineNumber - source line number within the method.
classof function

Returns class object of a given Java object. The resulting object supports the following properties:
- name - name of the class
- superclass - class object for super class (or null if java.lang.Object)
- statics - name, value pairs for static fields of the class
- fields - array of field objects. Field objects have name, signature properties
- loader - ClassLoader object that loaded this class.
Class objects have the following methods:
- isSubclassOf - tests whether given class is direct or indirect subclass of this class or not
- isSuperclassOf - tests whether a given class is direct or indirect superclass of this class or not
- subclasses - returns array of direct and indirect subclasses
- superclasses - returns array of direct and indirect superclasses
Examples
- Show class name of each Reference type object
```
select classof(o).name from instanceof java.lang.ref.Reference o
```
- Show all subclasses of java.io.InputStream
```
select heap.findClass("java.io.InputStream").subclasses()
```
- Show all superclasses of java.io.BufferedInputStream
```
show all superclasses of java.io.BufferedInputStream 
```

forEachReferrer function

Calls a callback function for each referrer of a given Java object.

identical function

Returns whether two given Java objects are identical or not, for example:

select identical(heap.findClass("Foo").statics.bar, heap.findClass("AnotherClass").statics.bar)

objectid function

Returns String id of a given Java object. This id can be passed to heap.findObject and may also be used to compare objects for identity. For example:
```
select objectid(o) from java.lang.Object o
```
reachables function

Returns an array of Java objects that are transitively referred from the given Java object. Optionally accepts a second parameter that is comma separated field names to be excluded from reachability computation. Fields are written in class_name.field_name pattern.

Examples
- Print all reachable objects from each Properties instance.
```
select reachables(p) from java.util.Properties p
```
- Print all reachables from each java.net.URL but omit the objects reachable via the fields specified.
```
select reachables(u, 'java.net.URL.handler') from java.net.URL u
```
referrers function

Returns an enumeration of Java objects that hold reference to a given Java object. This method accepts optional second parameter that is a boolean flag. This flag tells whether to include weak reference(s) or not. By default, weak reference(s) are not included.

Examples
- Print number of referrers for each java.lang.Object instance
```
select count(referrers(o)) from java.lang.Object o
```
- Print referrers for each java.io.File object
```
select referrers(f) from java.io.File f
```
- Print URL objects only if referred by 2 or more
```
select u from java.net.URL u where count(referrers(u)) > 2
```
referees function

Returns an array of Java objects to which the given Java object directly refers to. This method accepts optional second parameter that is a boolean flag. This flag tells whether to include weak reference(s) or not. By default, weak reference(s) are not included. For example, to print all static reference fields of java.io.File class:
```
select referees(heap.findClass("java.io.File"))
```
refers function

Returns whether first Java object refers to second Java object or not.
root function

If the given object is a member of root set of objects, this function returns a descriptive Root object describing why it is so. If given object is not a root, then this function returns null.
sizeof function

Returns size of the given Java object in bytes, for example:
```
select sizeof(o) from int[] o
```
retainedsize function

Returns size of the retained set of the given Java object in bytes. Note: Using this function for the first time on a heap dump may take significant amount of time.

The following is an example usage of the retainedsize function:
```
select rsizeof(o) from instanceof java.lang.HashMap o
```
toHtml function

Returns HTML string for the given Java object. Note that this is called automatically for objects selected by select expression. But, it may be useful to print more complex output. For example, to print a hyperlink in bold font:
```
select "<b>" + toHtml(o) + "</b>" from java.lang.Object o
```

13.3.8.3 Selecting Multiple Values

Multiple values can be selected using JavaScript object literals or arrays.

For example, show the name and thread for each thread object

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

array/iterator/enumeration manipulation functions

These functions accept an array/iterator/enumeration and an expression string [or a callback function] as input. These functions iterate the array/iterator/enumeration and apply the expression (or function) on each element. Note: JavaScript objects are associative arrays. So, these functions may also be used with arbitrary JavaScript objects.

concat function

Returns whether the given array/enumeration contains an element the given boolean expression specified in code. The code evaluated can refer to the following built-in variables.
- it - currently visited element
- index - index of the current element
- array - array/enumeration that is being iterated
For example, to select all Properties objects that are referred by some static field some class:
```
select p from java.util.Properties p
where contains(referrers(p), "classof(it).name == 'java.lang.Class'")
```
count function

Returns the count of elements of the input array/enumeration that satisfy the given boolean expression. The boolean expression code can refer to the following built-in variables.
- it - currently visited element
- index - index of the current element
- array - array/enumeration that is being iterated
For example, print the number of classes that have a specific name pattern:
```
select count(heap.classes(), "/java.io./(it.name)")
```
filter function

Returns an array/enumeration that contains elements of the input array/enumeration that satisfy the given boolean expression. The boolean expression code can refer to the following built-in variables.
- it - currently visited element
- index - index of the current element
- array - array/enumeration that is being iterated
- result -> result array/enumeration
Examples
- Show all classes that have java.io.* name pattern
```
select filter(heap.classes(), "/java.io./(it.name)")
```
- Show all referrers of URL object where the referrer is not from java.net package
```
select filter(referrers(u), "! /java.net./(classof(it).name)")
from java.net.URL u
```
length function

Returns number of elements of an array/enumeration.
map function

Transforms the given array/enumeration by evaluating given code on each element. The code evaluated can refer to the following built-in variables.
- it - currently visited element
- index - index of the current element
- array - array/enumeration that is being iterated
- result -> result array/enumeration
Map function returns an array/enumeration of values created by repeatedly calling code on each element of input array/enumeration.

For example, show all static fields of java.io.File with name and value:
```
select map(heap.findClass("java.io.File").statics, "index + '=' + toHtml(it)")
```
max function

Returns the maximum element of the given array/enumeration. Optionally accepts code expression to compare elements of the array. By default numerical comparison is used. The comparison expression can use the following built-in variables:
- lhs - left side element for comparison
- rhs - right side element for comparison
Examples
- Find the maximum length of any string instance
```
select max(map(heap.objects('java.lang.String', false), 'it.count'))
```
- Find string instance that has the maximum length
```
select max(heap.objects('java.lang.String'), 'lhs.count > rhs.count')
```
min function

Returns the minimum element of the given array/enumeration. Optionally accepts code expression to compare elements of the array. By default numerical comparison is used. The comparison expression can use the following built-in variables:
- lhs - left side element for comparison
- rhs - right side element for comparison
Examples
- Find the minimum size of any vector instance
```
select min(map(heap.objects('java.util.Vector', false), 'it.elementData.length'))
```
- Find vector instance that has the maximum length
```
select min(heap.objects('java.util.Vector'), 'lhs.elementData.length < rhs.elementData.length')
```
sort function

Sorts a given array/enumeration. Optionally accepts code expression to compare elements of the array. By default numerical comparison is used. The comparison expression can use the following built-in variables:
- lhs - left side element for comparison
- rhs - right side element for comparison
Examples
- Print all char[] objects in the order of size.
```
select sort(heap.objects('char[]'), 'sizeof(lhs) - sizeof(rhs)')
```
- Print all char[] objects in the order of size but print size as well.
```
select map(sort(heap.objects('char[]'), 'sizeof(lhs) - sizeof(rhs)'), 
'{ size: sizeof(it), obj: it }')
```
top function

Returns top N elements of the given array/enumeration. Optionally accepts code expression to compare elements of the array and the number of top elements. By default the first 10 elements in the order of appearance is returned. The comparison expression can use the following built-in variables:
- lhs - left side element for comparison
- rhs - right side element for comparison
Examples
- Print 5 longest strings
```
select top(heap.objects('java.lang.String'), 'rhs.count - lhs.count', 5)
```
- Print 5 longest strings but print size as well.
```
select map(top(heap.objects('java.lang.String'), 
'rhs.count - lhs.count', 5), '{ length: it.count, obj: it }')
```
sum function

Returns the sum of all the elements of the given input array or enumeration. Optionally, accepts an expression as second param. This is used to map the input elements before summing those.

For example, return the sum of sizes of the reachable objects from each Properties object:
```
select sum(map(reachables(p), 'sizeof(it)')) 
from java.util.Properties p
 
// or omit the map as in ...
select sum(reachables(p), 'sizeof(it)') 
from java.util.Properties p
```
toArray function

Returns an array that contains elements of the input array/enumeration.
unique function

Returns an array/enumeration containing unique elements of the given input array/enumeration.

The following example selects a unique char[] instances referenced from strings. Note that more than one string instance can share the same char[] for the content.
```
// number of unique char[] instances referenced from any String
select count(unique(map(heap.objects('java.lang.String'), 'it.value')))
 
// total number of Strings
select count(heap.objects('java.lang.String'))
```

13.3.8.4 Other Examples

The following example prints a histogram of each class loader and number of classes loaded by it.

java.lang.ClassLoader has a private field called classes of type java.util.Vector and Vector has a private field named elementCount that is number of elements in the vector. The query selects multiple values (loader, count) using JavaScript object literal and map function. It sorts the result by count (i.e., number of classes loaded) using sort function with comparison expression.

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

The following example shows the parent-child chain for each class loader instance.

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>";
      })

Note that the parent field of java.lang.ClassLoader class is used and the example walks until the parent is null using the callback function to map call.

The following example prints the value of all System properties. Note that this query (and many other queries) may not be stable - because private fields of the Java platform classes may be modified or removed without any notification (implementation detail). But using such queries on user classes may be safe, given that you have control over the classes.

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;
            });

java.lang.System has static field by name 'props' of type java.util.Properties.
java.util.Properties has field by 'table' of type java.util.Hashtable$Entry (this field is inherited from java.util.Hashtable). This is the hashtable buckets array.
java.util.Hashtable$Entry has key, value and next fields. Each entry points the next entry (or null) in the same hashtable bucket.
java.lang.String class has a value field of type char[].

13.3.9 How to Analyze CPU Performance

This task analyzes the performance of the target application. You can choose to profile the entire application or limit the code that is instrumented by specifying filters to control the classes that are profiled.

When you run this profiling task you receive the following profiling results:

Time in percentage and real time for executing methods in context
Number of times each method is invoked in context
Chains of method calls leading to method invocation
Time / number for executing methods in context

To analyze performance of the application:

Open the application you want to analyze.
From the main menu, select Run > Profile.
Click CPU in the left pane of the Profile window.
In the Filter list, select a filter.
If you choose, you can use profiling points to control profiler actions.
If you want to create a new custom configuration, click Create Custom...
Click Run.

When you click Run, the target application launches and the profiling session starts.

13.3.10 How to Create a Custom Configuration

When you create a custom configuration, you have complete control over all of the available internal settings for that profiling task. You can create, store, and assign names to separate sets of custom profiling settings. The custom configuration is associated with a specific project and is selectable in the CPU section of the Profile dialog.

You can set more advanced profiling options by clicking Advanced Settings. Custom configurations are automatically saved between IDE work sessions so that they can be reused and modified.

To create a custom configuration:

Open the application for which you want to create a custom configuration.
From the main menu, select Run > Profile.
Click CPU in the left pane of the Profile window.
Select the options you want to be part of the configuration, for example, filters, profiling points, etc.
Click Create Custom...
In the Name text box, enter a name for the new configuration.
Click OK.

13.3.11 Filtering Profiling Results

In the Live Profiling Results window and in result snapshots you can use the filter box located below the displayed results to filter the results by name.

To filter results by name:

From the Main menu, click Window > Live Results.
Enter the filter term in the filter box below the displayed results.

In snapshots, the filter box is available in the HotSpots and Combined tabs in CPU snapshots, and in the Memory tab in memory snapshots.
Choose one of the following filtering parameters for the term from the drop-down menu:
- Starts with(case sensitive)
- Contains (case insensitive)
- Does Not Contain(case insensitive)
- Ends with (case sensitive)
- Regular expression (case sensitive)
Click the check on the right to apply the filter to the results.

You can see and select previous filter terms by clicking the arrow to the right of the filter box. To restore the full unfiltered results, click Clear Filter to the right of the filter box.

13.3.12 How to Set Profiling Filters

When you analyze application performance, you can use filters to specify the classes that you want to include or exclude in the instrumentation. When you use a filter you limit the number of instrumented classes and reduce the profiling overhead. You choose a filter by selecting a filter from the Filter dropdown list when you configure the profiling session.

To modify the Quick Filter settings:

Open the application for which you want to create a custom configuration.
From the main menu, select Run > Profile.
Select Quick Filter in the Filter list.
Select either Exclusive or Inclusive as the filter type.
Enter filter values and click OK.

If you want to use a filter more than once, you can create a custom filter set.

To modify or create a custom filter set:

Choose CPU in the Select Profiling Task dialog.
Click Edit Filter Sets.
Select an existing filter set or click Add and enter a name for the new filter set.
Specify the Filter Set Type.
In the Global Filters list, activate the global filters you wish to be part of the filter set by selecting the checkbox for that filter.

You can place your cursor over the values to see all the patterns included in that filter.
Click OK to save the new custom filter set

After you create a new filter set, you can choose the filter in the Filter drop-down list. You can use the new filter when analyzing the performance of any project.

13.3.13 Working with Live Profiling Results

The Live Profiling Results window displays the live results of the running profiling session. You can use the toolbar and popup menus to work with the results displayed in the Live Profiling Results window. To open the Live Profiling Results window, do one of the following during a profiling session:

Choose Window > Profiling > Live Results from the main menu.
Click Live Results in the Profiler window.

Element	Description
Update Results Automatically	When enabled (default), results are updated at short intervals. When disabled, click Update Results Now to update the results.
Update Results Now	Click to update the results immediately.
Run Garbage Collection and Update Results	Run garbage collection.
Reset Collected Results	Click to discard the already accumulated profiling results.
Take Snapshot of Collected Results	Click to save the results as snapshot. The unsaved snapshot is opened in the Source Editor.
Save Current View	Click to save the displayed results as a `.png` image.

You can sort the results by clicking on the respective column header or right-click result entries to choose commands from the popup menu. The results that are displayed and the popup menu items available depend on which of the following profiling tasks is running.

13.3.14 Profiling Using Attach Mode

However, if you want or need to start your application outside of the IDE you can use the attach mode to profile an application. 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 appliction or target JVM.
You want to profile the application without restarting the application.

You must use the attach mode in the following cases:

You want to profile an application running on a remote JVM, such as a remote application server.

The Attach mode enables you to attach the profiling tool to an application that is already running, or just about to start on a local or remote machine. Using the attach mode is useful for profiling long-running applications, and in particular for profiling web or enterprise applications running on top of an application server. You can also use the attach mode to profile the code of the application server itself.

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

In the Attach Wizard you specify the type of application and the location. Based on the details that you provide, the Attach Wizard provides you with a set of instructions on how to configure the application or server so that you can attach the profiler.

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

Local Direct

Use this mode if you want to obtain profiling data on the startup of a local application.

When you use this mode, the target JVM and application wait until you attach the profiler before starting. After you detach from the application, you need to restart the application to start another profiling session.
Local Dynamic (requires JDK 1.6)

Use this mode if you want to obtain profiling data on a local application. To use this mode, the application needs to be running on JDK 1.6.

When you use this mode, you can attach to and detach from the application without restarting application.
Remote Direct

Use this mode if you want to obtain profiling data on an application running on a remote JVM. To use this mode, you need to install the Profiler Remote Pack on the target machine. You specify the details of the remote system and generate the Profiler Remote Pack using the Attach Wizard.

When you use this mode, the remote application starts after the profiler is attached. This mode enables you to obtain profiling data on the startup of the target JVM.

13.3.15 How to Monitor an Application

When you choose Monitor Application in the Profiling Task box, the target application runs without any instrumentation. The results show only high-level information about some properties of the target JVM, including thread activity and memory allocations.

To monitor an application:

Open the application you want to monitor.
From the main menu, select Run > Profile.
Click Monitor.
Optionally Select Enable Threads Monitoring.

Select this option to monitor threads from application startup.
Click Run.

When you click Run, the target application launches and the profiling task starts. Click the Telemetry button or the Threads button in the Profiler window to view the results.

By default, application thread activity is not monitored. You can start monitoring thread activity at any time during a profiling session by opening the Threads tab and clicking the Threads button.

If you want to monitor threads from application startup, select Enable Threads Monitoring before you start the profiling session.

13.3.16 How to Set Profiling Points

A profiling point is a marker in your source code which can invoke specific profiling actions. You set a profiling point in your code by using the popup menu in the Source Editor or by using the toolbar in the Profiling Points window.

You can set the following types of profiling points:

Reset Results
Stopwatch
Take Snapshot
Timed Take Snapshot
Triggered Take Snapshot

Note: Icons for the Timed Take Snapshot and Triggered Take Snapshot do not display in code editors. They only display in the Profiling Points window.

You can use a profiling point to reset profiling results, take a snapshot or record the timestamp or execution time of a code fragment.

Once you set a profiling point it becomes part of the project until you delete it.

To set a profiling point:

Locate the class where you want to add the profiling point and open the class in the Source Editor.
In the Source Editor, right-click in the gutter on the line where you want to add the profiling point.
Select Add Profiling Point to open the New Profiling Point wizard.
Select a profiling point type and the project.
Click Next.
Customize the properties of the profiling point, if necessary.
Click Finish.

An icon representing the profiling point type appears in the Source Editor where you inserted the profiling point.

To enable or disable a profiling point, in the Source Editor, right-click in the left margin of the line containing the profiling point and choose <Profiling point name> > Enable or Disable.

To view active profiling points:

Open the application.
From the main menu, select Run > Profile.
Select a profiling task (CPU or Memory).
Select Show Active Profiling Points.

You can also select Window > Profiling > Profiling Points.

13.3.17 How to Attach to a Remote Application

You can profile an application that is running on a remote system such as a web server by attaching the profiling tool to the application. When you use this mode, the remote application starts after the profiler is attached. This mode enables you to obtain profiling data on the startup of the target JVM.

To attach the profiling tool you use the Attach Wizard to specify the attachment settings for your project. In the Attach Wizard you specify the type of application and the remote location. Based on the details that you provide, the Attach Wizard provides you with a set of instructions on how to configure the remote system to support profiling.

To attach to a remote system you need to install a Remote Profiler Pack on the remote system and start the remote system on the pack. You use the Attach Wizard to specify the details of the remote system and to generate a Remote Profiler Pack for that system. See Section 13.3.18, "How to Generate a Profiler Remote Pack" for more information.

After you configure the remote system according to the instructions, you can attach the profiler to the remote location. You only need to configure the attach mode once. The attachment settings are associated with that project. You can go through the Attach Wizard at any time to change any of the attachment settings.

To profile a remote application:

Open the application.
From the main menu, select Run > Attach Profiler.
On the Profiler dialog, click define... to configure the attachment settings.
Under Attach Method, select Remote.
Complete the Attach wizard to specify the attachment settings according to the target application.
Click Finish to exit the Attach wizard.
Configure the target location and start the remote application according to the instructions provided in the last page of the Attach Wizard. You will need to install the generated Profiler Remote Pack on the remote system if not installed.

When you start the remote application, the application will wait until the IDE is attached before starting.
In the Profiler page, select a profiling task and any profiling options.
Click Attach.

When you click Attach, JDeveloper will attach to the remote JVM and the application will start. You can view profiling data as you would for a local application.

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 you need to use the startup options provided by the Attach wizard 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 need to reattach and restart the remote application.

13.3.18 How to Generate a Profiler Remote Pack

To attach the profiling tool to a remote system you need to install a Remote Profiler Pack on the remote system. The Remote Profiler Pack is an archive of libraries that enables the profiling tool to attach to the remote system.

To generate a Remote Profiler Pack:

Open the application.
From the main menu, select Run > Attach Profiler.
At the bottom of the Attach Profiler dialog, click define...
Under Attach Method, select Remote.
Specify the Hostname and Operating System.
Read the attach instructions and click Create a Remote Profiling Pack.

When you click Generate Remote Pack, you are prompted to specify a location where you want to save the Profiler Remote Pack. After the IDE generates the pack you need to follow the Attach Wizard instructions to install the pack and start the remote system on the pack.

13.3.19 How to Attach to a Local Application:

You can use the attach mode to profile a local application when you want or need to 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 appliction or target JVM.
You want to profile the application without restarting the application (Dynamic attach mode, requires JDK 1.6).

To attach to a local application, you first need to configure the attachment settings using the Attach wizard. These settings are associated with the project you are profiling. You only need to configure the attach settings for your project once, but you can modify the settings at any time by stepping through the Attach wizard again.

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

Direct - This mode enables you to obtain profiling data on the startup of the local application.
Dynamic (requires JDK 1.6) - This mode allows you to detach from and re-attach to the application without stopping the application.

To remotely attach to a local application:

Open the application.
From the main menu, select Run > Attach Profiler.
In the Attach To list, select the project, if available.
At the bottom of the Attach Profiler dialog, click define...
In the Attach Settings wizard, select the Local attach mode.
Complete the Attach wizard to specify the attachment settings according to the target application.
Click OK to exit the Attach Settings wizard.
Configure the target location and start the local application according to the instructions provided in the Attach Wizard. You will need to install the generated Profiler Remote Pack on the local system if not installed. See Section 13.3.18, "How to Generate a Profiler Remote Pack" for more information.

When you start the local application, the application will wait until the IDE is attached before starting.
Select a profiling task and any profiling options.
Click Attach.

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

Detach from the remote local application

When you detach from the remote local application, the application does not stop but you stop receiving profiling data about the application. To attach to the remote application you need to use the startup options provided by the Attach wizard 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 need to reattach and restart the remote application.

13.3.20 How to View Thread Activity

During a profiling session, you can view detailed information about application thread activity in the Threads window.

You can start monitoring thread activity at any time during a profiling session by opening the Threads tab and clicking the Threads button. By default, application thread activity is not monitored until invoked.

To open the Threads Window:

From the main menu, choose Window > Profiling > Threads.

If you want to monitor threads from application startup, select Enable Threads Monitoring when you start the profiling session. You can find this advanced setting on the Profile dialog.

13.3.21 How to View Telemetry Results

You can view high-level data on thread activity and memory heap and garbage collection in the VM Telemetry window. The VM Telemetry window is typically visible in the main Editor window.

To open the VM Telemetry window, do one of the following during a profiling session:

Select Window > Profiling > VM Telemetry from the main menu.
Click VM Telemetry in the Profiler tab (click Window > Profiling > Profiler from the main menu.

VM Telemetry results are displayed in the following tabs:

Memory (Heap) - This tab displays the total size and used size of the heap.
Memory (GC) - This tab displays the relative time spent in garbage collection and the number of surviving generations.
Threads/Loaded Classes - This tab displays the total number of threads in the profiled application JVM.

In each of the tabs, you can place your cursor over the graph to invoke a tooltip that displays more detailed data.

13.3.22 How to Take a Snapshot

A snapshot captures profiling data at a specific point in time. The data captured in a snapshot depends on the type of profiling session in progress when the snapshot is taken. You can explore snapshots using the toolbar in the Snapshot window and by filtering the displayed results. You can also right-click a result and select additional commands in the pop-up menu.

A snapshot differs from live profiling results in the following ways:

Snapshots can be examined when no profiling session is running.
Snapshots contain a more detailed record of profiling data than live results.
Snapshots can be easily compared.

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.

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

Start a profiling session (for more information, see Section 13.3.3, "How to Start a Profiling Session").
From the main menu, click Window > Profiling > Profiler.
Click Take Snapshot.

To take a snapshot using a profiling point:

Open the source file containing the line of code where you want to place the profiling point.
Right-click in the gutter next to the line of code and click Add Profiling Point.
Select one of the snapshot options in the New Profiling Point wizard and click Next.
Modify any of the profiling point properties in the Customize Properties page of the wizard.
Click Finish.

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 Saved Snapshots in the Profiler window. You can save a snapshot by clicking the Save to Project button in the snapshot toolbar. Alternatively, you can use the Tools > Preferences > Profiler window to configure the behavior when taking a snapshot.

13.4 Unit Testing with JUnit

JUnit is an open source regression testing framework for Java. Use JUnit to write and run tests that verify Java code.

Use JUnit wizards in JDeveloper to create test fixtures, cases, and suites. In addition to wizards for creating test components for generic projects, specialized wizards for business components projects are provided.

JUnit is an optional feature that can be installed and integrated with JDeveloper.

13.4.1 How to Install JUnit

JUnit is an optional feature that is not distributed with JDeveloper. You must download and install it if you wish to use it.

Note:

JUnit is provided under an IBM public license agreement. You must accept to the license agreement before downloading JUnit.

To install JUnit in JDeveloper:

Navigate to Help > Check for Updates to download JUnit from the Oracle Technology Network (OTN).
Exit and restart JDeveloper.
JUnit will be installed. Use the Extension Manager if you want to uninstall it.

13.4.2 Creating a JUnit Test for a Java Project

A JUnit test application consists of the following components:

One or more test cases, which invoke the methods that are to be tested, and make assertions about the expected results. While test case classes generated by default have 'Test' in their names, the user can specify any valid Java name.
Test fixtures, which provide the state in which the tests are run. Any class can serve as a test fixture, but JDeveloper provides wizards to help you create specialized test fixture classes. While test fixture classes generated by default have 'Fixture' in their names, the user can specify any valid Java name.
A test suite, which invokes the test cases. Default test suite classes have 'AllTests' in their names.
A runner, which invokes the test suite and collates and displays the results of the tests.

13.4.3 How to Create a JUnit Custom Test Fixture

A test fixture is a set of objects, having known values, that provide data for the test cases. Any class can serve as a test fixture, but JDeveloper provides wizards to help you create custom test fixture classes and various specialized test fixture classes.

Note:

UnitTestFixture is a public class. If you create an instance of it, there will be no errors in generated code.

AppModuleAMFixture is a private class. If you create an instance of it, there will be errors in the generated code.

To create a JUnit custom test fixture class:

In the Applications window, select the project.
Choose File > New > From Gallery.
In the Categories tree, expand General and select Unit Tests.
In the Items list, double-click Test Fixture.
Complete the wizard to create the test fixture class.

The class created by the wizard will be opened for editing.
In the Categories tree, expand General and select Unit Tests (JUnit).
In the Items list, double-click Custom Test Fixture.
Complete the wizard to create the test fixture class.
In the Categories tree, expand the Unit Tests.
Click Test Suite > OK.
In the Items list, double-click Test Fixture.
Complete the wizard to create the test case.

The class created by the wizard will be opened for editing.

When you create the test fixture using the wizard, a constructor is provided by default.
Modify the file as needed.

In particular, add code that initializes test fixture objects to the setUp() method. Add code that releases any resources they acquire to the tearDown() method.

13.4.4 How to Create a JUnit JDBC Test Fixture

A test fixture is a set of objects, having known values, that provide data for the test cases. A JDBC test fixture provides code that establishes a database connection for the test cases to use.

To create a JUnit JDBC test fixture class:

In the Applications window, select the project.
Choose File > New > From Gallery.
In the Categories tree, expand General and select Unit Tests (JUnit).
In the Items list, double-click JDBC Test Fixture.
Complete the dialog to create the test fixture class.

The class that was created will be opened for editing.
Modify the file as needed. In particular, to the setUp() method add code that initializes test fixture objects, and to the tearDown() method add code that releases any resources they acquire.

13.4.5 Creating a JUnit Test Case

A test case class has one or more methods that perform tests by calling JUnit assertions. Example 13-1 shows a typical test case in JUnit 3.x. It passes test fixture data to the method being tested, and then compare the result with a known value to confirm that it is what is expected.

Example 13-1 JUnit 3.x Test Case

public void testCountChars()
{
      int expected = 4;
      int actual = fixture1.countChars('a');
      assertEquals(expected, actual);
}

Example 13-2 JUnit 4 Test Case

@Test
public void testCountChars()
{
      int expected = 4;
      int actual = fixture1.countChars('a');
      Assert.assertEquals(expected, actual);
}

In the test case shown in Example 13-2, countChars() is being tested, and the result of the test is checked by assertEquals(), which is one of a variety of assertion methods defined in the JUnit Assert class. The state of the test fixture, fixture1, is established in the setUp() method, which will have been called before the test case is called, as shown in Example 13-3.

Example 13-3 setUp() method

protected void setup() throws Exception
{
fixture1 = new StringFixture("Goin' to Kansas City, Kansas City, here I come.");
}

To create a JUnit test case class:

In the Applications window, select the project or the particular class that you want to test.
Choose File > New > From Gallery.
In the Categories tree, expand General and select Unit Tests (JUnit).
In the Items list, double-click Test Case.
Complete the wizard to create the test fixture class. The class created by the wizard will be opened for editing.

13.4.6 Creating a JUnit Test Suite

A test suite is a class that invokes test cases.

The JUnit Test Suite wizard has options to insert a main() method and a call to a TestRunner class. Within JDeveloper, this will open the JUnit TestRunner log window to display the test results. Edit the method if you wish to use a different test runner.

In the JUnit 3.x test suite shown in Example 13-4, the suite() method creates a TestSuite instance and adds the test cases to it. Edit this method if you wish to add or remove test cases.

Example 13-4 JUnit 3.x Test Suite

public class AllTests {
    public static Test suite() {
    TestSuite suite;
    suite = new TestSuite("project1.AllTests");
    return suite;    }

In the JUnit 4 test suite shown in Example 13-5, the test case classes are written with @Suite and @RunWith annotations.

Example 13-5 JUnit 4 Test Suite

@RunWith(Suite.class)
@Suite.SuiteClasses( {})
public class AllTests1 {
    public static void main(String[] args) {
    String[] args2 = { AllTests1.class.getName() };
    org.junit.runner.JUnitCore.main(args2);
    }
}

To create a JUnit test suite class:

In the Applications window, select the project.
Choose File > New > From Gallery.
In the Categories tree, expand General and select Unit Tests (JUnit).
In the Items list, double-click Test Suite.
Complete the wizard to create the test suite class. The class created by the wizard displays for editing.
Modify the file as needed. In particular:
- In the suite() method, add the test cases.
- In the main() method, replace the runner invocation, if desired.

13.4.7 How to Create a JUnit Test Case

Before you create a JUnit test case, you must have created a project that is to be tested.

To generate a JUnit test case:

In the Applications window, right-click the project in which want to create a test case and choose New.
In the New Gallery, expand General, select Unit Tests and then Test Case, and click OK.
In the Select the Class to Test page of the Create Test Case dialog, enter the class under test or click Browse.
In the Class Browser dialog, locate the class you want to test or enter the beginning letters in the Match Class Name field. The Match Class list will be filtered for easier identification.

Select the class and click OK to close the dialog. Click Next.
Select the individual methods you want to test and click Next.
In the Setup Test Case Class page, enter the name of the test case, the package, and the class it extends and select the list of built-in functions JUnit will create stubs for. Click Next.
In the Select Test Fixtures page, select any test fixtures you want to add to the test case or click Browse.
Make sure that all the test fixtures you want to add to the test case are selected in the list and click Finish.

13.4.8 How to Add a Test to a JUnit Test Case

You can add a unit test for a method to an existing JUnit test case class.

To add a test to a JUnit test case class:

In the code editor, select a method for which you want to create a new unit test.
From the main menu, choose Source > New Method Test.
Select Add to Existing TestCase Class.
From the Class Name dropdown box, or by using Browse, select the test case class that you want to add the new test to.
To add the new test to the test case, click OK.

13.4.9 How to Create a Business Components Test Suite

The test fixture that is created is a singleton class to reduce the number of connections. If you want to connect or disconnect for each test case, customize the test case using the JUnit 4 annotations @Before and @After.

The JUnit BC4J Test Suite wizard will generate tests for each view object in the application module. If the application module does not have exported methods, the wizard will also generate a test for the application module itself. A generated view object class has the format view_objectVOTest.java and is placed into a package with the format package.view.viewobjectVO, where package is the application module package. A generated application module test has the format application_moduleAMTest.java and is placed into a package with the format package.applicationModule. A generated test fixture class has the format applicationmoduleAMFixture.java and is placed in the same package as the application module test.

The generated all test suite class has the format AllapplicationmoduleTest.java and is placed into the package with the same name as the application module package name.

A test case XML file is also generated for each application module or view object test. The XML file contains test methods defined in the application module or view object test cases. It does not include the test methods from the base classes (if any) because there may be too many duplicates.

To create a business components test suite:

In the main menu, choose File and then New.

You will create a separate project for the business components tests.
In the New Gallery, expand General, select Projects and then Java Projects, and click OK.
In the Project Name page of the Create Java Project wizard, enter a name and the directory path for the test project, and click Next.
In the Project Java Settings page, enter the package name, the directory of the Java source code in your project, and output directory where output class files will be placed, and click Finish.
In the Applications window, double-click the application module you want to test.
In the overview editor, click the Java navigation tab.
In the Java page, click the Edit icon for the Java Class section.
In the Select Java Options dialog, select Generate Application Module Class and click OK.
In the Java page of the overview editor, click the Edit icon for the Class Interface section.
In the Edit Client Interface dialog, shuttle the methods you want to test to the Selected pane, and click OK.
In the Applications window, right-click the test project you have created and choose New.
In the New Gallery, expand General, select Unit Tests and then Business Components Test Suite, and click OK.
In the Configure Tests page of the JUnit BC4J Test Suite wizard, select values for the following and click Next:
- Business Component Project: Select the project that has the application module you want to test.
- Application Module: Select the application module you want to test.
- Configuration: Choose a local or shared application module.
- Test Base Class-Application Module Extends: You can specify different base cases. The generated test case classes will extend from that base class where all public abstract methods in the base class will have simple and default implementation method bodies.
- Test Base Class-View Object Extends: You can specify which class the view object extends. The generated test case classes will extend from that base class where all public abstract methods in the base class will have simple and default implementation method bodies.
In the Summary page, verify the selections and click Finish.

13.4.10 How to Create a Business Components Test Fixture

When you create a business components test suite, a business components test fixture is created with it. You can also create Business Components test fixtures independently.

A generated test fixture class has the format applicationmoduleAMFixture.java and put into a package with the format package.applicationModule, where package is the application module package.

To create a business components test fixture:

In the main menu, choose File and then z.

You will create a separate project for the business components tests.
In the New Gallery, expand General, select Projects and then Java Projects, and click OK.
In the Project Name page of the Create Java Project dialog, enter a name and the directory path for the test project, and click Next.
In the Project Java Settings page, enter the package name and the source and output directories, and click Finish.
In the Applications window, double-click the application module you want to test.
In the overview editor, click the Java navigation tab and then click the Edit icon for the Java Class section.
In the Select Java Options dialog, select Generate Application Module Class, and click OK.
In the Java page of the overview editor, click the Edit icon for the Class Interface section.
In the Edit Client Interface dialog, shuttle the methods you want to test to the Selected pane, and click OK.
In the Applications window, right-click the test project you have created and choose New.
In the New Gallery, expand General, select Unit Tests and then Business Components Test Fixture, and click OK.
In the Configure Tests page of the JUnit BC4J Test Fixture wizard, select values for the following and click Next:
- Business Component Project: Select the project that has the application module you want to test.
- Application Module: Select the application module you want to test.
- Configuration: Choose a local or shared application module.
In the Summary page, verify the test fixture class and click Finish.

13.4.11 How to Update a Test Suite with all Test Cases in the Project

You update a test suite with all test cases in a project.

To update a test suite:

In a class that has a suite() method, from the main menu, choose Source > Refresh Test Suite.
Ensure that all items in the list of test cases are checked.
To update the test suite, click OK.

13.4.12 How to Run JUnit Test Suites

When your test suite has been successfully compiled you can run it.

To run a JUnit test suite:

In the Applications window, select the test suite class.
Right click it, and choose Run.

The test executes and the test runner displays the results.