Πλατφόρμα Eclipse
Κανόνες χρήσης για το API

Εκδοχή 0.15 - Τελευταία αναθεώρηση στις 30 Μαΐου 2001, 12:00

Σε αυτή την ενότητα παρουσιάζονται οι κανόνες για τη χρήση του API από τους πελάτες της πλατφόρμας Eclipse (και των άλλων συστατικών στοιχείων).

Ορισμός των στοιχείων API

Η πλατφόρμα Eclipse ορίζει τα στοιχεία API που θα χρησιμοποιηθούν από τους πελάτες του, δηλαδή τις πρόσθετες λειτουργίες εγγραφής ISV. Αυτές οι πρόσθετες λειτουργίες ορίζουν με τη σειρά τους στοιχεία API για τους πελάτες τους και ούτω καθεξής. Τα στοιχεία API είναι το δημόσιο πρόσωπο: φέρουν προδιαγραφές σχετικά με αυτά που πρέπει να κάνουν και για το πώς πρέπει να χρησιμοποιηθούν. Για τα στοιχεία API παρέχεται υποστήριξη: η ομάδα της πλατφόρμας Eclipse θα διορθώσει σφάλματα υλοποίησης, όπου υπάρχει απόκλιση από την καθορισμένη συμπεριφορά. Καθώς συχνά το κόστος που σχετίζεται με αλλαγές συμπεριφοράς API είναι υψηλό, η ομάδας της πλατφόρμας Eclipse θα προσπαθήσει επίσης να εξελίξει ομαλά τα στοιχεία API με διαδοχικές κύριες εκδόσεις.

Πώς διακρίνεται ένα στοιχείο API από ένα στοιχείο που δεν είναι API

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

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

Οποιοδήποτε άλλο στοιχείο θεωρείται λεπτομέρεια εσωτερικής υλοποίησης και είναι απαγορευμένο για όλους τους άλλους πελάτες. Ο νόμιμος κώδικας πελάτη ποτέ δεν πρέπει να παραπέμπει στα ονόματα των στοιχείων μη API (ούτε καν χρησιμοποιώντας τον έλεγχο και τροποποίηση κώδικα Java κατά το χρόνο εκτέλεσης). Σε ορισμένες περιπτώσεις, για να μην επιτρέπονται οι μη αποδεκτές παραπομπές, χρησιμοποιούνται οι κανόνες πρόσβασης της γλώσσας Java όσον αφορά τα ονόματα. Ωστόσο, υπάρχουν πολλές περιπτώσεις όπου αυτό είναι απλώς αδύνατον. Με την τήρηση του μοναδικού και απλού κανόνα, που θα αναφέρουμε αμέσως παρακάτω, το πρόβλημα αποφεύγεται εντελώς:

Γενικοί κανόνες

Οι προδιαγραφές των στοιχείων API δημιουργούνται από σχόλια Javadoc στον πρωτογενή κώδικα Java του στοιχείου. Για ορισμένα είδη στοιχείων, οι προδιαγραφές έχουν τη μορφή συμφωνίας. Για παράδειγμα, στην περίπτωση μεθόδων, η συμφωνία αφορά δύο οντότητες, το στοιχείο υποβολής κλήσης της μεθόδου και το περιβάλλον υλοποίησης της μεθόδου. Ο θεμελιώδης βασικός κανόνας είναι ο εξής: Όταν χρησιμοποιείται σε μια συμφωνία API ο όρος "πρέπει", σημαίνει ότι επιβάλλεται στην οντότητα να διασφαλίσει ότι η συνθήκη θα ικανοποιείται πάντα. Στην αντίθετη περίπτωση, θα θεωρείται σφάλμα προγραμματισμού με απροσδιόριστες (και ίσως μη αναμενόμενες) συνέπειες. Άλλοι κανόνες κοινής λογικής:

Κλήση δημόσιων μεθόδων API

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

Δημιουργία χρήσεων για τις κλάσεις του API της πλατφόρμας

