Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Platform Plug-in Development Environment Guide
Previous Page Home Next Page

API Use Ant Task

Purpose

This task runs a complete search of a given baseline to determine a producer-centric 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
		baseline="..."
		scope="..."
		proceedonerror="..."
		report="..."
		includenonapiprojects="..."
		includesystemlibraries="..."
		considerinternal="..."
		considerapi="..."
		eefile="..."
		excludelist="..."
		debug="..."
	/>

Parameters

Attribute Description Required
baseline This attribute specifies the location of the current product or baseline that you want to search for API usage to.

It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to a collection of bundles.

The location is specified using an absolute path.
Yes
scope This attribute specifies the location of the current product or baseline that you want to search against for API usage.

It can be a .zip, .jar, .tgz, .tar.gz file, or a directory that corresponds to a collection of bundles. If no scope is provided the baseline will act as itself and the search scope.

The location is specified using an absolute path.
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
proceedonerror If the use search should try to continue if an error is encountered.

Default is false.
No
includenonapiprojects If non-API enabled projects should be allowed in the search scope.

Default is false.
No
includesystemlibraries If system libraries should be allowed in the search scope.

Default is false.
No
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
eefile Set the execution environment file to use.

By default, an execution environment file corresponding to a JavaSE-1.6 execution environment is used.

The format of the file is described in this wiki page.

The file is specified using an absolute path.
No
excludelist Set the exclude list location.

The exclude list is used to know what bundles should excluded from the search scope during a search. The lines that start with '#' are ignored from the excluded elements.

Regular expressions can be used in the listing but must be prefixed with 'R:'. For example R:org.eclipse.*
The location is specified using an absolute path.
The format of the exclude list file looks like this:
 # DOC BUNDLES
 R:org.eclipse.*.doc.*

 # NON-ECLIPSE BUNDLES
 com.ibm.icu
 com.jcraft.jsch
 javax.servlet
 javax.servlet.jsp
 ...
No
debug Set the debug value.

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

Examples

	
<apitooling.apiuse
		baseline="/eclipse/eclipse.tar.gz"
		scope="/eclipse/jdt_only.tar.gz"
		proceedonerror="true"
		includenonapiprojects="false"
		includesystemlibraries="false"
		report="/eclipse/apiuse-both/XML"
		considerinternal="true"
		considerapi="true"
		eefile=""
		excludelist="/eclipse/excludelist.txt"
		debug="true"
	/>

This will run the task creating *.xml files inside the folder /eclipse/apiuse-both/XML. It will use the exclude list located in /eclipse/excludelist.txt to reduce the scope of the search.

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

Related reference

API Tools API Freeze Ant Task
API Tools Pluggable API Use Ant Task
API Tools File Generation Ant Task
API Tools Analysis Report Conversion Ant Task
API Tools API Freeze Report Conversion Ant Task
API Tools API Use Report Conversion Ant Task


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire