Tâche Ant de dépréciation d'API

Objectif

Cette tâche exécute une analyse d'API complète pour un profil d'API par rapport à une version de référence ; elle recherche uniquement les membres (classes, zones, méthodes) qui ont été dépréciées ou dont la dépréciation a été annulée. Le profil est l'état en cours d'un produit en cours de développement. Il est comparé à une version de référence d'API pour détecter les modifications de dépréciation (en général, l'édition précédente d'un produit).

Syntaxe

Description

Le nom de la tâche Ant est apitooling.apideprecation. Pour qu'il puisse être utilisé, le fichier jar apitooling-ant.jar doit figurer dans le chemin d'accès aux classes Ant.

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

Paramètres

Attribut Description Obligatoire
baseline Cet attribut définit l'emplacement de la ligne de base de référence.

Il peut s'agir d'un fichier .zip, .jar, .tgz, .tar.gz ou d'un répertoire qui correspond au dossier d'installation Eclipse. Il s'agit du répertoire dans lequel se trouve l'exécutable Eclipse.

L'emplacement est défini en utilisant un chemin absolu.
Oui
profile Cet attribut définit l'emplacement du produit ou du profil en cours à comparer à la ligne de base de référence.

Il peut s'agir d'un fichier .zip, .jar, .tgz, .tar.gz ou d'un répertoire qui correspond au dossier d'installation Eclipse. Il s'agit du répertoire dans lequel se trouve l'exécutable Eclipse.

L'emplacement est défini en utilisant un chemin absolu.
Oui
report Définit l'emplacement de génération des rapports.

A la fin de la tâche, les rapports sont disponibles dans ce répertoire en utilisant une structure similaire à la racine des filtres. Un sous-dossier est créé pour chaque composant pour lequel des incidents doivent être signalés. Chaque sous-dossier contient un fichier "report.xml".

Le dossier spécial "allNonApiBundles" est également créé dans ce dossier qui contient également un fichier "report.xml". Ce fichier répertorie tous les regroupements qui n'utilisent pas la nature d'utilitaire d'API.

L'emplacement est défini en utilisant un chemin absolu.
Oui
excludelist Définit l'emplacement de la liste d'exclusion.

L'emplacement de la liste d'exclusion indique les regroupements de fichier texte devant être exclus de l'analyse. Par défaut, tous les regroupements dans le profil sont analysés. Les attributs de liste d'inclusion et d'exclusion peuvent être utilisés pour inclure et exclure des regroupements de manière sélective. De plus, cette tâche prend en charge l'affichage de la liste des membres dans les listes d'inclusion et d'exclusion. La liste d'inclusion est tirée de l'ensemble de regroupements et de membres devant être analysés (en cas d'omission, tous les regroupements et membres sont inclus), et la liste d'exclusion est appliquée. Chaque ligne du fichier indique l'un des éléments suivants :
  • un nom de regroupement spécifique
  • un nom de membre spécifique
  • une expression régulière devant correspondre aux noms de regroupements ou de membres (lignes associées à "R:")
  • un commentaire (lignes associées à '#')

L'emplacement est défini en utilisant un chemin absolu.
L'exemple ci-dessous illustre la liste d'exclusion :
 # 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
 ...
La liste d'exclusion peut contenir des expressions régulières si la ligne commence par "R:".
Non
includelist Définit l'emplacement de la liste d'inclusion.

L'emplacement de la liste d'inclusion indique un fichier texte répertoriant les regroupements à inclure dans l'analyse. Par défaut, tous les regroupements dans le profil sont analysés. Les attributs de liste d'inclusion et d'exclusion peuvent être utilisés pour inclure et exclure des regroupements de manière sélective. De plus, cette tâche prend en charge l'affichage de la liste des membres dans les listes d'inclusion et d'exclusion. La liste d'inclusion est tirée de l'ensemble de regroupements et de membres devant être analysés (en cas d'omission, tous les regroupements et membres sont inclus), et la liste d'exclusion est appliquée. Chaque ligne du fichier indique l'un des éléments suivants :
  • un nom de regroupement spécifique
  • un nom de membre spécifique
  • une expression régulière devant correspondre aux noms de regroupements ou de membres (lignes associées à "R:")
  • un commentaire (lignes associées à '#')

L'emplacement est défini en utilisant un chemin absolu.
L'exemple ci-dessous illustre la liste d'inclusion :
 # 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
 ...
Non
debug Définit la valeur de débogage.

Les valeurs possibles sont true, false
La valeur par défaut est false.
Non
eefile Définit le fichier d'environnement d'exécution à utiliser.

Par défaut le fichier d'environnement d'exécution correspondant à un environnement d'exécution JavaSE-1.6 est utilisé.

Le format du fichier est décrit dans cette page wiki.

Le fichier est défini en utilisant un chemin absolu.
Non

Exemples

 <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"
 />

Cet exemple permet d'exécuter la tâche en créant des fichiers report.xml dans le dossier D:\reports\xml. Il utilise la liste d'exclusion afin de réduire le nombre d'incidents à signaler.

Etant donné que le débogage est activé, un traçage de débogage apparaît dans la console Ant.

Référence connexe

Tâche Ant de gel d'API
Tâche Ant de génération de fichier
Tâche Ant d'utilisation d'API
Tâche Ant de conversion de rapport d'analyse
Tâche Ant de conversion de rapport de gel d'API
Tâche Ant de conversion de rapport d'utilisation d'API
Tâche Ant de conversion de rapport de dépréciation d'API