Ant-Task für Fehler bei API-Verwendungssuchläufen

Zweck

Diese Task löst die API-Verwendungssuchläufe in einem Profil in Bezug auf eine Referenzkonfiguration auf. Sie meldet die Referenzen auf die Typen, Methoden und Felder, die zurzeit im Profil fehlen.

Verwendung

Beschreibung

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

<apitooling.apiusescanproblems
	profile="..."
	report="..."
	apiusescans="..."
	excludelist="..."
	includelist="..."
	preferences="..."
	debug="..."
/>

Parameter

Attribut Beschreibung Erforderlich
profile Dieses Attribut gibt die Position des aktuellen Produkts oder Profils an, für das die API-Verwendungssuchläufe aufgelöst werden sollen.

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. 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'.

Die Position wird mit einem absoluten Pfad angegeben.
Ja
apiusescans Dieses Attribut gibt die durch Kommas getrennte Liste von Positionen der API-Verwendungssuchläufe an, die für das Profil überprüft werden sollen.

Es kann eine Datei mit der Dateierweiterung '.zip' oder ein Verzeichnis angegeben werden, das dem API-Verwendungssuchlaufbericht entspricht. Dies ist das Verzeichnis, in dem sich der XML-Ordner im Verwendungssuchlauf befindet.
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. 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:
  • Einen bestimmten Produktpaketnamen
  • Einen regulären Ausdruck, der mit Produktpaketnamen 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:
 # 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:
  • Einen bestimmten Produktpaketnamen
  • Einen regulären Ausdruck, der mit Produktpaketnamen 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:
 # 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
 API_USE_SCAN_TYPE_SEVERITY=Error
 API_USE_SCAN_METHOD_SEVERITY=Error
 API_USE_SCAN_FIELD_SEVERITY=Error
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

Beispiele

	<apitooling.apiusescanproblems
		profile="D:\eclipse\3.7\eclipse"
		report="D:\reports\xml"
		apiusescans="D:\APIUseScan\ProductOne,D:\APIUseScan\ProductTwo"
		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 Typen, Methoden und Felder aus den Verwendungssuchläufen werden in dem Profil aufgelöst, das in D:\eclipse\3.7\eclipse angegeben ist, und die fehlenden werden berichtet. Die Task verwendet die Ausschlussliste aus der Datei D:\exclude_list_external.txt, um die Anzahl der Produktpakete zu verringern, für die Probleme zu melden sind.

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.

Zugehörige Referenzinformationen

Ant-Task für API-Analyse
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