Ant-opgave: Overførsel af API-brug

Formål

Denne opgave tager udgangspunkt i en scanning af API-brug og prøver at genfortolke den i en bestemt release af et kandidatprodukt og rapporterer eventuelle ikke-fortolkede referencer.

Brug

Beskrivelse

Navnet på Ant-opgaven er: apitooling.apimigration. For at kunne bruges skal JAR-filen apitooling-ant.jar findes i Ant-classpath.

 <apitooling.apimigration
	candidate="..."
	usescan="..."
	scopepattern="..."
	referencepattern="..."
	excludelist="..."
	includelist="..."
	report="..."
	debug="..."
 />

Parametre

Attribut Beskrivelse Påkrævet
candidate Denne attribut angiver det produkt, du vil bruge som overførselskandidat.

Det kan være en .zip-, .jar-, .tgz-, .tar.gz-fil eller et bibliotek, der svarer til Eclipse-installationsfolderen. Det er i dette bibliotek, at du kan finde den eksekvérbare Eclipse-fil.

Ja
usescan Denne attribut angiver den scanning af produktbrug, du vil sammenligne med overførselskandidaten.

Attributten usescan angives ved hjælp af en absolut sti til roden for brugsscanningen.
Ja
scopepattern Denne attribut angiver det regulære udtryksmønster, der bruges til at oprette omfanget af elementer, hvor der skal søges efter referencer fra i produktplaceringen.

Mønsteret skal være et korrekt formateret regulært udtryk som defineret her.
Nej
referencepattern Angiv det regulære udtryksmønster, der er brugt til at oprette omfanget af elementer for at søge efter referencer til fra produktplaceringen.

Mønsteret skal være et korrekt formateret regulært udtryk som defineret her.
Nej
excludelist Angiv placeringen af exclude-listen.

Placeringen af exclude-listen angiver en tekstfil med de bundter, der skal udelades fra analysen. Som standard analyseres alle bundterne i profilen. Attributter for include- og exclude-lister kan bruges til selektivt at medtage og udelade bundter. Include-listen tilfører det bundtsæt, der skal analyseres (når den ikke angives, medtages alle bundter), og exclude-listen anvendes derefter. Linjerne i filen angiver et af følgende:
  • et specifikt bundtnavn
  • et regulært udtryk, som skal matches med bundtnavne (linjer, der starter med "R:")
  • en kommentar (linjer, der starter med '#')

Placeringen angives ved hjælp af en absolut sti.
Her er et eksempel på en exclude-liste:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
Nej
includelist Angiv placeringen af include-listen.

Placeringen af include-listen angiver en tekstfil med de bundter, der skal medtages i analysen. Som standard analyseres alle bundterne i profilen. Attributter for include- og exclude-lister kan bruges til selektivt at medtage og udelade bundter. Include-listen tilfører det bundtsæt, der skal analyseres (når den ikke angives, medtages alle bundter), og exclude-listen anvendes derefter. Linjerne i filen angiver et af følgende:
  • et specifikt bundtnavn
  • et regulært udtryk, som skal matches med bundtnavne (linjer, der starter med "R:")
  • en kommentar (linjer, der starter med '#')

Placeringen angives ved hjælp af en absolut sti.
Her er et eksempel på en include-liste:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
Nej
report Angiv den outputplacering, hvor rapporterne bliver genereret.

Når opgaven er udført, er rapporterne tilgængelige i dette bibliotek ved hjælp af en hierarkisk struktur. Der oprettes en underfolder for alle komponenter, der et andet bundt, som refererer til det. De enkelte underfoldere indeholder en fil, der hedder "[bundtnavn].xml". I denne folder er der en anden underfolder (med navnet "[refererende bundtnavn].xml") for hvert bundt, der refererer til bundtet i den overordnede folder. I den refererende bundtfolder er der én ud af tre underfoldere (API, PRIVATE eller OTHER), som indeholder type-, metode- eller feltreferencer af denne slags.

To andre specielle filer skrives i rapportbiblioteket. Det er "not_searched.xml" og "no_apidescription.xml", og de indeholder oplysninger om bundter fra grundlinjen, som der henholdsvis ikke er søgt i efter anvendelsesoplysninger, og som ikke indeholder .api_description-filer.

Placeringen angives ved hjælp af en absolut sti.

Eksempel:
  rod
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- bundtnavn med syntaks
     |
     +--refererende bundtnavn
      |
      +-- [API eller PRIVATE eller OTHER]
       |
       +--[type_ eller method_ eller field_]references.xml
Ja
debug Angiv fejlfindingsværdien.

Mulige værdier er: true, false
Standardværdien er false.
Nej

Eksempler

 <apitooling.apimigration
  candidate="/eclipse/sdk3.5"
  usescan="/eclipse/scans/sdk3.4"

  scopepattern=".*"
  referencepattern="org\.eclipse.*"
  excludelist="D:\exclude_list_external.txt"
  report="/eclipse/apimigration/xml"
  debug="true"

 />

Herved køres den opgave, som opretter *.xml-filer i folderen /eclipse/apimigration/xml. Opgaven genfortolker alle referencer på placeringen usescan - defineret af det regulære udtryk .* - op imod det kandidatprodukt, hvis id starter med org.eclipse (defineret af de t regulære udtryk org\.eclipse.*). Opgaven bruger exclude-listefilen på placeringen D:\exclude_list_external.txt til at mindske antallet af problemer, der skal rapporteres.

Hvis fejlfinding er aktiveret, bliver der vist fejlfindingssporing i Ant-konsollen.

Relaterede referencer

API-opgave: API-frys
Ant-opgave: Generering af fil
Ant-opgave: Konvertering af analyserapport
Ant-opgave: Konvertering af API-frysrapport
Ant-opgave: API-forældelse
Ant-opgave: Konvertering af API-forældelsesrapport
Ant-opgave: Konvertering af API-brugsrapport
Ant-opgave: Konvertering af API-brugsoverførselsrapport