API használat Ant feladat

Cél

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.

Használat

Leírás

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

Paraméterek

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:
  • egy adott köteg neve
  • egy reguláris kifejezés a kötegnevek egyeztetéséhez (az "R:" kifejezéssel kezdődő sorok)
  • egy megjegyzés (a '#' karakterrel kezdődő sorok)

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:
  • egy adott köteg neve
  • egy reguláris kifejezés a kötegnevek egyeztetéséhez (az "R:" kifejezéssel kezdődő sorok)
  • egy megjegyzés (a '#' karakterrel kezdődő sorok)

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

Példák

	<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.

Kapcsolódó leírás

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