Diese Task führt eine vollständige API-Analyse eines API-Profils relativ zu einer Referenzkonfiguration aus - einschließlich einer Validierung der API-Verwendung, Binärkompatibilität und Versionsnummer des Produktpakets. Als Profil dient der aktuelle Status eines Produkts, das sich in der Entwicklung befindet. Das Profil wird mit einer API-Referenzkonfiguration hinsichtlich der Binärkompatibilität (in der Regel mit dem Vorgängerrelease eines Produkts) verglichen.
Die Analyse schließt keine Validierung von '@since'-Tags ein, da die gesamte Überprüfung für binäre Klassendateien erfolgt (die Quelle wird nicht analysiert).
Der Name der Ant-Task ist apitooling.analysis. Für ihre Verwendung muss sich die JAR-Datei apitooling-ant.jar im Ant-Klassenpfad
befinden.
<apitooling.analysis baseline="..." profile="..." report="..." filters="..." excludelist="..." includelist="..." preferences="..." debug="..." eefile="..." />
| Attribut | Beschreibung | Erforderlich |
| baseline | Dieses Attribut gibt die Position der Referenzkonfiguration an.
Es kann eine Datei mit der Dateierweiterung '.zip', '.jar', '.tgz' bzw. '.tar.gz' oder ein Verzeichnis angegeben werden, das dem Eclipse-Installationsordner entspricht. Dies ist das Verzeichnis, in dem sich die ausführbare Eclipse-Datei befindet. Die Position wird mit einem absoluten Pfad angegeben. |
Ja |
| profile | Dieses Attribut gibt die Position des aktuellen Produkts oder Profils an, das mit der Referenzkonfiguration verglichen werden soll.
Es kann eine Datei mit der Dateierweiterung '.zip', '.jar', '.tgz' bzw. '.tar.gz' oder ein Verzeichnis angegeben werden, das dem Eclipse-Installationsordner entspricht. Dies ist das Verzeichnis, in dem sich die ausführbare Eclipse-Datei befindet. Die Position wird mit einem absoluten Pfad angegeben. |
Ja |
| report | Gibt die Ausgabeposition an, in der die Berichte generiert werden.
Nach Abschluss der Task sind die Berichte in diesem Verzeichnis verfügbar. Hierbei wird eine Struktur verwendet, die dem Stammverzeichnis des Filters ähnlich ist. Für jede Komponente, für die Probleme bzw. Fehler gemeldet werden müssen, wird ein Unterordner erstellt. Jeder Unterordner enthält eine Datei namens 'report.xml'. Es wird ein besonderer Ordner namens 'allNonApiBundles' in diesem Ordner erstellt, der ebenfalls eine Datei 'report.xml' enthält. In dieser Datei werden alle Produktpakete aufgelistet, die die Gattung der API-Tools nicht verwenden. Es ist außerdem eine im Berichtsverzeichnis erstellte Datei "counts.xml" vorhanden, die eine Zusammenfassung der gefundenen Probleme enthält. Die Position wird mit einem absoluten Pfad angegeben. |
Ja |
| filters | Gibt das Stammverzeichnis der API-Filter an, die bei der Analyse verwendet werden sollen.
Das Argument ist das Stammverzeichnis der Dateien des Typs '.api_filters', die zum Filtern potenzieller Probleme bzw. Fehler verwendet werden sollen, die durch die API-Toolanalyse erstellt wurden. Das Stammverzeichnis wird mit einem absoluten Pfad angegeben. Das Stammverzeichnis muss die folgende Struktur enthalten:
stammverzeichnis
|
+-- komponentenname (d. h. org.eclipse.jface)
|
+--- .api_filters
|
Nein |
| excludelist | Gibt die Position der Ausschlussliste an.
Die Position der Ausschlussliste gibt eine Textdatei an, in der Produktpakete aufgelistet sind, die aus der Analyse ausgeschlossen werden sollen. Standardmäßig werden alle Produktpakete im Profil analysiert. Durch die Einschluss- und Ausschlusslistenattribute können Produktpakete selektiv ein- und ausgeschlossen werden. Die Einschlussliste gibt die Ausgangsgruppe der zu analysierenden Produktpakete an. (Wenn sie nicht angegeben wird, werden alle Produktpakete eingeschlossen.) Anschließend wird die Ausschlussliste auf diese Gruppe angewendet. Jede Zeile der Datei gibt einen der folgenden Informationstypen an:
Die Position wird mit einem absoluten Pfad angegeben. Das folgende Beispiel zeigt eine Ausschlussliste: # 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 R:javax\..* ... |
Nein |
| includelist | Gibt die Position der Einschlussliste an.
Die Position der Einschlussliste gibt eine Textdatei an, in der Produktpakete aufgelistet sind, die in die Analyse eingeschlossen werden sollen. Standardmäßig werden alle Produktpakete im Profil analysiert. Durch die Einschluss- und Ausschlusslistenattribute können Produktpakete selektiv ein- und ausgeschlossen werden. Die Einschlussliste gibt die Ausgangsgruppe der zu analysierenden Produktpakete an. (Wenn sie nicht angegeben wird, werden alle Produktpakete eingeschlossen.) Anschließend wird die Ausschlussliste auf diese Gruppe angewendet. Jede Zeile der Datei gibt einen der folgenden Informationstypen an:
Die Position wird mit einem absoluten Pfad angegeben. Das folgende Beispiel zeigt eine Einschlussliste: # DOC BUNDLES org.eclipse.jdt.doc.isv org.eclipse.jdt.doc.user org.eclipse.pde.doc.user R:org.eclipse.platform.doc.* # NON-ECLIPSE BUNDLES com.ibm.icu com.jcraft.jsch R:javax\..* ... |
Nein |
| preferences | Gibt die Benutzervorgaben für die Task an.
Die Benutzervorgaben werden zum Konfigurieren von Fehlerbewertungen verwendet. Für Fehlerbewertungen sind die folgenden drei Werte möglich: 'Ignorieren', 'Warnung' oder 'Fehler'. Die Gruppe der festgestellten Probleme wird in den API-Tools durch entsprechende Benutzervorgabenschlüssel für Probleme definiert. Die Position wird mit einem absoluten Pfad angegeben. Wenn die angegebene Position nicht existiert, wird die Benutzervorgabe nicht angegeben. Zeilen, die mit '#' starten, werden ignoriert. Das Format der Benutzervorgabendatei sieht wie folgt aus: #Thu Nov 20 17:35:06 EST 2008 ANNOTATION_ELEMENT_TYPE_ADDED_METHOD_WITHOUT_DEFAULT_VALUE=Ignore ANNOTATION_ELEMENT_TYPE_CHANGED_TYPE_CONVERSION=Ignore ANNOTATION_ELEMENT_TYPE_REMOVED_FIELD=Ignore ANNOTATION_ELEMENT_TYPE_REMOVED_METHOD=Ignore ANNOTATION_ELEMENT_TYPE_REMOVED_TYPE_MEMBER=Warning API_COMPONENT_ELEMENT_TYPE_REMOVED_API_TYPE=Ignore API_COMPONENT_ELEMENT_TYPE_REMOVED_TYPE=Ignore CLASS_ELEMENT_TYPE_ADDED_METHOD=Error CLASS_ELEMENT_TYPE_ADDED_RESTRICTIONS=Ignore CLASS_ELEMENT_TYPE_ADDED_TYPE_PARAMETER=Ignore CLASS_ELEMENT_TYPE_CHANGED_CONTRACTED_SUPERINTERFACES_SET=Ignore ...Die Schlüssel befinden sich in 'org.eclipse.pde.api.tools.internal.provisional.problems.IApiProblemTypes'. |
Nein |
| debug | Gibt den Wert für die Debugfunktion an.
Folgende Werte sind möglich: true und false.
Der Standardwert ist false.
|
Nein |
| eefile | Gibt die Ausführungsumgebungsdatei an, die verwendet werden soll.
Standardmäßig wird eine Ausführungsumgebungsdatei verwendet, die einer JavaSE-1.6-Ausführungsumgebung entspricht. Das Format der Datei wird auf dieser Wiki-Seite mit Beschreibungen der Ausführungsumgebung erläutert. Die Datei wird mit einem absoluten Pfad angegeben. |
Nein |
<apitooling.analysis baseline="D:\eclipse\3.4.1\eclipse" profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz" report="D:\reports\xml" filters="D:\filters" excludelist="D:\exclude_list_external.txt" preferences="D:\tests_api\org.eclipse.pde.api.tools.prefs" debug="true" />
Hierdurch wird die Task ausgeführt, durch die report.xml-Dateien im Ordner D:\reports\xml erstellt werden.
Die Task verwendet die Ausschlussliste D:\exclude_list_external.txt und die Dateien des Typs .api_filter im Verzeichnis D:\filters, um die Anzahl der zu meldenden Probleme bzw. Fehler zu senken.
Fehlerbewertungen werden wie durch D:\tests_api\org.eclipse.pde.api.tools.prefs angegeben generiert.
Da die Debugfunktion aktiviert ist, wird in der Ant-Konsole die Tracefunktion für die Fehlerbehebung angezeigt.

Ant-Task für API-Freeze
Ant-Task für Dateigenerierung
Ant-Task für API-Verwendung
Ant-Task für Analyseberichtskonvertierung
Ant-Task für API-Freeze-Berichtskonvertierung
Ant-Task für API-Verwendungsberichtskonvertierung
Ant-Task für eingestellte API-Unterstützung
Ant-Task für Konvertierung von Berichten zu eingestellter API-Unterstützung