The Clover JDeveloper Plugin allows you to instrument your Java code and view your coverage results easily from within the Oracle JDeveloper Java IDE.

Once you have downloaded the Clover JDeveloper Plugin package from http://www.cenqua.com, you can install the plugin as follows:

1. shutdown any running instances of JDeveloper
2. remove any previous versions of the the clover plugin jar from JDEVELOPER_HOME/jdev/lib/ext
3. copy CLOVER_HOME/lib/clover-jdeveloper.jar into the JDEVELOPER_HOME/jdev/lib/ext directory, and restart JDeveloper.

You will need a license to activate your plugin.

• Download your clover.license file from http://www.cenqua.com/licenses.jspa. Evaluation licenses are available free of charge.
• Place the clover.license file next to the clover-jdeveloper.jar file in the JDEVELOPER_HOME/jdev/lib/ext directory.

If you are upgrading from a previous version of the Clover JDeveloper Plugin, you will also need to do the following.

• Edit the JDEVELOPER_HOME/jdev/system.../ide.properties file, removing all of the MainWindow.Toolbar.item property references to Clover.

To uninstall the Clover JDeveloper Plugin:

1. shutdown any running instances of JDeveloper
2. delete the clover-jdeveloper.jar file from the JDEVELOPER_HOME/jdev/lib/ext directory.
3. restart JDeveloper

Add clover jar to your project classpath.

• Open the project properties "Tools | Project Properties... " or by double clicking on the project within the Navigator window.
• Go to "Profiles | Active Profile | Libraries". Create a new library and add the JDEVELOPER_HOME/jdev/lib/ext/clover-jdeveloper.jar to the libraries classpath. Add this library to your projects 'Selected Libraries'.

  (The clover jar needs to be in the classpath because it is needed at runtime when you are running your unit tests and at compile time when you are compiling instrumented source files.)

This getting started guide will take you through the steps required to generate Clover coverage for your project.

1. Ensure that you have configured your project to use Clover.
2. Enable Clover, by selecting the 'Enable Clover' check box in the "Tools | Project Properties... | Clover" interface.
3. Turn on clover instrumentation by selecting the toolbar item
4. Rebuild your project using any of the build mechanisms provided by JDeveloper.
5. Run your project by running the unit tests or some other means.
6. Refresh the latest coverage data by clicking the toolbar item.
7. View the project coverage data by selecting the toolbar item.

Code Coverage information will be available for viewing within JDeveloper after you have built and run your application. The display of coverage information within the IDE can be controlled via the toggle button in the IDE toolbar, or the "Show Coverage" menu item in the "Clover" menu.

Within the Application Navigator, you will see coverage percentages displayed next to projects, packages and source files that have been clovered. The coverage displayed at each level of the Navigator is the sum of coverage of the packages or source files below it. That is, the coverage of a package is the sum of the coverage for the files contained within the package and all sub-packages.

Within the Structure window, you can view a summary of the coverage details for the currently 'active node'. This summary information includes the coverage of methods, conditional and statements, as well as the number of lines of code, files, classes and packages associated with this summary.

In addition, the plugin can annotate the Java code with the coverage information. Green indicates that the line of source has been 'covered', red indicates it has not been 'covered', and yellow indicates that the coverage information is out of date. The tooltips indicate exactly how many times a line has been executed, or an expression has evaluated to true etc.

There are a number of menu items and toolbar actions that allow you to interact with Clover. They are as follows:

• Show Coverage When selected, coverage information will be displayed within the IDE, as decided in the previous section.
• Build with Clover. When selected, Clover will instrument your source files during the JDeveloper build cycle.
• Refresh Coverage Will force the plugin to load the latest coverage information. You will need to refresh after building or running your application.
• Delete Coverage Delete the current coverage database.
• Generate Report... Launches the report generation wizard that will take you through the steps required to generate a Pdf, Html or XML report.
• Filter Coverage... Launches a dialog to set the context filter.

Configuration options for Clover are accessible on the Clover panel of the Project Properties dialog. The first Tab on this panel provides compilation options:

Initstring

This section controls where the Clover coverage database will be stored. Select 'Automatic' to have Clover manage this location for you (relative to your project directory). Select 'User Specified' to nominate the path to the Clover coverage database. This is useful if you want to use the plugin in conjunction with an Ant build that already defines the location of the Clover coverage database.

Flush Policy

The Flush Policy controls how Clover writes coverage data to disk at runtime. See Flush Policies.

Filtering

Allows you to specify a comma separated list of set of Ant Patternsets that describe which files to include and exclude in instrumentation. These options are the same as those described in the <clover-setup> task.

Language Level

Allows you to specify which language features you would like Clover to support. If you use asserts within your code, you would need to select '1.4' or higher, if you use enums, then you need to select '1.5'.

The second Tab on the configuration panel provides viewing options;

Refresh Policy

The Refresh Policy controls how the Clover Plugin monitors the Coverage Database for new data. "Manual" is the default and means that you have to click button to refresh the coverage data. "Automatic" means that the Clover Plugin will periodically check for new coverage data for you.

Inline View

Allows you to customize where coverage data is displayed within the JDeveloper IDE. Gutter marks appear in the left hand gutter of the Java Source Editor. Inline refers to the annotations that appear directly over your source code. Overlay refers to the coverage information displayed within the Application Navigator window, and Summary refers to the coverage summary panel available within the Structure Window.

Span

Allows you to configure the span used by Clover. See Spans for more information.

The third Tab on the configuration panel provides viewing options;

Regexp Filters

The regexp filters allow you to define custom contexts to ignore when viewing coverage information.

Working with regexp filters.

• Use group of button on the right hand side to Create, Delete, Edit or Copy the selected filter.
• All new and edited regexp filters will be shown in 'blue', indicating that they are currently unavailable.
• To make a new/edited filter available, you need to delete the existing coverage database using the menu item and rebuild your project.

Block Filters

Allows you to specify contexts to ignore when viewing coverage information. For example, selecting the if context will remove if body (not the conditional) from the coverage reports.

For the sake of this example, let us assume that we want to remove all private methods from the coverage reports. How would we go about this?

• Open the configuration panel "Tools | Project Properties | Clover | Filters".
• Select Add to create a new Regexp Context Filter.
• Select Edit to open up the Regexp Edit dialog.
• Set the name to private.
• Since we are creating this filter to filter private 'methods', specify the Method type.
• We now need to define regular expression that will match all private method signatures. That is, a regexp that will match any method with the private modifier. An example of such a regexp is (.* )?private .*. Enter this regexp in the regexp field.
• You will notice that the name of this new filter appears in blue. Blue is used to indicate that the filter is either new or recently edited and therefore 'unavailable'. To make this new filter available, select from the Clover menu and recompile your project. Once active, you will notice the private filter appears in the Context Filter Dialog. You will now be able to filter private methods out of your Clover coverage calulations and reports.

The configuration panel for the source highlighting options is available in the JDeveloper preferences located at "Tools | Preferences | Clover".

Source Highlighting

The source highlighting configuration panel allows you to specify the colours used by clover when it renders coverage information in the JDeveloper editor panel. The Background colour represents the colour used to highlight each line of source code, the Gutter colour is the colour of the mark located in the editors left side gutter.

Q: Clover has caused blank actions to appear in my Main Toolbar.

A: This happens when you are upgrading to version 1.0RC1 of the plugin. To fix this, you will need to edit the JDEVELOPER_HOME/jdev/system.../ide.properties file, removing all of the MainWindow.Toolbar.item property references to Clover.