This task takes a given API use scan and tries to re-resolve it within a given candidate product release and reports any unresolved references.
The name of the Ant task is: apitooling.apimigration
. To be used, the jar file apitooling-ant.jar
has to be on the Ant
classpath.
<apitooling.apimigration candidate="..." usescan="..." scopepattern="..." referencepattern="..." report="..." debug="..." />
Attribute | Description | Required |
candidate | This attribute specifies the product you want to use as the migration candidate.
It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to the Eclipse installation folder. This is the directory is which you can find the Eclipse executable. |
Yes |
usescan | This attribute specifies the product use scan you want to compare to the migration candidate.
The usescan is specified using an absolute path to the root of the use scan. |
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 |
debug | Set the debug value.
The possible values are: true , false
Default is false . |
No |
<apitooling.apimigration candidate="/eclipse/sdk3.5" usescan="/eclipse/scans/sdk3.4" scopepattern=".*" referencepattern="org\.eclipse.*" report="/eclipse/apimigration/xml" debug="true" />
This will run the task creating *.xml
files inside the folder /eclipse/apimigration/xml
.
The task will re-resolve all references in the usescan
location - defined by the regular expression .*
- against
the candidate product whose identifier begins with org.eclipse (defined by the org\.eclipse.*
regular expression).
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
API Use Migration Report Conversion Ant Task