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.