API Use Migration Ant Task

Purpose

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.

Usage

Description

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="..."
	excludelist="..."
	includelist="..."
	report="..."
	debug="..."
 />

Parameters

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
excludelist	Set the exclude list location. The exclude list location specifies a text file listing bundles to be excluded from the analysis. By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, all bundles are included), and the exclude list is then applied. Each line of the file specifies one of: a specific bundle name a regular expression to match against bundle names (lines being with "R:") a comment (lines being with '#') The location is specified using an absolute path. Following is an example exclude list: # EXCLUDED BUNDLES R:org\.eclipse\..\.doc\.. ...	No
includelist	Set the include list location. The include list location specifies a text file listing bundles to be included in the analysis. By default all bundles in the profile are analyzed. The include and exclude list attributes can be used to selectively include and exclude bundles. The include list seeds the set of bundles to be analyzed (when omitted, all bundles are included), and the exclude list is then applied. Each line of the file specifies one of: a specific bundle name a regular expression to match against bundle names (lines being with "R:") a comment (lines being with '#') The location is specified using an absolute path. Following is an example include list: # INCLUDED BUNDLES R:org\.eclipse\..* ...	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

Examples

 <apitooling.apimigration
  candidate="/eclipse/sdk3.5"
  usescan="/eclipse/scans/sdk3.4"

  scopepattern=".*"
  referencepattern="org\.eclipse.*"
  excludelist="D:\exclude_list_external.txt"
  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). It will use the exclude list file located in D:\exclude_list_external.txt to reduce the number of problems to report.

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