Med den här uppgiften görs en fullständig sökning för en given basnivå för att skapa en rapport för API-användning.
Analysen innefattar inte samlingspaket som inte är API-verktygsaktiverade.
Ant-uppgiftens namn: apitooling.apiuse. Om den ska kunna användas måste JAR-filen apitooling-ant.jar finnas i Ant-klassökvägen.
<apitooling.apiuse location="..." scopepattern="..." referencepattern="..." report="..." considerinternal="..." considerapi="..." considerillegaluse="..." apipatterns="..." internalpatterns="..." archivepatterns="..." excludelist="..." includelist="..." debug="..." />
| Attribut | Beskrivning | Obligatoriskt |
| location |
Attributet anger platsen för aktuell produkt som ska användas för API-användningssökning. Det kan vara en fil av typen .zip, .jar, .tgz, .tar.gz, eller en katalog som innehåller en produkt eller en paketsamling. Platsen anges med en absolut sökväg. |
Ja |
| scopepattern |
Attributet anger ett mönster för reguljärt uttryck som används till att välja vilka paket på platsen som ska genomsökas.
Exempel: Med följande sker sökningen efter API-användning enbart i Eclipse-paket: org.eclipse.*Mönstret måste vara ett giltigt reguljärt uttryck, vilket definieras här. |
Nej |
| referencepattern |
Attributet anger ett mönster för reguljärt uttryck som används till att filtrera sökresultaten. Endast API-användning som refererar till ett paket som matchar filtret kommer att rapporteras.
Exempel: Med följande rapporteras endast användning som refererar till kod i JDT: org.eclipse.jdt.*Mönstret måste vara ett giltigt reguljärt uttryck, vilket definieras här. |
Nej |
| report | Utdataplats där rapporteran skapas.
När uppgiften har slutförts finns rapporterna i katalogen i en hierarki. En undermapp skapas för varje komponent som refereras av ett annat samlingspaket. Varje undermapp innehåller filen "[samlingspaketnamn].xml". I mappen finns en annan undermapp (med namnet "[namn på refererande samlingspaket].xml") för varje samlingspaket som refererar till samlingspaket i den innehållande mappen. I mappen för referenssamlingspaketet finns en av tre undermappar (API, PRIVATE eller OTHER) som innehåller typ, metod eller fältreferenser av den typen. Tre andra specialfiler skrivs till rapportkatalogen: "counts.xml", "not_searched.xml" och "no_apidescription.xml". De innehåller information om antalet hittade referenser, paket från basnivån som inte genomsöktes och paket som inte innehöll några .api_description-filer. Platsen anges med en absolut sökväg. Exempel: root | +-- "not_searched.xml" +-- "no_apidescription.xml" +-- "counts.xml" +-- bundle name with usage | +--referencing bundle name | +-- [API or PRIVATE or OTHER] | +--[type_ or method_ or field_]references.xml |
Ja |
| considerinternal | Om interna referenser ska beaktas vid sökning. Standardvärdet är false. |
Nej |
| considerapi | Om API-referenser ska beaktas vid sökning. Standardvärdet är false. |
Nej |
| considerillegaluse | Om ogiltiga API-referenser ska beaktas under sökningen. Standardvärdet är false. |
Nej |
| apipatterns | En kommaavgränsad lista över paketnamnsmönster (reguljära uttryck) som ska betraktas som API-paket.
Som standard används API-beskrivningar i de genomsökta paketen, men du kan använda detta om du vill åsidosätta eller lägga till API-paket. |
Nej |
| internalpatterns | En kommaavgränsad lista över paketnamnsmönster (reguljära uttryck) som ska betraktas som privata paket.
Som standard används API-beskrivningar i de genomsökta paketen, men du kan använda detta om du vill åsidosätta eller lägga till privata paket. |
Nej |
| archivepatterns | En kommaavgränsad lista över arkividentifierare som ska ignoreras under sökningen. En arkividentifierare har formatet: [paket-id]:[sökväg till arkiv]. |
Nej |
| excludelist |
Platsen för exkluderingslistan
I exkluderingslistan anges en textfil där de samlingspaket som ska uteslutas från analysen listas. Som standard analyseras alla paket i profilen. Med inkluderings- och exkluderingslistattributen kan du välja vilka paket som ska tas med repektive uteslutas. Inkluderingslistan anger vilka paket som ska analyseras (om den utelämnas tas alla paket med), och sedan tillämpas exkluderingslistan. Varje rad i filen anger antingen:
Platsen anges med en absolut sökväg. Följande är ett exempel på en exkluderingslista: # EXCLUDED BUNDLES R:org\.eclipse\..*\.doc\..* ... |
Nej |
| includelist |
Platsen för inkluderingsslistan.
I inkluderingslistan anges en textfil där de samlingspaket som ska tas med i analysen listas. Som standard analyseras alla paket i profilen. Med inkluderings- och exkluderingslistattributen kan du välja vilka paket som ska tas med repektive uteslutas. Inkluderingslistan anger vilka paket som ska analyseras (om den utelämnas tas alla paket med), och sedan tillämpas exkluderingslistan. Varje rad i filen anger antingen:
Platsen anges med en absolut sökväg. Följande är ett exempel på en inkluderingslista: # INCLUDED BUNDLES R:org\.eclipse\..* ... |
Nej |
| filter | Rotkatalogen för API-filter som ska användas vid användningssökningen.
Argumentet är rotkatalogen för filerna .api_filters som ska användas för filtrering av referenser. Filerna .api_filters anger vilka problem som ska ignoreras under api-analysen. Under användningssökningen konverteras problemfiltren till en referenslista som filtreras bort från resultaten. Roten anges med en absolut sökväg. Roten måste innehålla följande struktur:
root
|
+-- komponentnamn (dvs. org.eclipse.jface)
|
+--- .api_filters
|
Nej |
| debug | Felsökningsvärdet Giltiga värden är true och false.
Standardvärdet är false. |
Nej |
<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" />
Uppgiften som skapar *.xml-filer i mappen /eclipse/apiuse-both/XML körs.
Den söker igenom alla samlingspaket på produktplatsen - som definieras av det reguljära uttrycket .* - söker efter alla referenser till samlingspaket vars identifierare börjar med org.eclipse (som definieras av det reguljära uttrycket org\.eclipse.*).
Exkluderingslistan D:\exclude_list_external.txt används för att minska antalet problem som ska rapporteras.
Under sökningen ignoreras alla klassfiler i /libs/contributed.jar archive inom org.eclipse.test.bundle.
Om debug är aktiverat visas vissa felsökningsmeddelanden i Ant-konsolen.

Ant-uppgiften API Freeze
Ant-uppgiften File Generation
Ant-uppgiften Analysis Report Conversion
Ant-uppgiften API Freeze Report Conversion
Ant-uppgiften API Deprecation
Ant-uppgiften API Deprecation Report Conversion
Ant-uppgiften API Use Report Conversion