Friday, February 4, 2011

Self help with API Tooling Reports (Part II): Generating the API Use report using Ant Task

The API Use report can also be generated using Ant tasks. See Eclipse help documentation for it here. If you already know how to run ant tasks in Eclipse, skip the rest of it.

1. Writing Ant script
I assume you know a bit of Ant already. If not, stop and step over to Ant Tutorial.
Create a new File and lets call it GenerateApiUseReport.xml. It will open in default text editor. Close it and Open it with Ant Editor (use right click on file and select 'Open With' -> 'Other...')
Now write this in the file.



The parameters match to the UI we discussed before.
Ant Parameters                UI
location                       <=> Analyze
scopepattern              <=> Bundles matching
referencepattern      <=> References to
report                           <=> Report Output Location
considerinternal       <=> Internal references
considerapi                 <=> API references
considerillegaluse    <=> Illegal API Use

These two are not in UI
archivepatterns - Its exclude filter. It will be a comma-separated list with the format <bundle-id>:<relative-path-to-jar>

debug - Supplying a "true" will make the apitooling.apiuse ant task give out all the debug trace information. This might be helpful if for some reason the results are not expected and you need to investigate. Since default value is false, I would recommend leaving it out until you need it and know what you are doing.

2. Running the script
This is simple. You have to create a new Ant Build launch config from the External Tools Configuration wizard. But why do it when there is a shortcut. Just right-click in the ant editor and select 'Run As' -> '2. ant Build...'. This will automatically create an Ant Build launch config for you and open it. It will look like this


Hit the Run to execute the script. You can open this again from External Tools configuration wizard.

3. Generating HTML reports
The apitooling.apiuse ant task only generating the XML report. For generating the HTML reports we need to invoke the apitooling.apiuse_reportconversion task. The parameters are very simple. See the documentation here.

Since we would want to do this along with the report generation only. We can add this to same Ant script and
make it look like this


 
  
  
 

Thursday, February 3, 2011

Self help with API Tooling Reports (Part I): Generating the API Use report

API Tools is part of Plug-in Development Environment. It provides tooling support for tracking and managing your APIs and dependencies and can generate various reports. The Eclipse help discusses here about how to set it up.

What we will discuss here is how to generate various reports and making sense out of them.

Generating the API Use report

API Use report is the simplest of the report. It tells what APIs are referenced (used) by a given profile. A profile can be an API Baseline, a Target Definition or a directory containing an Eclipse product or just some plug-ins.

PDE provides an External Tools configuration wizard to run this report. The wizards can be launched from the Run menu -> External Tools -> External Tools Configurations...

This will open the External Tools Configurations wizard. Select 'API Use Report' from the left pane and press the 'New' launch configuration button.

The snapshot below shows the settings for an RCP product.


Analyze
You can choose an API Baseline, a Target Definition or a directory to run the report on. The report is a set of XML files. To make it human readable, there is an option to generate HTML report out of any existing API Use report.

Search For
Here you control what to look out for. The 'References to' takes a regular expression which will be used to match the APIs source. In this example the report will lookout only for the API originating out of bundles whose name starts with 'org.eclipse.'
API references: The APIs used in your product
Internal references: Marks the non-API - one coming from internal packages.
Illegal API Use: Usage that breaks the restrictions marked using JavaDoc tags.

Search In
This controls the search scope. The APIs references will be searched only in the plug-ins that match the regex provided here,

Reporting
This is self explanatory. The report will be churned out as a hierarchy of.folders and XMLs in the output location. And if checked for 'Create HTML reports', they will be generated too. The report is saved inside the folder 'XML' in the report output location. While the HTML reports are inside the folder named 'HTML'.

Wednesday, February 2, 2011

Self help with API Tooling Reports (Part III): Understanding the API Use Report

API Tooling reports are collection of XML files. A typical API Use Scan report will look is like this

XML
│   meta.xml
│   not_searched.xml

├───plugin.a.b.c (1.0.0.201101280335)
│   └───com.example.myrcpproduct (1.0.0.201101280335)
│       ├───API
│       │       method_references.xml
│       │       type_references.xml
│       │
│       ├───ILLEGAL_API
│       │       type_references.xml
│       │
│       └───PRIVATE_PERMISSIBLE
│               method_references.xml
│               type_references.xml

├───plugin.x.y.x (1.3.0.v20100512)
│   └───com.example.myrcpproduct (1.0.0.201101280335)
│       ├───API
│       │       method_references.xml
│       │       type_references.xml
...       ...
...

XML folder is where the report is generated

meta.xml contains the report parameters - the regex filters and locations, etc

not_searched.xml is the list of plug-in not looked into and why.

The XML folder will also contain a bunch of folders whose names are plug-in id (with version) whose API are referenced (used). These folders will again have sub-folder named as the plug-id id (with version) which references those APIs. The usage (or violation) is stored  is XML files under their respective folders.

This structure is very technical and for sparing you the trouble of understanding it, the report can be converted to HTML files. So it will be more useful to understand them.

Example API Use HTML report


The report has three sections

Scan Details will show the parameters used for generating the report. This information comes from meta.xml mentioned above.


Additional Bundle Information gives the link to the bundles that were not searched. The color legends are self-explanatory

References section is a table detailing the bundles who are referenced (used) along with the number of references of different types. A reference is a usage of a type, method or field.

  • API - any public reference
  • Internal - any reference from an internal package
  • Internal-Permissible - any reference from an internal package but visible to the consuming (or referencing) bundle due to x-friends marking in manifest.
  • Fragment-Permissible - same as Internal-Permissible but from fragment bundles
  • Illegal - references which violates the API restrictions placed using JavaDoc tags.
Each bundle name is a hyper-link that would open the details for than bundle. The details for org.eclipse.apitest would look like this


Opening the details shows the list of the Referenced Types (types being used). Each type can be opened (follow the hyper-link) to see each member and visibility details.


This way you can find of each usage - valid or otherwise.

The other API Tooling reports too are structured in similar hierarchy. However, with API Use Scans you can do more ... so stay tuned for more.