API Use Scan Problems Ant Task

Purpose

This task resolves the API Use Scans in a profile relative to a baseline. It reports the references to the types, methods and fields which are now missing from the profile.

Usage

Description

The name of the Ant task is: apitooling.apiusescanproblems. To be used, the jar file apitooling-ant.jar has to be on the Ant classpath.

<apitooling.apiusescanproblems
	profile="..."
	report="..."
	apiusescans="..."
	excludelist="..."
	includelist="..."
	preferences="..."
	debug="..."
/>

Parameters

Attribute Description Required
profile This attribute specifies the location of the current product or profile that you want to resolved the API Use Scans against.

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.

The location is specified using an absolute path.
Yes
report Set the output location where the reports will be generated.

Once the task is completed, reports are available in this directory. A sub-folder is created for each component that has problems to be reported. Each sub-folder contains a file called "report.xml".

The location is specified using an absolute path.
Yes
apiusescans This attribute specifies the comma-separated list of the locations of the API Use Scans that you want to check against the profile.

It can be a .zip file or a directory that corresponds to the API Use Scan report. This is the directory is which you can find the XML folder in the Use Scan.
Yes
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:
 # DOC BUNDLES
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 org.eclipse.platform.doc.isv
 org.eclipse.platform.doc.user
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
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:
 # DOC BUNDLES
 org.eclipse.jdt.doc.isv
 org.eclipse.jdt.doc.user
 org.eclipse.pde.doc.user
 R:org.eclipse.platform.doc.*
 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 R:javax\..*
 ...
No
preferences Set the preferences for the task.

The preferences are used to configure problem severities. Problem severities have three possible values: Ignore, Warning, or Error. The set of problems detected is defined by corresponding problem preference keys in API tools.
The location is specified using an absolute path. If the given location doesn't exist, the preferences won't be set.
Lines starting with '#' are ignored. The format of the preferences file looks like this:
 #Thu Nov 20 17:35:06 EST 2008
 API_USE_SCAN_TYPE_SEVERITY=Error
 API_USE_SCAN_METHOD_SEVERITY=Error
 API_USE_SCAN_FIELD_SEVERITY=Error
The keys can be found in org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes.
No
debug Set the debug value.

The possible values are: true, false
Default is false.
No

Examples

	<apitooling.apiusescanproblems
		profile="D:\eclipse\3.7\eclipse"
		report="D:\reports\xml"
		apiusescans="D:\APIUseScan\ProductOne,D:\APIUseScan\ProductTwo"
		excludelist="D:\exclude_list_external.txt"
		preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs"
		debug="true"
	/>

This will run the task creating report.xml files inside the folder D:\reports\xml. The types, methods and fields from the use scans will be resolved in the profile at D:\eclipse\3.7\eclipse and the missing ones will be reported. It will use the exclude list from the file D:\exclude_list_external.txt to reduce the number of bundles for which problems to report.

Problem severities will be generated as specified by D:\tests_api\org.eclipse.pde.api.tools.prefs.

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

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