Ant-Task für API-Verwendungsmigration

Zweck

Diese Task verwendet einen bestimmten API-Verwendungssuchlauf, versucht, diesen im Release eines bestimmten Kandidatenprodukts erneut aufzulösen und meldet alle nicht aufgelösten Verweise.

Verwendung

Beschreibung

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

 <apitooling.apimigration
	candidate="..."
	usescan="..."
	scopepattern="..."
	referencepattern="..."
	excludelist="..."
	includelist="..."
	report="..."
	debug="..."
 />

Parameter

Attribut Beschreibung Erforderlich
candidate Dieses Attribut gibt das Produkt an, das als Migrationskandidat verwendet 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.

Ja
usescan Dieses Attribut gibt den Produktverwendungssuchlauf an, der mit dem Migrationskandidaten verglichen werden soll.

Der Verwendungssuchlauf wird mithilfe eines absoluten Pfads zu seinem Stammverzeichnis angegeben.
Ja
scopepattern Dieses Attribut gibt das Muster eines regulären Ausdrucks an, das für die Erstellung des Bereichs der Elemente verwendet werden soll, die nach von ihnen ausgehenden Verweisen an der Produktposition durchsucht werden sollen.

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 legt das Muster eines regulären Ausdrucks fest, das für die Erstellung des Bereichs der Elemente verwendet werden soll, die nach Verweisen auf sie an der Produktposition durchsucht werden sollen.

Bei diesem Muster muss es sich um einen ordnungsgemäß formatierten regulären Ausdruck handeln, der der Definition entspricht, die Sie hier finden.
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
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 zwei weitere besondere Dateien in das Berichtsverzeichnis geschrieben, nämlich 'not_searched.xml' und 'no_apidescription.xml'. Die Datei 'not_searched.xml' enthält Informationen zu Produktpaketen der Referenzkonfiguration, die nicht nach Informationen zur Verwendung durchsucht wurden, und die Datei 'no_apidescription.xml' enthält Informationen zu Produktpaketen, die zum Zeitpunkt der Suche keine Dateien des Typs '.api_description' enthalten haben.

Die Position wird mit einem absoluten Pfad angegeben.

Zum Beispiel:
  stammverzeichnis
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- produktpaketname mit verwendung
     |
     +--referenzierender produktpaketname
      |
      +-- [API oder PRIVATE oder OTHER]
       |
       +--[type_ oder method_ oder field_]references.xml
Ja
debug Gibt den Wert für die Debugfunktion an.

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

Beispiele

 <apitooling.apimigration
  candidate="/eclipse/sdk3.5"
  usescan="/eclipse/scans/sdk3.4"

  scopepattern=".*"
  referencepattern="org\.eclipse.*"
  excludelist="D:\exclude_list_external.txt"
  report="/eclipse/apimigration/xml"
  debug="true"

 />

Hierdurch wird die Task ausgeführt, durch die *.xml-Dateien im Ordner /eclipse/apimigration/xml erstellt werden. Die Task löst alle Verweise an der usescan-Position (durch den regulären Ausdruck .* definiert) im Kontext des Kandidatenprodukts, dessen Kennung mit 'org.eclipse' beginnt (durch den regulären Ausdruck org\.eclipse.* definiert), erneut auf. Die Task verwendet die Ausschlussliste in D:\exclude_list_external.txt, um die Anzahl der zu meldenden Probleme bzw. Fehler zu senken.

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
Ant-Task für Konvertierung von API-Verwendungsmigrationsberichten