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.
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="..." />
| 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:
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:
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 |
<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í.

Ú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