Εργασία Ant χρήσης API

Σκοπός

Αυτή η εργασία πραγματοποιεί ολοκληρωμένη αναζήτηση μιας συγκεκριμένης γραμμής βάσης για τη δημιουργία μιας αναφοράς χρήσης ΑΡΙ.

Η ανάλυση δεν συμπεριλαμβάνει δέσμες που δεν διαθέτουν τη δυνατότητα εργαλείων API.

Χρήση

Περιγραφή

Το όνομα της εργασίας Ant είναι: apitooling.apiuse. Προκειμένου να χρησιμοποιηθεί, το αρχείο jar apitooling-ant.jar πρέπει να βρίσκεται στην ίδια διαδρομή κλάσεων Ant.

<apitooling.apiuse
	location="..."
	scopepattern="..."
	referencepattern="..."
	report="..."
	considerinternal="..."
	considerapi="..."
	considerillegaluse="..."
	apipatterns="..."
	internalpatterns="..."
	archivepatterns="..."
	excludelist="..."
	includelist="..."	
			debug="..."
/>

Παράμετροι

Γνώρισμα Περιγραφή Απαιτείται
location Αυτό το γνώρισμα καθορίζει τη θέση του τρέχοντος προϊόντος στο οποίο θέλετε να πραγματοποιήσετε αναζήτηση για χρήση API.

Μπορεί να είναι αρχείο .zip, .jar, .tgz, .tar.gz ή ένας κατάλογος που περιέχει ένα προϊόν ή μια συλλογή δεσμών.

Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ναι
scopepattern Αυτό το γνώρισμα καθορίζει ένα μοτίβο κανονικής έκφρασης που χρησιμοποιείται για την επιλογή των δεσμών για τις οποίες θα γίνει αναζήτηση στην τοποθεσία.

Για παράδειγμα, με την παρακάτω πρόταση θα γίνει ανίχνευση μόνο για χρήση API σε δέσμες Eclipse:
org.eclipse.*
Το μοτίβο πρέπει να είναι μια κανονική έκφραση με έγκυρη μορφή, όπως ορίζεται εδώ.
Όχι
referencepattern Αυτό το γνώρισμα καθορίζει ένα μοτίβο κανονικής έκφρασης που χρησιμοποιείται για το φιλτράρισμα των αποτελεσμάτων αναζήτησης. Θα αναφερθεί μόνο η χρήση API που παραπέμπει σε μία δέσμη που ικανοποιεί τα κριτήρια φιλτραρίσματος.

Για παράδειγμα, η παρακάτω πρόταση θα αναφέρει μόνο τη χρήση που παραπέμπει σε κώδικα στο JDT:
org.eclipse.jdt.*
Το μοτίβο πρέπει να είναι μια κανονική έκφραση με έγκυρη μορφή, όπως ορίζεται εδώ.
Όχι
report Ορίστε τη θέση εξόδου στην οποία θα δημιουργηθούν οι αναφορές.

Μετά την ολοκλήρωση της εργασίας, οι αναφορές είναι διαθέσιμες σε αυτόν τον κατάλογο με τη χρήση μιας ιεραρχικής δομής. Δημιουργείται ένας υποφάκελος για κάθε στοιχείο που διαθέτει άλλη δέσμη και παραπέμπει σε αυτό. Κάθε υποφάκελος περιέχει ένα αρχείο με το όνομα "[bundlename].xml". Σε αυτόν το φάκελο βρίσκεται ένας υποφάκελος (με το όνομα "[referencing bundle name].xml") για κάθε δέσμη η οποία παραπέμπει στη δέσμη του περιλαμβανομένου φακέλου. Στο φάκελο δεσμών παραπομπής, βρίσκεται ένας από τρεις υποφακέλους (API, PRIVATE ή OTHER) ο οποίος περιλαμβάνει παραπομπές ειδών, μεθόδων ή πεδίων.

Γίνεται εγγραφή άλλων τριών ειδικών αρχείων στον κατάλογο αναφορών, τα οποία είναι τα αρχεία "counts.xml", "not_searched.xml" και "no_apidescription.xml" και περιλαμβάνουν πληροφορίες σχετικά με το πλήθος των παραπομπών που εντοπίστηκαν, τις δέσμες από τη γραμμή βάσης στις οποίες δεν έγινε αναζήτηση για πληροφορίες χρήσης και τις δέσμες που δεν περιείχαν αρχεία .api_description αντίστοιχα.

Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.