Δημιουργία χρήσεων δεν μπορεί να γίνει από οποιονδήποτε και για όλες τις υπαρκτές κλάσεις API. Για τις κλάσεις API υπάρχει μια συμφωνία για τη δημιουργία χρήσεων, η οποία δηλώνει τους όρους υπό τους οποίους μπορούν να δημιουργηθούν χρήσεις. Η συμφωνία μπορεί επίσης να καλύψει ζητήματα όπως είναι οι υπευθυνότητες απόδοσης αρχικών τιμών για παραμένοντα προγράμματα (για παράδειγμα η ρύθμιση μιας συγκεκριμένης ιδιότητας προτού η χρήση καταστεί πλήρως ενεργή) και οι σχετιζόμενες υπευθυνότητες κύκλου ζωής (για παράδειγμα, η κλήση του dispose() για να ελευθερωθούν πόροι του λειτουργικού συστήματος που δεσμεύονται από τη χρήση). Κλάσεις των οποίων ο σχεδιασμός επιτρέπει τη δημιουργία χρήσεων από πελάτες επισημαίνονται ρητά με ενδείκτη στο σχόλιο της κλάσης Javadoc (με διατύπωση του τύπου "Clients may instantiate" [Επιτρέπεται η δημιουργία χρήσεων από τους πελάτες])..

Μετατροπή των κλάσεων του API της πλατφόρμας σε υπο-κλάσεις

Μόνο ένα υποσύνολο των κλάσεων API σχεδιάστηκε ώστε να διατίθεται ως υπο-κλάση. Για τις κλάσεις API υπάρχει μια συμφωνία υπο-κλάσεων που δηλώνει τους όρους βάσει των οποίων μπορούν να δηλωθούν υπο-κλάσεις. Αυτή η συμφωνία καλύπτει επίσης υπευθυνότητες απόδοσης αρχικών τιμών και κύκλου ζωής. Κλάσεις των οποίων ο σχεδιασμός επιτρέπει να μετατρέπονται σε υπο-κλάσεις από τους πελάτες επισημαίνονται ρητά με ενδείκτη στο σχόλιο της κλάσης Javadoc (με διατύπωση του τύπου "Clients may subclass" [Επιτρέπεται η μετατροπή σε υπο-κλάση από τους πελάτες])..

Κλήση προστατευμένων μεθόδων API

Η κλήση μεταβιβασμένων, προστατευμένων και δημόσιων μεθόδων μέσα από μια υπο-κλάση γενικά επιτρέπεται. Ωστόσο, για να γίνει σωστά η κλήση, απαιτείται συχνά μεγαλύτερη προσοχή από αυτήν που απαιτεί η κλήση δημόσιων μεθόδων έξω από την ιεραρχία.

Αντικατάσταση μεθόδων API

Μόνο ένα υποσύνολο των δημόσιων και προστατευμένων μεθόδων API σχεδιάστηκε ώστε να αντικαθίσταται. Για κάθε μέθοδο API υπάρχει μια συμφωνία υπο-κλάσης που δηλώνει τους όρους υπό τους οποίους μπορεί να αντικατασταθεί από μια υπο-κλάση. Από προεπιλογή, δεν επιτρέπεται η αντικατάσταση. Είναι σημαντικό ο χρήστης να ελέγξει τη συμφωνία υπο-κλάσης για την πραγματική υλοποίηση μεθόδου που αντικαθίσταται. Οι όροι των συμφωνιών για την υπο-κλάση δεν μεταβιβάζονται αυτόματα όταν αντικαθίσταται η συγκεκριμένη μέθοδος.

Υλοποίηση διεπαφών API πλατφόρμας

Μόνο ένα υποσύνολο των διεπαφών API σχεδιάστηκε ώστε να υλοποιείται από πελάτες. Για τις διεπαφές API υπάρχει μια συμφωνία που δηλώνει τους όρους υπό τους οποίους μπορούν να υλοποιηθούν. Διεπαφές των οποίων ο σχεδιασμός επιτρέπει να υλοποιούνται από τους πελάτες επισημαίνονται ρητά με ενδείκτη στο σχόλιο της κλάσης Javadoc (με διατύπωση του τύπου "Clients may implement" [Επιτρέπεται η υλοποίηση από τους πελάτες]).. Ένας πελάτης μπορεί να δηλώσει μια υπο-διεπαφή μιας διεπαφής API, αποκλειστικά και μόνο αν επιτρέπεται να την υλοποιήσει.

