API Use Ant Task

Purpose

This task runs a complete search of a given baseline to create a report of API usage.

The analysis does not include bundles that are not API Tools enabled.

Usage

Description

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

Parameters

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 containing a product or a collection of bundles. The location is specified using an absolute path.	Yes
scopepattern	This attribute specifies a regular expression pattern used to select what bundles in the location will be searched. For example, the following would only scan for API usage in Eclipse bundles: org.eclipse.* The pattern must be a well-formatted regular expression as defined here.	No
referencepattern	This attribute specifies a regular expression pattern used to filter the search results. Only API usage that references a bundle matching the filter will be reported. For example, the following would only report usage that references code in JDT: org.eclipse.jdt.* 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. Three other special files are written into the report directory, which are "counts.xml", "not_searched.xml" and "no_apidescription.xml" and they contain information about the number of references found, 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" +-- "counts.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
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
filters	Set the root directory of API filters to use during the use scan. The argument is the root directory of the .api_filters files that should be used to filter references. The .api_filters files specify specific problems to ignore during api analysis. During the use scan, the problem filters will be converted to a list of references that will be filtered from the use scan results. The root is specified using an absolute path. The root needs to contain the following structure: root \| +-- component name (i.e. org.eclipse.jface) \| +--- .api_filters	No
debug	Set the debug value. The possible values are: `true`, `false` Default is `false`.	No

Examples

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

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.