Για παράδειγμα:
  root
   |
   +-- "not_searched.xml"
   +-- "no_apidescription.xml"
   +-- "counts.xml"
   +-- όνομα δέσμης με χρήση
   		|
   		+--όνομα δέσμης με παραπομπή
   			|
   			+-- [API ή PRIVATE ή OTHER]
   				|
   				+--[type_ ή method_ ή field_]references.xml
Ναι
considerinternal Καθορίζει αν κατά την αναζήτηση πρέπει να ληφθούν υπόψη εσωτερικές παραπομπές.

Η προεπιλεγμένη τιμή είναι false.
Όχι
considerapi Καθορίζει αν κατά την αναζήτηση πρέπει να ληφθούν υπόψη παραπομπές API.

Η προεπιλεγμένη τιμή είναι false.
Όχι
considerillegaluse Καθορίζει αν κατά την αναζήτηση πρέπει να ληφθούν υπόψη παραπομπές μη έγκυρης χρήσης API.

Η προεπιλεγμένη τιμή είναι false.
Όχι
apipatterns Διαχωρισμένη με κόμματα λίστα μοτίβων πακέτων ονομάτων (κανονικές εκφράσεις) για να θεωρηθούν πακέτα API.

Από προεπιλογή οι περιγραφές API χρησιμοποιούνται στις δέσμες που ανιχνεύονται, αλλά μπορούν να χρησιμοποιηθούν για την αντικατάσταση ή προσθήκη πακέτων API.
Όχι
internalpatterns Διαχωρισμένη με κόμματα λίστα μοτίβων πακέτων ονομάτων (κανονικές εκφράσεις) για να θεωρηθούν ιδιωτικά πακέτα.

Από προεπιλογή οι περιγραφές API χρησιμοποιούνται στις δέσμες που ανιχνεύονται, αλλά μπορούν να χρησιμοποιηθούν για την αντικατάσταση ή προσθήκη ιδιωτικών πακέτων.
Όχι
archivepatterns Λίστα διαχωρισμένη με κόμματα με ταυτότητες αρχείων αποθήκευσης προς παράβλεψη κατά την ανίχνευση.

Η ταυτότητα ενός αρχείου αποθήκευσης έχει τη μορφή: [ταυτότητα δέσμης]:[διαδρομή αρχείου αποθήκευσης].
Όχι
excludelist Ορίστε τη θέση της λίστας εξαιρέσεων.

Η θέση της λίστας εξαιρέσεων καθορίζει ένα αρχείο κειμένου στο οποίο εμφανίζονται οι δέσμες που θα εξαιρεθούν από την ανάλυση. Από προεπιλογή, αναλύονται όλες οι δέσμες του προφίλ. Τα γνωρίσματα λίστας συμπεριλήψεων και εξαιρέσεων μπορούν να χρησιμοποιηθούν για την επιλεκτική συμπερίληψη ή εξαίρεση δεσμών. Η λίστα συμπεριλήψεων παρέχει το αρχικό σύνολο με τις δέσμες που θα αναλυθούν (αν παραλειφθεί, συμπεριλαμβάνονται όλες οι δέσμες). Στη συνέχεια εφαρμόζεται η λίστα εξαιρέσεων. Κάθε γραμμή του αρχείου καθορίζει ένα από τα εξής:
  • ένα όνομα δέσμης
  • μια κανονική έκφραση για την αναζήτηση ονομάτων δεσμών (γραμμές που αρχίζουν με "R:")
  • ένα σχόλιο (γραμμές που αρχίζουν με '#')

Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ακολουθεί ένα παράδειγμα λίστας εξαιρέσεων:
# EXCLUDED BUNDLES
R:org\.eclipse\..*\.doc\..*
...
Όχι
includelist Ορίζει τη θέση της λίστας συμπεριλήψεων.

