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