# Pluggable API Use Ant Task

## Purpose

This task runs a complete search of a given baseline to determine a producer-centric report of API usage and report those results to the supplied `IApiSearchReporter`.

The analysis does not include bundles that are not API Tools enabled by default.

## Usage

### Description

The name of the ant task is: `apitooling.pluggableapiuse`. To be used, the jar file `apitooling-ant.jar` and the jar file for the database driver you wish to use must to be on the ant classpath.

    	<apitooling.apiusedb
    		baseline="..."
    		scope="..."
    		reporterclass="..."
    		proceedonerror="..."
    		includenonapiprojects="..."
    		includesystemlibraries="..."
    		considerinternal="..."
    		considerapi="..."
    		eefile="..."
    		excludelist="..."
    		debug="..."
    	/>

### Parameters

Attribute | Description | Required
baseline | This attribute specifies the location of the current product or profile that you want to search for API usage to. It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to a collection of bundles. The location is specified using an absolute path. | Yes
scope | This attribute specifies the location of the current product or baseline that you want to search against for API usage. It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to a collection of bundles. If no scope is provided the baseline will act as itself and the search scope. The location is specified using an absolute path. | No
proceedonerror | If the use search should include bundles that have resolution errors in the scan. Default is `false`. | No
includenonapiprojects | If non-API enabled projects should be allowed in the search scope. Default is `false`. | No
includesystemlibraries | If system libraries should be allowed in the search scope. Default is `false`. | No
reporterclass | This attribute specifies the package-qualified name of the class that should be loaded and have search results reported to it. The class must implement `IApiSearchReporter` and must appear on the Ant classpath with any required classes. For example `org.eclipse.a.b.c.MyReporter`. | Yes
considerinternal | If internal references should be considered during the search. Default is `false`. | No
considerapi | If API references should be considered during the search. Default is `false`. | No
eefile | Set the execution environment file to use. By default, an execution environment file corresponding to a JavaSE-1.6 execution environment is used. The format of the file is described in this wiki page. The file is specified using an absolute path. | No

excludelist

Set the exclude list location.
The exclude list is used to know what bundles should excluded from the scope during a search. The lines that start with '#' are ignored from the excluded elements.
Regular expressions can be used in the listing but must be prefixed with 'R:'. For example `R:org.eclipse.*`
The location is specified using an absolute path.
The format of the exclude list file looks like this:

     # DOC BUNDLES
     R:org.eclipse.*.doc.*

     # NON-ECLIPSE BUNDLES
     com.ibm.icu
     com.jcraft.jsch
     javax.servlet
     javax.servlet.jsp
     ...

No

debug | Set the debug value. The possible values are: `true`, `false` Default is `false`. | No

### Examples

    	<apitooling.apiusedb
    		baseline="/eclipse/eclipse.tar.gz"
    		scope="/eclipse/jdt_only.tar.gz"
    		proceedonerror="true"
    		includenonapiprojects="false"
    		includesystemlibraries="false"
    		reporterclass="org.eclipse.a.b.c.MyReporter"
    		considerinternal="true"
    		considerapi="true"
    		eefile=""
    		excludelist="/eclipse/excludelist.txt"
    		debug="true"
    	/>

This will run the task writing results out to the given search reporter class. It will use the exclude list located in `/eclipse/excludelist.txt` to reduce the scope of the search.

If debug is enabled, some debug tracing will show up in the ant console.

API Tools API Freeze Ant Task
API Tools File Generation Ant Task
API Tools Analysis Report Conversion Ant Task
API Tools API Freeze Report Conversion Ant Task
API Tools API Use Report Conversion Ant Task