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