Úloha Ant použití API

Účel

Tato úloha spustí úplné hledání dané úrovně baseline, aby vytvořila sestavu o využívání rozhraní API.

Analýza nezahrnuje balíky, které nejsou povoleny pro API Tools.

Použití

Popis

Název úlohy Ant je: apitooling.apiuse. Chcete-li ji použít, soubor JAR apitooling-ant.jar musí být v cestě ke třídě nástroje Ant.

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

Parametry

Atribut Popis Nezbytné
location Tento atribut určuje umístění aktuálního produktu, kde chcete hledat využití rozhraní API.

Může to být soubor .zip, .jar, .tgz, .tar.gz, nebo adresář, který obsahuje produkt nebo kolekci balíků.

Umístění se zadává pomocí absolutní cesty.
Ano
scopepattern Tento atribut určuje vzor regulárního výrazu použitý k výběru balíků, které se budou vyhledávat v umístění.

Například následující ukázka by procházela použití rozhraní API pouze v balících Eclipse:
org.eclipse.*
Vzorek musí být dobře naformátovaný regulární výraz, odpovídající této definici.
Ne
referencepattern Tento atribut určuje vzor regulárního výrazu použitý k filtrování výsledků hledání. Bude hlášeno pouze použití rozhraní API, které odkazuje na balík vyhovující filtru.

Například následující ukázka by hlásila pouze použití, které odkazuje na kód v JDT:
org.eclipse.jdt.*
Vzorek musí být dobře naformátovaný regulární výraz, odpovídající této definici.
Ne
report Nastavte umístění výstupu, kam se vygenerují sestavy.

Jakmile je úloha dokončena, v tomto adresáři jsou k dispozici sestavy v hierarchické struktuře. Pro každou komponentu, na kterou odkazuje jiný balík, se vytvoří podsložka. Každá podsložka obsahuje soubor s názvem "[název balíku].xml". V této složce je další podsložka (s názvem "[název odkazujícího balíku].xml") pro každý balík, který odkazuje na balík obsahující složky. Uvnitř složky odkazujícího balíku je jedna ze tří podsložek (API, PRIVATE nebo OTHER) obsahujících odkazy na typy, metody nebo pole příslušného druhu.

Do adresáře sestavy se zapíší tři další speciální soubory, a to "counts.xml", "not_searched.xml" a "no_apidescription.xml", které obsahují informace o počtu nalezených odkazů, o balících z úrovně baseline, v kterých nebyly hledány informace o využití, resp. o těch, které v sobě neobsahovaly soubor .api_description.

Umístění se zadává pomocí absolutní cesty.

Například:
  kořen
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- "counts.xml"
   +-- název balíku s využitím
   		|
   		+--název odkazujícího balíku
   			|
   			+-- [API nebo PRIVATE nebo OTHER]
   				|
   				+--[type_ nebo method_ nebo field_]references.xml
Ano
considerinternal Určuje, zda mají být při hledání zohledněny interní odkazy.

Výchozí hodnota je false.
Ne
considerapi Určuje, zda mají být při hledání zohledněny odkazy rozhraní API.

Výchozí hodnota je false.
Ne
considerillegaluse Zda mají být při vyhledávání zvažovány nepovolené odkazy na použití rozhraní API.

Výchozí hodnota je false.
Ne
apipatterns Seznam vzorků názvů balíků (regulárních výrazů), které se mají zvážit jako balíky rozhraní API, oddělený čárkami.

Standardně se popisy rozhraní API používají v balících získaných procházením, ale pomocí tohoto atributu lze potlačit nebo přidat balíky API.
Ne
internalpatterns Seznam vzorků názvů balíků (regulárních výrazů), které se mají zvážit jako balíky soukromé rozhraní, oddělený čárkami.

Standardně se popisy rozhraní API používají v balících získaných procházením, ale pomocí tohoto atributu lze potlačit nebo přidat soukromé balíky.
Ne
archivepatterns Seznam identifikátorů archivů, které se mají při procházení ignorovat, oddělený čárkami.

Identifikátor archivu je v této formě: [id balíku]:[cesta k archivu].
Ne
excludelist Nastavte umístění vylučovacího seznamu.

Umístění vylučovacího seznamu určuje textový soubor obsahující seznam balíků, které se mají vyloučit z analýzy. Standardně se analyzují všechny balíky v profilu. Atributy zahrnovacího a vylučovacího seznamu lze použít k selektivnímu zahrnutí a vyloučení balíků. Seznam zahrnutí naplní sadu balíků, které se mají analyzovat (když je vynechán, zahrnou se všechny balíky), a poté se použije vylučovací seznam. Každý řádek souboru určuje jedno z následujících:
  • Specifický název balíku.
  • Regulární výraz k porovnání s názvy balíků (řádky s "R:").
  • Komentář (řádky s '#').

Umístění se zadává pomocí absolutní cesty.
Následuje příklad vylučovacího seznamu:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
Ne
includelist Nastavte umístění seznamu zahrnutí.

Umístění seznamu zahrnutí určuje textový soubor obsahující seznam balíků, které se mají zahrnout do analýzy. Standardně se analyzují všechny balíky v profilu. Atributy zahrnovacího a vylučovacího seznamu lze použít k selektivnímu zahrnutí a vyloučení balíků. Seznam zahrnutí naplní sadu balíků, které se mají analyzovat (když je vynechán, zahrnou se všechny balíky), a poté se použije vylučovací seznam. Každý řádek souboru určuje jedno z následujících:
  • Specifický název balíku.
  • Regulární výraz k porovnání s názvy balíků (řádky s "R:").
  • Komentář (řádky s '#').

Umístění se zadává pomocí absolutní cesty.
Následuje příklad seznamu zahrnutí:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
Ne
filters Nastavte kořenový adresář filtrů rozhraní API, které se mají při procházení použití použít.

Argumentem je kořenový adresář souborů .api_filters, které se mají použít k filtrování odkazů.

Soubory .api_filters určují specifické problémy, které se mají během analýzy rozhraní API ignorovat. Během procházení použití se filtry problémů převedou na seznam odkazů, které budou filtrovány z výsledků procházení použití.

Kořen se zadává pomocí absolutní cesty.
Kořen musí mít následující strukturu:
 kořen
  |
  +-- název komponenty (tj. org.eclipse.jface)
         |
         +--- .api_filters
Ne
debug Nastavte hodnotu ladění.

Možné hodnoty jsou: true, false
Výchozí hodnota je false.
Ne

Příklady

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

Tímto se spustí úloha a vytvoří se soubory *.xml ve složce /eclipse/apiuse-both/XML. Tato úloha prohledá všechny balíky v umístění produktu - definováno regulárním výrazem .* - a hledá všechny odkazy na libovolné balíky, jejichž identifikátor začíná na org.eclipse (definováno regulárním výrazem org\.eclipse.*). Ke snížení počtu hlášených problémů se použije vylučovací seznam v souboru D:\exclude_list_external.txt.

Při procházení budou ignorovány veškeré soubory tříd nalezené v archivu /libs/contributed.jar uvnitř balíku org.eclipse.test.bundle.

Pokud je povoleno ladění, na konzole Ant se zobrazí určitá ladicí trasování.

Související odkazy

Úloha Ant zmrazení API
Úloha Ant generování souboru
Úloha Ant převodu sestavy analýzy
Úloha Ant převodu sestavy zmrazení API
Úloha Ant nepřípustnosti rozhraní API
Úloha Ant převodu sestavy nepřípustnosti rozhraní API
Úloha Ant převodu sestavy využití API