API Use Reports

An API Use Report describes a set of references from one set of bundles to another set of bundles. A report can be generated using the API Use Ant Task. A user interface is provided to configure and generate a report in the External Tools dialog. To create a new use scan configuration simply double-click the API Use Report configuration type.

API Use Report Tab

The API Use Report tab allows you to configure the analysis.

The following example shows a configuration to extract all references to Eclipse bundles in a 3.4 installation.

API Use Report tab


Option

Description

Default

Analyze You can select what you want to analyze, which can be either an API baseline, target definition or a directory of bundles. You can also select to only generate HTML for an existing report. You can only select one option, with each option allowing you to configure it. I.e. you can go to the API baselines preference page to edit existing baselines if you select analyzing an API baseline. API Baseline
Analyze > API Baseline You can choose any API baseline from the combo box to analyze Default baseline or empty
Analyze > Baselines... Allows access to the API Baselines preference page to configure the baseline to analyze.  
Analyze > Target Definition You can choose any target definition from the combo box to analyze The active target definition or empty
Analyze > Targets Allows access to the Target Platform preference page to configure the target definition to analyze.  
Analyze > Directory You can enter the absolute path to a directory containing the bundles. empty
Analyze > Browse... Allows you to browse for a folder of bundles to analyze.  
Analyze > Generate HTML report for existing use scan Allows you to create a report for an existing scan and not have to perform the analysis again.  
Search for > References to Allows you to specify the name (or matching RegEx) of the bundle that you want to see references to. Consider the following example: org\.eclipse.*. In this example we are saying that we want to see all references to any bundle that starts with the name org.eclipse.. empty
Search for > API references Allows you to scan for API references. unchecked
Search for > Internal references Allows you to scan for internal references. checked
Search for > Illegal API Use Allows you to scan for illegal API usage i.e. usage of restricted API members. unchecked
Search in > Bundles matching Allows you to specify the name (or matching RegEx) of the bundle(s) that you want to scan for references from i.e. a search scope. Consider the following example: .*. In this example we are saying that we want to search in all bundles whose name matches any character sequence. The same effect can be achieved leaving the field blank. empty
Filters > Additional Filters Allows you to specify a directory of API problem filters to use during the scan.

The setting is the root directory of the .api_filters files that should be used to filter potential references found by the use scan.
The root is specified using an absolute path.
The root needs to contain the following structure:

root
 |
 +-- component name (i.e. org.eclipse.jface)
        |
        +--- .api_filters
		
empty
Filters > Browse... Opens a dialog where you can select a root filter directory. empty
Reporting > Report Type Allows you to choose between two html report formats. If Referenced bundles report (Producers) is selected the report will list all of the bundles containing the types that are being referenced in the searched bundles. If Referencing bundles report (Consumers) is selected the report will be organized to show all of the bundles in the search scope that contain references.

When switching report types, check that the References to and Bundles matching regular expressions have the correct values. When using a wildcard expression such as .* in one setting, switching to another report type often requires the wilcard being moved to the other setting to get the most useful report.

Referenced bundles report (Producers)
Reporting > Report Output Location Allows you to specify the absolute path where any generated reports should be placed. empty
Reporting > Browse... Opens a dialog where you can select the location to output any reports.  
Reporting > Clean report directory before reporting new results Allows you to clear out an existing XML report location prior to the scan reporting any results. It should be noted that this option will completely remove the specified report directory if it exists, with all child directories being recursively removed as well. unchecked
Reporting > Create HTML reports Converts all of the XML output into formatted HTML and place it in <report location>\html unchecked
Reporting > Clean HTML report location Allows you to clear out an existing HTML location prior to creating new reports. It should be noted that this option will completely remove the specified HTML directory if it exists, with all child directories being recursively removed as well. This option only enables if you select the Create HTML Reports option mentioned above. unchecked
Reporting > Open report when search completes Opens the HTML report when the analysis is complete. This option only enables if you select the Create HTML Reports option mentioned above. unchecked
Reporting > Description Allows you to enter a human-readable description for the report. empty

Patterns Tab

The Patterns tab allows you to create a variety of Regular Expression patterns to control the use analysis. There are currently three supported kinds of patterns:

  1. Archive Pattern - Allows you to specify nested archives that should be ignored during analysis.
  2. Package Pattern - Allows you to specify packages that should be API or internal without having to update your bundle manifest.
  3. Report Conversion Pattern - Allows you to create a package name regular expression to filter references taht are reported. All reported referece are filtered using their fully qualified package name.

Patterns tab


Option

Description

Default

Add... Allows you to add a new pattern. This button will start the Pattern wizard.  
Edit Allows you to edit the currently selected pattern. Only one pattern can be edited at a time.  
Remove Allows you to remove the selected pattern(s). You can remove more than one pattern at a time.  

Related tasks

Comparing to an API baseline
Setting up a baseline

Related reference

API Baselines Preferences
API Use Patterns Wizard