This task runs a complete search of a given baseline to determine a producer-centric report of API usage.
The analysis does not include bundles that are not API Tools enabled.
The name of the Ant task is: apitooling.apiuse
. To be used, the jar file apitooling-ant.jar
has to be on the Ant
classpath.
<apitooling.apiuse location="..." scopepattern="..." referencepattern="..." report="..." considerinternal="..." considerapi="..." considerillegaluse="..." apipatterns="..." internalpatterns="..." archivepatterns="..." debug="..." />
Attribute | Description | Required |
location |
This attribute specifies the location of the current product you want to search for API usage.
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 |
scopepattern |
This attribute specifies the regular expression pattern used to build the scope of elements to search for
references from in the product location.
The pattern must be a well-formatted regular expression as defined here. |
No |
referencepattern |
Set the regular expression pattern used to build the scope of elements to search for
references to in the product location.
The pattern must be a well-formatted regular expression as defined here. |
No |
report | Set the output location where the reports will be generated.
Once the task is completed, reports are available in this directory using a hierarchical structure. A sub-folder is created for each component that has another bundle that references it. Each sub-folder contains a file called "[bundlename].xml". Within this folder is another sub-folder (named "[referencing bundle name].xml") for each bundle that references the bundle of the containing folder. Inside the referencing bundle folder is one of three sub-folders (API, PRIVATE or OTHER) which contain type, method or field references of that kind. Two other special files are written into the report directory, which are "not_searched.xml" and "no_apidescription.xml" and they contain information about bundles from the baseline that were not search for usage information and those that did not have an .api_description files in them, respectively. The location is specified using an absolute path. For example: root | +-- "not_searched.xml" +-- "no_apidescription.xml" +-- bundle name with usage | +--referencing bundle name | +-- [API or PRIVATE or OTHER] | +--[type_ or method_ or field_]references.xml |
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 |
considerillegaluse | If illegal API use references should be considered during the search.
Default is false . |
No |
apipatterns | A comma separated list of package name patterns (regular expressions) to consider as API packages.
By default API descriptions are used in the scanned bundles, but this can be used to override or add API packages. |
No |
internalpatterns | A comma separated list of package name patterns (regular expressions) to consider as private packages.
By default API descriptions are used in the scanned bundles, but this can be used to override or add private packages. |
No |
archivepatterns | A comma separated list of archive identifiers to ignore during the scan.
An archive identifier is of the form: [bundle id]:[path to archive] . |
No |
debug | Set the debug value.
The possible values are: true , false
Default is false . |
No |
<apitooling.apiuse location="/eclipse/eclipse.tar.gz" scopepattern=".*" referencepattern="org\.eclipse.*" report="/eclipse/apiuse-both/XML" considerinternal="true" considerapi="true" considerillegaluse="true" archivepatterns="org.eclipse.test.bundle:/libs/contributed.jar" debug="true" />
This will run the task creating *.xml
files inside the folder /eclipse/apiuse-both/XML
.
The task will search all bundles in the product location - defined by the regular expression .*
- searching
for all references to any bundles whose identifier begins with org.eclipse (defined by the org\.eclipse.*
regular expression).
While scanning, any class files found in the /libs/contributed.jar archive inside org.eclipse.test.bundle will be ignored.
If debug is enabled, some debug tracing will show up in the Ant console.
API Freeze Ant Task
File Generation Ant Task
Analysis Report Conversion Ant Task
API Freeze Report Conversion Ant Task
API Deprecation Ant Task
API Deprecation Report Conversion Ant Task
API Use Report Conversion Ant Task