Zadanie Ant migrowania użycia interfejsu API

Przeznaczenie

To zadanie pobiera określony skan użycia interfejsu API i próbuje ponownie rozstrzygnąć go w ramach podanej kandydującej wersji produktu, a następnie zgłasza wszystkie nierozstrzygnięte odwołania.

Użycie

Opis

Nazwa zadania Ant to apitooling.apimigration. Aby możliwe było jego użycie, plik JAR apitooling-ant.jar musi znajdować się w ścieżce klas narzędzia Ant.

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

Parametry

Atrybut Opis Wymagany
candidate Ten atrybut określa produkt do użycia jako kandydata do migracji.

Może to być plik .zip, .jar, .tgz lub .tar.gz albo katalog odpowiadający folderowi instalacyjnemu platformy Eclipse. Jest to katalog, w którym znajduje się plik wykonywalny platformy Eclipse.

Tak
usescan Ten atrybut określa skan użycia produktu do porównania z kandydatem do migracji.

Atrybut usescan określa się przy użyciu pełnej ścieżki do elementu głównego skanu użycia.
Tak
scopepattern Ten atrybut określa wzorzec wyrażenia regularnego używanego do budowania zasięgu elementów na potrzeby wyszukiwania odwołań z poziomu położenia produktu.

Wzorzec musi być poprawnie sformatowanym wyrażeniem regularnym według definicji podanej tutaj.
Nie
referencepattern Umożliwia ustawienie wzorca wyrażenia regularnego używanego do budowania zasięgu elementów na potrzeby wyszukiwania odwołań w położeniu produktu.

Wzorzec musi być poprawnie sformatowanym wyrażeniem regularnym według definicji podanej tutaj.
Nie
excludelist Ustawia położenie listy wykluczeń.

Położenie listy wykluczeń określa plik tekstowy zawierający pakunki do wykluczenia z analizy. Domyślnie analizowane są wszystkie pakunki w profilu. Atrybutów listy włączeń i wykluczeń można używać do selektywnego włączania i wykluczania pakunków. Lista włączeń określa zbiór pakunków, które mają być analizowane (jej pominięcie oznacza włączenie wszystkich pakunków). Po niej jest stosowana lista wykluczeń. Każdy wiersz pliku określa jeden z następujących elementów:
  • konkretna nazwa pakunku,
  • wyrażenie regularne porównywane z nazwami pakunków (wiersze zaczynające się od łańcucha „R:”),
  • komentarz (wiersze zaczynające się od znaku „#”).

Położenie jest określane przy użyciu pełnej ścieżki.
Przykładowa lista wykluczeń:
# PAKUNKI WYKLUCZONE
R:org\.eclipse\..*\.doc\..*
...
Nie
includelist Ustawia położenie listy włączeń.

Położenie listy włączeń określa plik tekstowy zawierający pakunki do uwzględnienia w analizie. Domyślnie analizowane są wszystkie pakunki w profilu. Atrybutów listy włączeń i wykluczeń można używać do selektywnego włączania i wykluczania pakunków. Lista włączeń określa zbiór pakunków, które mają być analizowane (jej pominięcie oznacza włączenie wszystkich pakunków). Po niej jest stosowana lista wykluczeń. Każdy wiersz pliku określa jeden z następujących elementów:
  • konkretna nazwa pakunku,
  • wyrażenie regularne porównywane z nazwami pakunków (wiersze zaczynające się od łańcucha „R:”),
  • komentarz (wiersze zaczynające się od znaku „#”).

Położenie jest określane przy użyciu pełnej ścieżki.
Przykładowa lista włączeń:
# PAKUNKI WŁĄCZONE
R:org\.eclipse\..*
...
Nie
report Ustawia położenie wyjściowe, w którym będą generowane raporty.

Po zakończeniu tego zadania raporty będą dostępne w danym katalogu o strukturze hierarchicznej. Dla każdego komponentu zawierającego inny pakunek, który się do niego odwołuje, tworzony jest podfolder. Każdy podfolder zawiera plik o nazwie [nazwa_pakunku].xml. W ramach tego folderu znajduje się inny podfolder (o nazwie [nazwa pakunku odwołującego się].xml) dla każdego pakunku odwołującego się do pakunku folderu zawierającego. Wewnątrz folderu pakunku odwołującego się znajduje się jeden z trzech podfolderów (API, PRIVATE lub OTHER), który zawiera odwołania do typu, metody lub pola odpowiedniego rodzaju.

W katalogu raportu zapisywane są dwa inne pliki specjalne i nazwach not_searched.xml i no_apidescription.xml, które zawierają informacje o pakunkach z wersji bazowej, w których nie szukano informacji o wykorzystaniu, oraz odpowiednio te, które nie zawierają plików .api_description.

Położenie jest określane przy użyciu pełnej ścieżki.

Na przykład:
  root
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- nazwa pakunku z określonym użyciem
     |
     +--nazwa pakunku odwołującego się
      |
      +-- [API lub PRIVATE, lub OTHER]
       |
       +--[type_ lub method_, lub field_]references.xml
Tak
debug Ustawia wartość debugowania.

Możliwe wartości to: true i false.
Wartość domyślna to false.
Nie

Przykłady

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

  scopepattern=".*"
  referencepattern="org\.eclipse.*"
  excludelist="D:\lista_wykluczeń_zewnętrznych.txt"
  report="/eclipse/apimigration/xml"
  debug="true"

 />

Spowoduje to uruchomienie zadania tworzenia plików *.xml w folderze /eclipse/apimigration/xml. Zadanie rozstrzyga ponownie wszystkie odwołania do położenia określonego przez parametr usescan (zdefiniowanego przez wyrażenie regularne .*) względem kandydującego produktu, którego identyfikator zaczyna się od napisu org.eclipse (zdefiniowanego przez wyrażenie regularne org\.eclipse.*). Aby zmniejszyć liczbę problemów do zgłoszenia, używana jest lista wykluczeń D:\lista_wykluczeń_zewnętrznych.txt.

Jeśli włączone jest debugowanie, część danych śledzenia debugowania będzie wyświetlana w konsoli narzędzia Ant.

Informacje pokrewne

Zadanie Ant blokowania interfejsu API
Zadanie Ant generowania pliku
Zadanie Ant konwersji raportu analizy
Zadanie Ant konwersji raportu blokowania interfejsu API
Zadanie Ant deaktualizowania interfejsu API
Zadanie Ant konwersji raportu deaktualizowania interfejsu API
Zadanie Ant konwersji raportu użycia interfejsu API
Zadanie Ant konwersji raportu migracji użycia interfejsu API