Zadanie Ant użycia interfejsu API

Przeznaczenie

To zadanie uruchamia pełne wyszukiwanie danej wersji bazowej w celu utworzenia raportu dotyczącego wykorzystania interfejsu API.

Analiza nie obejmuje pakunków, które nie obsługują narzędzi interfejsu API.

Opis

Opis

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

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

Parametry

Atrybut Opis Wymagany
location Ten atrybut określa położenie bieżącego produktu, który ma zostać wyszukany w celu określenia użycia interfejsu API.

Może to być plik .zip, .jar, .tgz, .tar.gz bądź katalog zawierający produkt lub kolekcję pakunków.

Położenie jest określane przy użyciu pełnej ścieżki.
Tak
scopepattern Ten atrybut określa wzorzec wyrażenia regularnego używanego do wybierania pakunków wyszukiwanych w danym położeniu.

Na przykład następujący wzorzec powoduje skanowanie użycia interfejsu API w pakunkach Eclipse:
org.eclipse.*
Wzorzec musi być poprawnie sformatowanym wyrażeniem regularnym według definicji podanej tutaj.
Nie
referencepattern Ten atrybut określa wzorzec wyrażenia regularnego używanego do filtrowania wyników wyszukiwania. Raportowane jest wyłącznie użycie funkcji API odwołujących się do pakunku zgodnego z filtrem.

Na przykład następujący wzorzec powoduje raportowanie wyłącznie użycia odwołującego się do kodu w JDT:
org.eclipse.jdt.*
Wzorzec musi być poprawnie sformatowanym wyrażeniem regularnym według definicji podanej tutaj.
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ą trzy inne pliki specjalne o nazwach counts.xml, not_searched.xml i no_apidescription.xml, które zawierają informacje o liczbie znalezionych odwołań, o pakunkach z wersji bazowej, w których nie szukano informacji o używaniu, 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"
   +-- "counts.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
considerinternal Jeśli podczas wyszukiwania mają być uwzględnianie odwołania wewnętrzne.

Wartość domyślna to false.
Nie
considerapi Jeśli podczas wyszukiwania mają być uwzględnianie odwołania do interfejsu API.

Wartość domyślna to false.
Nie
considerillegaluse Określa, czy podczas wyszukiwania mają być uwzględnianie niedozwolone odwołania do użycia interfejsu API.

Wartość domyślna to false.
Nie
apipatterns Rozdzielana przecinkami lista wzorców nazw pakietów (wyrażeń regularnych), które mają być traktowane jako pakiety interfejsu API.

Domyślnie opisy interfejsu API są używane w skanowanych pakunkach, lecz tej listy można użyć do przesłonięcia lub dodania pakietów interfejsu API.
Nie
internalpatterns Rozdzielana przecinkami lista wzorców nazw pakietów (wyrażeń regularnych), które mają być traktowane jako pakiety prywatne.

Domyślnie opisy interfejsu API są używane w skanowanych pakunkach, lecz tej listy można użyć do przesłonięcia lub dodania pakietów prywatnych.
Nie
archivepatterns Rozdzielana przecinkami lista identyfikatorów archiwów do zignorowania podczas skanowania.

Identyfikator archiwum ma postać [identyfikator pakunku]:[ścieżka do archiwum].
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
filtry Ustawia katalog główny filtrów interfejsu API, które mają być używane podczas skanowania użycia.

Argumentem jest katalog główny plików .api_filters, które powinny być używane do filtrowania odwołań.

Pliki .api_filters określają konkretne problemy do zignorowania podczas analizy interfejsu API. Podczas skanowania użycia filtry problemów są przekształcane w listę odwołań, które należy odfiltrować z wyników skanowania użycia.

Katalog główny jest określany przy użyciu pełnej ścieżki.
Katalog główny musi zawierać następującą strukturę:
 root
  |
  +-- nazwa komponentu (tzn. org.eclipse.jface)
         |
         +--- .api_filters
Nie
debug Ustawia wartość debugowania.

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

Przykłady

	<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:\lista_wykluczeń_zewnętrznych.txt"
		debug="true"
	/>

W powyższym przykładzie uruchamiane jest zadanie tworzenia plików *.xml wewnątrz folderu /eclipse/apiuse-both/XML. Zadanie przeszuka wszystkie pakunki w położeniu produktu (zdefiniowane przez wyrażenie regularne .*), wyszukując wszystkie odwołania do wszystkich pakunków, których identyfikator rozpoczyna się od łańcucha org.eclipse (zdefiniowanych 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.

Podczas skanowania wszystkie pliki klas znalezione w archiwum /libs/contributed.jar wewnątrz pakunku org.eclipse.test.bundle będą ignorowane.

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