Υλοποίηση δημόσιων μεθόδων API

Δείτε την ενότητα "Αντικατάσταση μεθόδων API"

Πρόσβαση σε πεδία σε κλάσεις και διεπαφές API

Οι πελάτες μπορούν να διαβάσουν πεδία API, από τα οποία τα περισσότερα είναι τελικά. Συγκεκριμένα αντικείμενα τύπου struct, ενδέχεται να έχουν μη τελικά δημόσια πεδία, τα οποία οι πελάτες μπορούν να διαβάσουν και στα οποία μπορούν να εγγράψουν, εκτός αν ορίζεται διαφορετικά.

Μετατροπή αντικειμένων ενός γνωστού είδους API

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

Και φυσικά, ποτέ δεν ενδείκνυται η μετατροπή οποιουδήποτε αντικείμενου σε κλάση ή διεπαφή μη API.

Μη συμμόρφωση με τους κανόνες

Η εκούσια ή ακούσια παραβίαση των κανόνων έχει ορισμένες συνέπειες. Μπορεί να ήταν πιο εύκολο για όλους τους εμπλεκόμενους αν υπήρχε μια αστυνομία για το API, που θα συλλάμβανε οποιονδήποτε παραβίαζε τους κανόνες. Ωστόσο, κάτι τέτοιο δεν υπάρχει. Ως επί το πλείστον, η συμμόρφωση με τους κανόνες για το API λειτουργεί σαν κώδικας τιμής, όπου ο κάθε πελάτης έχει την ευθύνη να γνωρίζει τους κανόνες και να τους εφαρμόζει.

Οι συμφωνίες για τα στοιχεία API οριοθετούν τη συμπεριφορά που υποστηρίζεται και συντηρείται. Καθώς η πλατφόρμα Eclipse ωριμάζει και εξελίσσεται, οι συμφωνίες API θα είναι αυτές που θα οδηγούν αυτή την εξέλιξη. Εκτός αυτών των συμφωνιών, τίποτα δεν τεκμηριώνεται και όλα υπόκεινται σε αλλαγές, χωρίς προειδοποίηση, οποιαδήποτε στιγμή (ακόμα και κατά τη διάρκεια μιας έκδοσης ή μεταξύ διαφορετικών πλατφόρμων λειτουργικού συστήματος). Ο κώδικας πελάτη που παραβιάζει τους παραπάνω κανόνες, ενδέχεται να αποτύχει σε διάφορες εκδοχές και διάφορα επίπεδα επιδιόρθωσης της πλατφόρμας, όταν εκτελείται σε διαφορετικά υποκείμενα λειτουργικά συστήματα, με διαφορετικό συνδυασμό πρόσθετων λειτουργιών που συνυπάρχουν στη μνήμη, με μια διαφορετική προοπτική του πάγκου εργασίας κ.ο.κ. Πράγματι, κανέναν δεν ενδιαφέρουν ιδιαίτερα ούτε καν οι υποθέσεις σχετικά με το πώς μια συγκεκριμένη παραβίαση κανόνα μπορεί να έχει συνέπειες αργότερα. Όσοι λοιπόν επιλέξουν να παραβλέπουν τους κανόνες, δεν μπορούν να ισχυριστούν ότι δεν προειδοποιήθηκαν. Και δεν πρέπει να περιμένουν τίποτα πέρα από τη συμπονετική αντίδραση των άλλων.

Από την άλλη πλευρά, ο κώδικας πρόσθετης λειτουργίας πελάτη που τηρεί τους παραπάνω κανόνες, πρέπει να συνεχίσει να εργάζεται σε όλες τις εκδόσεις και τα επίπεδα επιδιόρθωσης της πλατφόρμας, σε διαφορετικά υποκείμενα λειτουργικά συστήματα και πρέπει να συνυπάρχει αρμονικά με τις άλλες πρόσθετες λειτουργίες. Αν οι κανόνες γίνουν σεβαστοί από όλους, η πλατφόρμα Eclipse θα αποτελέσει μια σταθερή και ισχυρή βάση στην οποία θα δομηθούν εξαιρετικά ενδιαφέροντα νέα προϊόντα.