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.

Related reference

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