Ez a feladat egy adott alapsor teljes keresését futtatja az API használattal kapcsolatos jelentés létrehozásához.
Az elemzés nem tartalmazza azokat a kötegeket, amelyek nincsenek felkészítve az API eszközök használatára.
Az Ant feladat neve: apitooling.apiuse. A
használatához az apitooling-ant.jar fájlnak szerepelnie kell
az Ant osztályútvonalon.
<apitooling.apiuse location="..." scopepattern="..." referencepattern="..." report="..." considerinternal="..." considerapi="..." considerillegaluse="..." apipatterns="..." internalpatterns="..." archivepatterns="..." excludelist="..." includelist="..." debug="..." />
| Attribútum | Leírás | Kötelező |
| location |
Ez az attribútum annak az aktuális terméknek a helyét adja meg, amelyben API használati elemeket szeretne keresni.
Ez lehet egy .zip, .jar, .tgz, .tar.gz fájl, vagy egy könyvtár, amely egy terméket vagy egy köteggyűjteményt tartalmaz. A helyet abszolút útvonalként kell megadni. |
Igen |
| scopepattern |
Ez az attribútum egy reguláris kifejezést határoz meg, amely megadja,
hogy a helyen belül mely kötegekben kell keresni.
Például a következő reguláris kifejezés csak az Eclipse kötegekben elemzi az API használatot: org.eclipse.*A mintáknak jól formázott reguláris kifejezéseknek kell lenniük (meghatározás itt). |
Nem |
| referencepattern |
Ez az attribútum egy reguláris kifejezést határoz meg, amely a
keresési eredmények szűréséhez használható. Csak a szűrőnek megfelelő
kötegre hivatkozó API használat lesz jelentve.
Például a következő reguláris kifejezés csak a JDT kódra hivatkozó használatot jelenti: org.eclipse.jdt.*A mintáknak jól formázott reguláris kifejezéseknek kell lenniük (meghatározás itt). |
Nem |
| report | Itt állíthatja be a kimeneti helyet, ahová a jelentések
elő lesznek állítva.
A feladat befejeződése után a jelentések ebben a könyvtárban érhetők el, egy hierarchikus szerkezetben. Minden olyan komponenshez létrehozásra kerül egy almappa, amelyre egy másik köteg hivatkozik. Minden almappa tartalmaz egy "[kötegnév].xml" nevű fájlt. A mappán belül van egy másik almappa, melynek neve "[hivatkozó köteg neve].xml", minden olyan köteghez, amely hivatkozik a tartalmazó mappa kötegére. A hivatkozó köteg mappáján belül szerepel az API, PRIVATE vagy OTHER almappák egyike, amely az adott fajtájú típus-, metódus- vagy mezőhivatkozásokat tartalmazza. A jelentés könyvtárba három másik speciális fájl is kerül (a "counts.xml", "not_searched.xml" és a "no_apidescription.xml"), amelyek rendre a talált hivatkozások számát, az alapsor használati elemzésből kizárt kötegeit, valamint az .api_description fájlt nem tartalmazó kötegeket tartalmazzák. A helyet abszolút útvonalként kell megadni. Például: gyökér | +-- "not_searched.xml" +-- "no_apidescription.xml" +-- "counts.xml" +-- kötegnév használattal | +--hivatkozó köteg neve | +-- [API vagy PRIVATE vagy OTHER] | +--[type_ vagy method_ vagy field_]references.xml |
Igen |
| considerinternal | A belső hivatkozásokat figyelembe kell-e venni a keresés során.
Az alapértelmezett érték a false. |
Nem |
| considerapi | Az API hivatkozásokat figyelembe kell-e venni a keresés során.
Az alapértelmezett érték a false. |
Nem |
| considerillegaluse | Az illegális API használati hivatkozásokat figyelembe kell-e venni a keresés során.
Az alapértelmezett érték a false. |
Nem |
| apipatterns | Az API csomagként tekintendő csomagnév minták (reguláris kifejezések) vesszővel elválasztott listája.
Alapértelmezésben az elemzett kötegekben az API leírások kerülnek felhasználásra, de ez felhasználható API csomagok felülbírálására vagy hozzáadására. |
Nem |
| internalpatterns | A privát csomagként tekintendő csomagnév minták (reguláris kifejezések) vesszővel elválasztott listája.
Alapértelmezésben az elemzett kötegekben az API leírások kerülnek felhasználásra, de ez felhasználható privát csomagok felülbírálására vagy hozzáadására. |
Nem |
| archivepatterns | Az elemzés során figyelmen kívül hagyandó
archívumazonosítók vesszővel elválasztott listája.
Az archívumazonosítók formátuma a következő: [kötegazonosító]:[archívum_útvonala]. |
Nem |
| excludelist |
Itt állíthatja be a kizárási lista helyét.
A kizárási lista helye egy szövegfájlt ad meg, amely az elemzésből kizárandó kötegek listáját tartalmazza. Alapértelmezésben a profilban lévő összes köteg elemezve lesz. A tartalmazási és kizárási lista attribútumok használatával egyenként megadhatja a tartalmazni és kizárni kívánt kötegeket. A tartalmazási lista adja meg az elemezni kívánt kötegek alap készletét (ha nincs megadva, akkor az összes köteg), és ezután kerül alkalmazásra a kizárási lista. A fájl minden sora a következők egyikét adja meg:
A helyet abszolút útvonalként kell megadni. Íme egy példa a kizárási listára: # KIZÁRT KÖTEGEK R:org\.eclipse\..*\.doc\..* ... |
Nem |
| includelist |
Itt állíthatja be a tartalmazási lista helyét.
A tartalmazási lista helye egy szövegfájlt ad meg, amely az elemzésbe belefoglalni kívánt kötegek listáját tartalmazza. Alapértelmezésben a profilban lévő összes köteg elemezve lesz. A tartalmazási és kizárási lista attribútumok használatával egyenként megadhatja a tartalmazni és kizárni kívánt kötegeket. A tartalmazási lista adja meg az elemezni kívánt kötegek alap készletét (ha nincs megadva, akkor az összes köteg), és ezután kerül alkalmazásra a kizárási lista. A fájl minden sora a következők egyikét adja meg:
A helyet abszolút útvonalként kell megadni. Íme egy példa a tartalmazási listára: # TARTALMAZOTT KÖTEGEK R:org\.eclipse\..* ... |
Nem |
| filters | Itt állíthatja be az API szűrők elemzés során használandó
gyökérkönyvtárát.
Az argumentum .api_filters fájlok gyökérkönyvtára, amelyet a hivatkozások szűréséhez kell használni. Az .api_filters fájlok adják meg az API elemzés során figyelmen kívül hagyandó problémákat. A használati elemzés során a problémaszűrők át lesznek alakítva hivatkozások listájára, amelyek ki lesznek szűrve a használati elemzés eredményeiből. A gyökérkönyvtárat abszolút útvonalként kell megadni. A gyökér a következő szerkezetet tartalmazza:
gyökér |
+-- komponens neve (vagyis org.eclipse.jface)
|
+--- .api_filters
|
Nem |
| debug | Itt állíthatja be a hibakeresési értéket.
Lehetséges értékek: true vagy false
Az alapértelmezett érték a false. |
Nem |
<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" />
Ez lefuttatja a feladatot és az /eclipse/apiuse-both/XML mappán belül létrehozza a *.xml fájlokat.
A feladat megkeresi a .* reguláris kifejezéssel megadott
termékhelyen lévő összes kötegben az összes olyan hivatkozást bármely
kötegre, melyek azonosítója az org\.eclipse.* reguláris
kifejezéssel meghatározott org.eclipse karaktersorozattal kezdődik.
A jelentendő problémák számának csökkentéséhez a
D:\exclude_list_external.txt helyen található kizárási lista
fájlt fogja használni.
Az elemzés során az org.eclipse.test.bundle kötegen belüli /libs/contributed.jar archívumban talált osztályfájl figyelmen kívül marad.
Ha engedélyezve van a hibakeresés, az Ant konzolon hibakeresési nyomkövetési információk is megjelennek.

API befagyasztás Ant feladat
Fájl előállítása Ant feladat
Elemzési jelentés átalakítása Ant feladat
API befagyasztási jelentés átalakítása Ant feladat
API elavulás Ant feladat
API elavulás jelentés átalakítása Ant feladat
API használat jelentés átalakítása Ant feladat