# API Deprecation Ant Task

## Purpose

This task runs a complete API analysis of an API profile relative to a baseline - looking only for members (classes, fields, methods) that have been deprecated / un-deprecated. The profile is the current state of a product under development. The profile is compared to an API baseline for deprecation changes (usually the previous release of a product).

## Usage

### Description

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

    <apitooling.apideprecation
    	baseline="..."
    	profile="..."
    	report="..."
    	excludelist="..."
    	includelist="..."
    	debug="..."
    	eefile="..."
    />

### Parameters

Attribute | Description | Required
baseline | This attribute specifies the location of the reference baseline. 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
profile | This attribute specifies the location of the current product or profile that you want to compare against the reference baseline. 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 using a structure similar to the filter root. A sub-folder is created for each component that has problems to be reported. Each sub-folder contains a file called "report.xml".
A special folder called "allNonApiBundles" is also created in this folder which also contains a file called "report.xml". This file lists all the bundles that are not using the API Tools nature.
The location is specified using an absolute path.

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. In addition, this task supports listing members in the include and exclude lists. The include list seeds the set of bundles and members to be analyzed (when omitted, all bundles and members are included), and the exclude list is then applied. Each line of the file specifies one of:

- a specific bundle name
- a specific member name
- a regular expression to match against bundle or member names (lines being with "R:")
- a comment (lines being with '#')

The location is specified using an absolute path.
Following is an example exclude list:

     # ECLIPSE MEMBERS
     org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
     # 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
     javax.servlet
     javax.servlet.jsp
     ...

The exclude list can contain regular expressions if the line starts with "R:".

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. In addition, this task supports listing members in the include and exclude lists. The include list seeds the set of bundles and members to be analyzed (when omitted, all bundles and members are included), and the exclude list is then applied. Each line of the file specifies one of:

- a specific bundle name
- a specific member name
- a regular expression to match against bundle or member names (lines being with "R:")
- a comment (lines being with '#')

The location is specified using an absolute path.
Following is an example include list:

     # ECLIPSE MEMBERS
     org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
     # 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
     javax.servlet
     javax.servlet.jsp
     ...

No

debug | Set the debug value. The possible values are: `true`, `false` 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

### Examples

     <apitooling.apideprecation
      baseline="D:\eclipse\3.4.1\eclipse"
      profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"

      report="D:\reports\xml"
      excludelist="D:\exclude_list_external.txt"
      debug="true"
     />

This will run the task creating `report.xml` files inside the folder `D:\reports\xml`. It will use the exclude list to reduce the number of problems to report.

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

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 Report Conversion Ant Task