Η θέση της λίστας συμπεριλήψεων καθορίζει ένα αρχείο κειμένου στο οποίο εμφανίζονται οι δέσμες που θα συμπεριληφθούν στην ανάλυση. Από προεπιλογή, αναλύονται όλες οι δέσμες του προφίλ. Τα γνωρίσματα λίστας συμπεριλήψεων και εξαιρέσεων μπορούν να χρησιμοποιηθούν για την επιλεκτική συμπερίληψη ή εξαίρεση δεσμών. Η λίστα συμπεριλήψεων παρέχει το αρχικό σύνολο με τις δέσμες που θα αναλυθούν (αν παραλειφθεί, συμπεριλαμβάνονται όλες οι δέσμες). Στη συνέχεια εφαρμόζεται η λίστα εξαιρέσεων. Κάθε γραμμή του αρχείου καθορίζει ένα από τα εξής:
  • ένα όνομα δέσμης
  • μια κανονική έκφραση για την αναζήτηση ονομάτων δεσμών (γραμμές που αρχίζουν με "R:")
  • ένα σχόλιο (γραμμές που αρχίζουν με '#')

Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ακολουθεί ένα παράδειγμα λίστας συμπεριλήψεων:
# INCLUDED BUNDLES
R:org\.eclipse\..*
...
Όχι
φίλτρα Ορίστε τον κεντρικό κατάλογο των φίλτρων API που θα χρησιμοποιηθούν κατά την ανίχνευση χρήσης.

Το όρισμα είναι ο κεντρικός κατάλογος των αρχείων .api_filters που πρέπει να χρησιμοποιηθούν για το φιλτράρισμα των παραπομπών.

Τα αρχεία .api_filters καθορίζουν συγκεκριμένα προβλήματα προς παράβλεψη κατά την ανάλυση api. Κατά την ανίχνευση χρήσης, τα φίλτρα προβλημάτων μετατρέπονται σε μια λίστα παραπομπών η οποία φιλτράρεται από τα αποτελέσματα ανίχνευσης χρήσης.

Ο κεντρικός κατάλογος καθορίζεται με τη χρήση μιας απόλυτης διαδρομής.
Ο κεντρικός κατάλογος πρέπει να περιλαμβάνει την ακόλουθη δομή:
 root
  |
  +-- όνομα λειτουργικού τμήματος (π.χ. org.eclipse.jface)
         |
         +--- .api_filters
Όχι
debug Ορίστε την τιμή για τον εντοπισμό και τη διόρθωση σφαλμάτων.

Οι πιθανές τιμές είναι: true, false
Η προεπιλεγμένη τιμή είναι false.
Όχι

Παραδείγματα

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

Εκτελεί την εργασία που δημιουργεί τα αρχεία *.xml στο φάκελο /eclipse/apiuse-both/XML. Η εργασία θα αναζητήσει όλες τις δέσμες στη θέση του προϊόντος - που ορίζεται από την κανονική έκφραση .* - για όλες τις παραπομπές σε οποιαδήποτε δέσμη της οποίας η ταυτότητα ξεκινά με org.eclipse (όπως ορίζεται από την κανονική έκφραση org\.eclipse.*). Θα χρησιμοποιήσει το αρχείο λίστας εξαιρέσεων D:\exclude_list_external.txt για τη μείωση του αριθμού των προβλημάτων στην αναφορά.

Κατά τη διάρκεια της ανίχνευσης, οποιαδήποτε αρχεία κλάσης εντοπιστούν στο αρχείο αποθήκευσης /libs/contributed.jar στη δέσμη org.eclipse.test.bundle θα παραβλεφθούν.

Αν έχει ενεργοποιηθεί η λειτουργία εντοπισμού και διόρθωσης σφαλμάτων, στην κονσόλα Ant θα εμφανιστούν ορισμένες πληροφορίες ιχνηλασίας.

Σχετικές παραπομπές

Εργασία Ant αναστολής API
Εργασία Ant δημιουργίας αρχείων
Εργασία Ant μετατροπής αναφορών ανάλυσης
Εργασία Ant μετατροπής αναφορών αναστολής API
Εργασία Ant κατάργησης ΑΡΙ
Εργασία Ant μετατροπής αναφορών κατάργησης API
Εργασία Ant μετατροπής αναφορών χρήσης API