Cette tâche exécute une recherche complète d'une ligne de base pour créer un rapport d'utilisation d'API.
L'analyse n'inclut pas les regroupements pour lesquels les utilitaires d'API ne sont pas activés.
Le nom de la tâche Ant est apitooling.apiuse. Pour qu'il puisse être utilisé, le fichier jar apitooling-ant.jar doit figurer dans le chemin d'accès aux classes Ant.
<apitooling.apiuse location="..." scopepattern="..." referencepattern="..." report="..." considerinternal="..." considerapi="..." considerillegaluse="..." apipatterns="..." internalpatterns="..." archivepatterns="..." excludelist="..." includelist="..." debug="..." />
| Attribut | Description | Obligatoire |
| emplacement |
Cet attribut spécifie l'emplacement du produit courant pour lequel rechercher l'utilisation d'API.
Il peut s'agir d'un fichier .zip, .jar, .tgz, .tar.gz ou d'un répertoire contenant un produit ou une collection de regroupements. L'emplacement est défini en utilisant un chemin absolu. |
Oui |
| scopepattern |
Cet attribut indique un masque d'expression régulière utilisé pour sélectionner les regroupements à l'emplacement indiqué qui doivent être recherchés.
Par exemple, l'instruction suivante analyse uniquement l'utilisation d'API dans les regroupements Eclipse : org.eclipse.*Ce masque doit être une expression régulière syntaxiquement correcte conforme aux spécifications définies ici. |
Non |
| referencepattern |
Cet attribut indique un masque d'expression régulière utilisé pour filtrer les résultats de la recherche. Seule l'utilisation d'API qui référence un regroupement correspondant au filtre est signalée.
Par exemple, l'instruction suivante signale uniquement l'utilisation qui référence le code dans JDT : org.eclipse.jdt.*Ce masque doit être une expression régulière syntaxiquement correcte conforme aux spécifications définies ici. |
Non |
| report | Définit l'emplacement de génération des rapports.
Une fois la tâche exécutée, les rapports sont disponibles dans ce répertoire dans une structure hiérarchique. Un sous-dossier est créé pour chaque composant ayant un autre regroupement qui y fait référence. Chaque sous-dossier contient un fichier "[bundlename].xml". Ce dossier contient également un sous-dossier "[referencing bundle name].xml" pour chaque regroupement qui fait référence au regroupement du dossier conteneur. Le dossier de regroupement de référence contient l'un des trois sous-dossiers (API, PRIVATE ou OTHER) qui contient les référence de type, de méthode et de zones de ce type. Trois autres fichiers spéciaux, "counts.xml", "not_searched.xml" et "no_apidescription.xml", sont écrits dans le répertoire des rapports ; ils contiennent des informations sur le nombre de références trouvées, les regroupements de la ligne de base qui n'ont pas fait l'objet de recherche d'informations d'utilisation et ceux qui ne contiennent pas de fichier .api_description. L'emplacement est défini en utilisant un chemin absolu. Par exemple : 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 |
Oui |
| considerinternal | Indique si les références internes doivent être prises en compte dans la recherche.
La valeur par défaut est false. |
Non |
| considerapi | Indique si les références d'API doivent être prises en compte dans la recherche.
La valeur par défaut est false. |
Non |
| considerillegaluse | Indique si les références d'utilisation d'API non autorisées doivent être prises en compte dans la recherche.
La valeur par défaut est false. |
Non |
| apipatterns | Liste de masques de nom de package (expressions régulières) séparés par des virgules à prendre en compte comme packages d'API.
Par défaut, les descriptions d'API sont utilisées dans les regroupements analysés mais elles peuvent également être utilisées pour remplacer ou ajouter des packages d'API. |
Non |
| internalpatterns | Liste de masques de nom de package (expressions régulières) séparés par des virgules à prendre en compte comme packages privés.
Par défaut, les descriptions d'API sont utilisées dans les regroupements analysés mais elles peuvent également être utilisées pour remplacer ou ajouter des packages privés. |
Non |
| archivepatterns | Liste d'identificateurs d'archive séparés par des virgules à ignorer pendant l'analyse.
Un identificateur d'archive se présente sous la forme : [id regroupement]:[chemin d'accès à l'archive]. |
Non |
| 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. La liste d'inclusion est tirée de l'ensemble de regroupements devant être analysés (en cas d'omission, tous les regroupements sont inclus), et la liste d'exclusion est appliquée. Chaque ligne du fichier indique l'un des éléments suivants :
L'emplacement est défini en utilisant un chemin absolu. L'exemple ci-dessous illustre la liste d'exclusion : # EXCLUDED BUNDLES R:org\.eclipse\..*\.doc\..* ... |
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. La liste d'inclusion est tirée de l'ensemble de regroupements devant être analysés (en cas d'omission, tous les regroupements sont inclus), et la liste d'exclusion est appliquée. Chaque ligne du fichier indique l'un des éléments suivants :
L'emplacement est défini en utilisant un chemin absolu. L'exemple ci-dessous illustre la liste d'inclusion : # INCLUDED BUNDLES R:org\.eclipse\..* ... |
Non |
| filters | Définit le répertoire racine des filtres API à utiliser pendant l'analyse d'utilisation.
L'argument est le répertoire racine des fichiers .api_filters qui doivent être utilisés pour filtrer les références. Les fichiers .api_filters indiquent les problèmes spécifiques à ignorer au cours de l'analyse d'API. Au cours de l'analyse d'utilisation, les filtres de problème sont convertis en une liste de références qui sera filtrée à partir des résultats de l'analyse d'utilisation. La racine est spécifiée en utilisant un chemin absolu. La racine doit contenir la structure suivante :
root
|
+-- component name (i.e. org.eclipse.jface)
|
+--- .api_filters
|
Non |
| debug | Définit la valeur de débogage.
Les valeurs possibles sont true, false
La valeur par défaut est false. |
Non |
<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" />
Cet exemple exécute la tâche en créant des fichiers *.xml dans le dossier /eclipse/apiuse-both/XML.
La tâche recherche tous les regroupements dans l'emplacement de produit (défini par l'expression régulière .* en recherchant toutes les références aux regroupements dont l'identificateur commence par org.eclipse (défini par l'expression régulière org\.eclipse.*).
Il utilise la liste d'exclusion qui se trouve dans le fichier D:\exclude_list_external.txt pour réduire le nombre d'incidents à signaler.
Lors de l'analyse, les fichiers classe trouvés dans l'archive /libs/contributed.jar qui se trouve dans org.eclipse.test.bundle sont ignorés.
Si le débogage est activé, un traçage de débogage apparaît dans la console Ant.

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