Ant-Task für API-Freeze

Zweck

Diese Task identifiziert Anwendungsprogrammierschnittstellen (APIs), die relativ zu einer API-Referenzkonfiguration hinzugefügt, geändert oder entfernt wurden. Aufgabe dieser Task ist es sicherzustellen, dass nach einem API-Freeze keine weiteren Änderungen an der API vorgenommen werden.

Verwendung

Beschreibung

Der Name der Ant-Task ist apitooling.apifreeze. Für ihre Verwendung muss sich die JAR-Datei apitooling-ant.jar im Ant-Klassenpfad befinden.

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

Parameter

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 den Namen der Berichtsdatei an, die generiert werden soll.

Er sollte mit einem absoluten Pfad angegeben werden.
Dies muss eine Dateiposition sein, kein Verzeichnis. 		Ja
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. Darüber hinaus unterstützt diese Task das Auflisten von Membern in der Einschluss- und der Ausschlussliste. Die Einschlussliste gibt die Ausgangsgruppe der zu analysierenden Produktpakete an. (Wenn sie nicht angegeben wird, werden alle Produktpakete und Member eingeschlossen.) Anschließend wird die Ausschlussliste auf diese Gruppe angewendet. Jede Zeile der Datei gibt einen der folgenden Informationstypen an:
  • Einen bestimmten Produktpaketnamen
  • Einen bestimmten Membernamen
  • Einen regulären Ausdruck, der mit Produktpaketnamen oder Membernamen abgeglichen wird (Zeilen, die mit "R:" beginnen)
  • Einen Kommentar (Zeilen, die mit '#' beginnen)

Die Position wird mit einem absoluten Pfad angegeben.
Das folgende Beispiel zeigt eine Ausschlussliste: 
# ECLIPSE MEMBERS
org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
# ECLIPSE BUNDLES
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_ERROR
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_WARNING
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_ELCL_COLLAPSEALL
# NON-ECLIPSE BUNDLES
com.ibm.icu
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. Darüber hinaus unterstützt diese Task das Auflisten von Membern in der Einschluss- und der Ausschlussliste. Die Einschlussliste gibt die Ausgangsgruppe der zu analysierenden Produktpakete an. (Wenn sie nicht angegeben wird, werden alle Produktpakete und Member eingeschlossen.) Anschließend wird die Ausschlussliste auf diese Gruppe angewendet. Jede Zeile der Datei gibt einen der folgenden Informationstypen an:
  • Einen bestimmten Produktpaketnamen
  • Einen bestimmten Membernamen
  • Einen regulären Ausdruck, der mit Produktpaketnamen oder Membernamen abgeglichen wird (Zeilen, die mit "R:" beginnen)
  • Einen Kommentar (Zeilen, die mit '#' beginnen)

Die Position wird mit einem absoluten Pfad angegeben.
Das folgende Beispiel zeigt eine Einschlussliste: 
# ECLIPSE MEMBERS
org.eclipse.jface.databinding_1.2.0:org.eclipse.jface.databinding.viewers.ObservableListContentProvider#getElements(Ljava/lang/Object;)[Ljava/lang/Object;
# ECLIPSE BUNDLES
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_ERROR
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_DEC_FIELD_WARNING
org.eclipse.ui.workbench_3.4.0:org.eclipse.ui.ISharedImages#IMG_ELCL_COLLAPSEALL
# NON-ECLIPSE BUNDLES
com.ibm.icu
R:javax\..*
...
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
processunresolvedbundles Legt fest, ob Produktpakete mit Auflöserfehlern analysiert werden sollen.

Wird dieses Attribut definiert, werden Produktpakete mit Auflöserfehlern (wie beispielsweise fehlenden Abhängigkeiten) in die Analyse eingeschlossen. Die Fehler können sich auf die Ergebnisse auswirken; daher wird eine Liste der Auflöserfehler in die XML-Ausgabe eingeschlossen, und während der Berichtskonvertierung in HTML werden Warnungen hinzugefügt.

Folgende Werte sind möglich: true und false.
Der Standardwert ist true. 		Nein

Beispiele

	<apitooling.apifreeze
		baseline="D:\eclipse\3.4.1\eclipse"
		profile="D:\eclipse-SDK-I20081118-0800-linux-gtk.tar.gz"
		report="D:\report\report.xml"
		excludelist="D:\exclude_list.txt"
		debug="true"
	/>

Hierdurch wird die Task ausgeführt, die report.xml im Ordner D:\report erstellt. Die Task verwendet die Ausschlussliste D:\exclude_list_external.txt, um die Anzahl der zu meldenden Probleme bzw. Fehler zu senken.

Da die Debugfunktion aktiviert ist, wird in der Ant-Konsole die Tracefunktion für die Fehlerbehebung angezeigt.

Zugehörige Referenzinformationen

Ant-Task für Analyse
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 eingestellte API-Unterstützung
Ant-Task für Konvertierung von Berichten zu eingestellter API-Unterstützung
Ant-Task für API-Verwendungsberichtskonvertierung