Αυτή η εργασία πραγματοποιεί ολοκληρωμένη αναζήτηση μιας συγκεκριμένης γραμμής βάσης για τη δημιουργία μιας αναφοράς χρήσης ΑΡΙ.
Η ανάλυση δεν συμπεριλαμβάνει δέσμες που δεν διαθέτουν τη δυνατότητα εργαλείων 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 |
Ορίστε τη θέση της λίστας εξαιρέσεων.
Η θέση της λίστας εξαιρέσεων καθορίζει ένα αρχείο κειμένου στο οποίο εμφανίζονται οι δέσμες που θα εξαιρεθούν από την ανάλυση. Από προεπιλογή, αναλύονται όλες οι δέσμες του προφίλ. Τα γνωρίσματα λίστας συμπεριλήψεων και εξαιρέσεων μπορούν να χρησιμοποιηθούν για την επιλεκτική συμπερίληψη ή εξαίρεση δεσμών. Η λίστα συμπεριλήψεων παρέχει το αρχικό σύνολο με τις δέσμες που θα αναλυθούν (αν παραλειφθεί, συμπεριλαμβάνονται όλες οι δέσμες). Στη συνέχεια εφαρμόζεται η λίστα εξαιρέσεων. Κάθε γραμμή του αρχείου καθορίζει ένα από τα εξής:
Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής. Ακολουθεί ένα παράδειγμα λίστας εξαιρέσεων: # EXCLUDED BUNDLES R:org\.eclipse\..*\.doc\..* ... |
Όχι |
| includelist |
Ορίζει τη θέση της λίστας συμπεριλήψεων.
Η θέση της λίστας συμπεριλήψεων καθορίζει ένα αρχείο κειμένου στο οποίο εμφανίζονται οι δέσμες που θα συμπεριληφθούν στην ανάλυση. Από προεπιλογή, αναλύονται όλες οι δέσμες του προφίλ. Τα γνωρίσματα λίστας συμπεριλήψεων και εξαιρέσεων μπορούν να χρησιμοποιηθούν για την επιλεκτική συμπερίληψη ή εξαίρεση δεσμών. Η λίστα συμπεριλήψεων παρέχει το αρχικό σύνολο με τις δέσμες που θα αναλυθούν (αν παραλειφθεί, συμπεριλαμβάνονται όλες οι δέσμες). Στη συνέχεια εφαρμόζεται η λίστα εξαιρέσεων. Κάθε γραμμή του αρχείου καθορίζει ένα από τα εξής:
Η θέση καθορίζεται με τη χρήση μιας απόλυτης διαδρομής. Ακολουθεί ένα παράδειγμα λίστας συμπεριλήψεων: # 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