Ant-uppgiften API Use

Ändamål

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.

Användning

Beskrivning

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

Parametrar

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:
  • ett specifikt samlingspaketnamn
  • ett reguljärt uttryck som matchas mot paketnamnen (rader som börjar med "R:")
  • en kommentar (rader börjar med #)

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:
  • ett specifikt samlingspaketnamn
  • ett reguljärt uttryck som matchas mot paketnamnen (rader som börjar med "R:")
  • en kommentar (rader börjar med #)

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

Exempel

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

Närliggande referenser

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