Ant-Task für API-Verwendung

Zweck

Diese Task führt eine vollständige Suche in einer angegebenen Referenzkonfiguration durch, um einen Bericht zur API-Verwendung zu erstellen.

Die Analyse schließt keine Produktpakete ein, die nicht für API-Tools aktiviert sind.

Verwendung

Beschreibung

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

<apitooling.apiuse
	location="..."
	scopepattern="..."
	referencepattern="..."
	report="..."
	considerinternal="..."
	considerapi="..."
	considerillegaluse="..."
	apipatterns="..."
	internalpatterns="..."
	archivepatterns="..."
	excludelist="..."
	includelist="..."	
	debug="..."
/>

Parameter

Attribut Beschreibung Erforderlich
location Dieses Attribut gibt die Position des aktuellen Produkts an, das bezüglich der API-Verwendung durchsucht werden soll.

Es kann eine Datei mit der Dateierweiterung '.zip', '.jar', '.tgz' bzw. '.tar.gz' oder ein Verzeichnis angegeben werden, das ein Produkt oder eine Sammlung von Produktpaketen enthält.

Die Position wird mit einem absoluten Pfad angegeben.
Ja
scopepattern Dieses Attribut gibt ein Muster eines regulären Ausdrucks an, mit dem die Produktpakete ausgewählt werden, die an der Position durchsucht werden.

Durch die folgende Angabe würde zum Beispiel nur nach der API-Verwendung in Eclipse-Produktpaketen gesucht:
org.eclipse.*
Bei diesem Muster muss es sich um einen ordnungsgemäß formatierten regulären Ausdruck handeln, der der Definition entspricht, die Sie hier finden.
Nein
referencepattern Dieses Attribut gibt ein Muster eines regulären Ausdrucks an, mit dem die Suchergebnisse gefiltert werden. Es wird nur die API-Verwendung gemeldet, die ein Produktpaket referenziert, das dem Filter entspricht.

Durch die folgende Angabe würde zum Beispiel nur die Verwendung gemeldet, die Code in JDT referenziert:
org.eclipse.jdt.*
Bei diesem Muster muss es sich um einen ordnungsgemäß formatierten regulären Ausdruck handeln, der der Definition entspricht, die Sie hier finden.
Nein
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 hierarchische Struktur verwendet. Für jede Komponente, auf die ein anderes Produktpaket verweist, wird ein Unterordner erstellt. Jeder Unterordner enthält eine Datei namens '[name_des_produktpakets].xml'. Dieser Ordner enthält für jedes Produktpaket, das auf das Produktpaket im übergeordneten Ordner verweist, einen weiteren Unterordner (namens "[name_des_referenzierenden_produktpakets].xml"). Im Ordner des referenzierenden Produktpakets befindet sich einer von drei Unterordnern (namens (API, PRIVATE oder OTHER), die Typ, Methode oder Feldverweise dieses Typs enthalten.

Außerdem werden drei weitere besondere Dateien in das Berichtsverzeichnis geschrieben: "counts.xml", "not_searched.xml" und "no_apidescription.xml". Diese Dateien enthalten Informationen zur Anzahl gefundener Referenzen, zu Produktpaketen der Referenzkonfiguration, die nicht nach Informationen zur Verwendung durchsucht wurden, bzw. zu Produktpaketen, die zum Zeitpunkt der Suche keine Dateien des Typs '.api_description' enthielten.

Die Position wird mit einem absoluten Pfad angegeben.

Beispiel:
  Stammverzeichnis
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- "counts.xml"
   +-- Produktpaketname mit Verwendung
   		|
   		+--referenzierender Produktpaketname
   			|
   			+-- [API oder PRIVATE oder OTHER]
   				|
   				+--[type_ oder method_ oder field_]references.xml
Ja
considerinternal Gibt an, ob interne Referenzen (Verweise) bei der Suche berücksichtigt werden sollen.

Der Standardwert ist false.
Nein
considerapi Gibt an, ob API-Verweise bei der Suche berücksichtigt werden sollen.

Der Standardwert ist false.
Nein
considerillegaluse Gibt an, ob unzulässige API-Verwendungsverweise bei der Suche berücksichtigt werden sollen.

Der Standardwert ist false.
Nein
apipatterns Eine durch Kommas getrennte Liste mit Paketnamensmustern (regulären Ausdrücken), die als API-Pakete berücksichtigt werden sollen.

Standardmäßig werden API-Beschreibungen in den durchsuchten Produktpaketen verwendet. Die Angaben hier können jedoch verwendet werden, um API-Pakete zu überschreiben oder hinzuzufügen.
Nein
internalpatterns Eine durch Kommas getrennte Liste mit Paketnamensmustern (regulären Ausdrücken), die als private Pakete berücksichtigt werden sollen.

Standardmäßig werden API-Beschreibungen in den durchsuchten Produktpaketen verwendet. Die Angaben hier können jedoch verwendet werden, um private Pakete zu überschreiben oder hinzuzufügen.
Nein
archivepatterns Eine durch Kommas getrennte Liste mit Archivkennungen, die bei der Suche ignoriert werden sollen.

Archivkennungen haben folgendes Format: [produktpaket-id]:[pfad_zum_archiv].
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:
  • 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:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
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:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
Nein
filters Gibt das Stammverzeichnis der API-Filter an, die bei dem Verwendungssuchlauf verwendet werden sollen.

Das Argument ist das Stammverzeichnis der Dateien des Typs '.api_filters', die zum Filtern von Verweisen verwendet werden sollen.

Die Dateien '.api_filters' geben bestimmte Probleme an, die bei der API-Analyse ignoriert werden sollen. Während des Verwendungssuchlaufs werden die Problemfilter in eine Liste von Verweisen konvertiert, die aus den Ergebnissen des Verwendungssuchlaufs herausgefiltert werden.

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
debug Gibt den Wert für die Debugfunktion an.

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

Beispiele

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

Hierdurch wird die Task ausgeführt, durch die *.xml-Dateien im Ordner /eclipse/apiuse-both/XML erstellt werden. Die Task durchsucht alle Produktpakete an der Produktposition (durch den regulären Ausdruck .* definiert) auf alle Verweise auf sämtliche Produktpakete, deren Kennung mit 'org.eclipse' beginnt (durch den regulären Ausdruck org\.eclipse.* definiert). Die Task verwendet die Ausschlussliste in D:\exclude_list_external.txt, um die Anzahl der zu meldenden Probleme bzw. Fehler zu senken.

Während des Suchlaufs werden alle Klassendateien, die im Archiv '/libs/contributed.jar archive' in 'org.eclipse.test.bundle' gefunden werden, ignoriert.

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

Zugehörige Referenzinformationen

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