Eclipse platform
API-felhasználás szabályai
Verziószám: 0.15 - Utolsó felülvizsgálat: 2001. május 30. 12:00 óra
Az alábbiakban az Eclipse platform API (és más összetevők) ügyfeleire
vonatkozó felhasználási szabályok olvashatók.
Az API fogalom jelentése
Az Eclipse platform API elemeket határoz meg ügyfelei, nevezetesen a
bedolgozókat író külső szoftvergyártók használatára.
Ezek a bedolgozók aztán API elemeket határozhatnak meg saját
ügyfeleik számára, és így tovább. Az API elemek a bárki számára
hozzáférhető felületet alkotják: meghatározást hordoznak arról,
hogyan kell működniük, valamint tervezett felhasználásukról. Az
API elemekhez terméktámogatás jár, azaz az Eclipse platform
munkacsoport kijavít bármely, a megadottól eltérő viselkedést
okozó megvalósítási hibát. Mivel az API változtatások bevezetése
gyakran magas költséggel jár együtt, az Eclipse platform
munkacsoport igyekszik az API elemeket az egymást követő fő
kiadások között gördülékenyen kifejleszteni.
Az API megkülönböztetése attól, ami nem az
Természetükből adódóan, az API elemek dokumentáltak és van
meghatározásuk, ezzel szemben a nem-API elemek a belső megvalósítás
részét képzik, és általában nincs nyilvános dokumentációjuk vagy
meghatározásuk. Ezért ha valaminek a dokumentációja nem
található, akkor az erősen utal arra, hogy az illető dolog nem
API.
Talán még erősebben meghúzható a határ a két fogalom között a
következőképpen: a platform kódalapja API és nem-API csomagokra oszlik
úgy, hogy minden API elem deklarációja saját API csomagjában van.
-
API-csomag - legalább egy API osztályt vagy felületet
tartalmazó Java csomag. Az API csomagok nevei az adott összetevő
dokumentációjában kerülnek közzétételre, emellett ahol ez
megoldható, az "internal" szó szerepel minden olyan csomag
nevében, amely csak a megvalósítás részleteit tartalmazza. Az
API csomagok nevei érvényesen megjelenhetnek az ügyfélkódban.
Magán az Eclipse platformon belül ezek a következők:
-
org.eclipse.foo.* - például org.eclipse.swt.widgets,
org.eclipse.ui,
vagy org.eclipse.core.runtime
-
org.eclipse.foo.internal.* - nem az API, hanem a belső
megvalósítás részét képző csomagok
-
org.eclipse.foo.examples.* - nem API, hanem példagyűjtemény
-
org.eclipse.foo.tests.* - nem API, hanem tesztkészlet
-
API osztály vagy felület - egy API csomagban található
nyilvános osztály vagy felület, illetve más API osztály vagy
felület által öröklött vagy abban deklarált nyilvános vagy
védett osztály vagy felület.
Az API osztályok, illetve felületek nevei érvényesen
megjelenhetnek az ügyfélkódban.
-
API metódus vagy konstruktor - egy API osztály vagy
felület által örökölt vagy abban deklarált nyilvános
vagy védett metódus vagy konstruktor. Az API metódusok nevei érvényesen
megjelenhetnek az ügyfélkódban.
-
API mező - egy API osztály vagy felület által örökölt vagy abban
deklarált nyilvános vagy védett mező. Az API mezők nevei
érvényesen megjelenhetnek az ügyfélkódban.
Bármi más a belső megvalósítás részének tekinthető, amihez a
hozzáférés tiltott minden ügyfél számára. Az érvényes ügyfélkód
soha nem tartalmazhat hivatkozást nem-API elemekre (még Java
Reflection használatával sem). Bizonyos esetekben az érvénytelen
hivatkozások tiltása a Java nyelv név-hozzáférhetőségi szabályainak
alkalmazása révén valósul meg.
Ugyanakkor számos olyan eset van, amelyekben ez egyszerűen nem
lehetséges. Az alábbi egyszerű szabály betartásával
a probléma teljesen elkerülhető.
-
Ragaszkodjon a hivatalosan dokumentált API csomagokhoz. Csak az
összetevő közzétett API Javadocjában dokumentált csomagokra
hivatkozzon.
Soha ne hivatkozzon a nevében az "internal" szót tartalmazó
komponenshez tartozó csomagra---ezek soha nem API csomagok. Soha
ne hivatkozzon olyan csomagra, amelyhez nem tartozik közzétett
API Javadoc---ezek sem API csomagok.
Általános szabályok
Az API elemek meghatározása az egyes elemek Java forráskódjában
található Javadoc megjegyzésekből áll elő. Bizonyos elemtípusok
esetében a meghatározás formája szerződés. Például a metódusok
esetében a szerződés két fél között jön létre, ezek egyfelől a
metódus meghívója, másfelől a metódus megvalósítója. Az alapvető
ökölszabály a következő:
-
Minden szerződést tiszteletben kell tartani. A
szerződések leírása a használt elemekre vonatkozó, közzétett
Javadocokban található.
Az API szerződésekben szereplő "kell" szó azt jelenti, hogy a
szerződő fél köteles gondoskodni a feltétel mindenkori
betartásáról. Ennek elmulasztása nem meghatározott (és
valószínűleg megjósolhatatlan) következményekkel járó
programozói hibának tekinthető.
-
A "kell" szót tiszteletben kell tartania. Különösen szigorúan
tartsa be azokat a feltételeket, amelyekben a "kell" szó szerepel.
További ésszerű szabályok:
-
Ne támaszkodjon a véletlenszerű viselkedésre. A véletlenszerű
viselkedés megfigyelhető kísérletek során vagy a gyakorlatban, de
semmilyen API-meghatározás nem garantálja.
-
Ne kezelje a nullértéket objektumként. A nullérték inkább
az objektum hiányaként fogható fel.
Amennyiben az API meghatározás nem mond mást, tekintsen mindent
nem-nullértéknek.
-
Ne próbáljon a Java Reflection használatával csalni. A Java
Reflection használata a Java fordítóprogram ellenőrző rutinjainak
kikerülésére semmilyen hasznot nem hoz. Nem léteznek a Java
Reflection használatára vonatkozó kiegészítő API szerződések,
így az csak a nem meghatározott viselkedésre vagy a belső
megvalósítás egy részére való támaszkodás esélyét növeli.
-
Használja a saját csomagjait. Ne deklaráljon kódot más
komponenshez tartozó csomagban. Mindig a saját kódját deklarálja
a saját csomagjában.
Nyilvános API metódusok meghívása
A legtöbb ügyfél esetében az Eclispse API felületeket és osztályokat kezelő
nyilvános metódusokból áll, melyeket az ügyfél a megfelelő helyzetben
meghívhat.
-
Biztosítsa az előfeltételeket. A meghívni kívánt API
metódus előfeltételeinek teljesítését mindenképpen biztosítsa a
meghívás előtt. Ezzel együtt a hívó mindig nyugodtan
kiindulhat abból a feltételezésből, hogy a metódus
kilépési feltételei a hívásból való visszatérés után
azonnal teljesülni fognak.
-
Nullparaméterek API metódusnak ne adjon át
nullparamétert, kivéve, ha a paraméter dokumentációja
kifejezetten jelzi, hogy ez engedélyezett. Ez talán a
leggyakrabban elkövetett programozói hiba.
-
Korlátozott hívók Ne hívjon meg olyan API metódust,
amely dokumentációjának értelmében csak bizonyos hívók számára
elérhető, kivéve, ha Ön is egy ezek közül. Néhány helyzetben a
metódusoknak a hívók bizonyos (gyakran belső) osztályainak
érdekében a nyilvános API részét kell képezniük, de ezeknek a
metódusoknak a nem megfelelő alkalomkor történő meghívása nem
dokumentált (és valószínűleg megjósolhatatlan) következményekkel
jár.
-
Hibakeresési metódusok Ne hívjon meg olyan API
metódusokat, melyek a "csak hibakeresési célokra" megjelölést
viselik. Ebbe a kategóriába tartozik például a legtöbb
toString() metódus.
-
Paraméterek rögzítése. Ne adjon át olyan tömböt,
kollekciót vagy más változékony objektumot egy metódusnak
paraméterként, amelyet átadás után módosít. Ezzel csak kihívja
maga ellen a sorsot.
Platformfüggő API osztályok példányosítása
Nem minden konkrét API osztály célja, hogy bárki példányosíthassa.
Az API osztályokhoz a példányok létrehozásának feltételeit rögzítő
példányosítási szerződések tartoznak. A szerződés kiterjedhet olyan
dolgokra is, mint további inicializálási kötelmek (például egy bizonyos
tulajdonság beállítása még mielőtt a példány teljesen aktívvá válna)
valamint életciklusra vonatkozó kötelmek (például a dispose()
eljárás meghívása a példány által lefoglalt operációsrendszer-erőforrások
felszabadításának érdekében). Az ügyfelek általi példányosításara szánt
osztályokat a Javadoc osztálymegjegyzések kifejezetten megjelölik (az
"ügyfelek által példányosítható", vagy hasonló szavakkal).
-
Korlátozott példányosítók Ne példányosítson meg olyan API
osztályt, amely dokumentációjának értelmében csak bizonyos felek
számára elérhető, kivéve, ha Ön is egy ezek közül.
Néhány helyzetben az
osztályoknak a felek bizonyos (gyakran belső) osztályainak érdekében a
nyilvános API részét kell képzeniük, de ezeknek az osztályoknak a nem
megfelelő alkalomkor történő példányosítása nem dokumentált (és
valószínűleg megjósolhatatlan) következményekkel jár.
Platformfüggő API osztályok továbbszármaztatása
Tervezőik az API osztályoknak csupán egy részhalmazát szánták
továbbszármaztatásra. Az API osztályokhoz az alosztályok deklarálásának
feltételeit rögzítő alosztályszerződések tartoznak. Ezek a szerződések
kiterjednek az inicializálásra, illetve az életciklusra vonatkozó
kötelmekre is. Az ügyfelek általi továbbszármaztatásra szánt osztályokat a
Javadoc osztálymegjegyzések kifejezetten jelölik (az "ügyfelek által
továbbszármaztatható", vagy hasonló szavakkal).
-
Korlátozott továbbszármaztatók Ne származtasson tovább
olyan API osztályokat, melyeket tervezőik nem szántak erre a
célra. Kezelje ezeket az osztályokat úgy, mintha véglegesnek
deklarálták volna őket. (Ezek időnként "átmenetileg végleges"
osztályokként szerepelnek).
Védett API metódusok meghívása
Az öröklött védett és nyilvános metódusok meghívása egy
alosztályon belülről általában engedélyezett, ugyanakkor az
ilyen esetkben a helyes meghívás gyakran több figyelemet
igényel, mint a nyilvános metódusok hierarchián kívülről
történő meghívása.
API metódusok felülbírálása
Tervezőik a védett és nyilvános API metódusoknak csupán egy
részhalmazát szánták felülbírálásra. Az API metódusokhoz az
alosztályok általi felülbírálás feltételeit rögzítő
alosztályszerződések tartoznak. Alapértelmezésben a felülbírálás
nem engedélyezett.
Fontos a felülbírált metódus megvalósítására vonatkozó
alosztályszerződés ellenőrzése, mivel az alosztályszerződés
feltételei a metódus felülbírálásakor nem kerülnek automatikusan
továbbadásra.
-
Ne bíráljon felül nyilvános és védett API metódusokat,
kivéve, ha ez kifejezetten engedélyezett. Hacsak nincs
ennek ellenkezőjére utalás, kezelje minden metódus
deklarációját véglegesnek. (Ezek némely esetben "átmenetileg
végleges" metódusokként ismertek).
Amennyiben az engedélyezett
felülbírálás jellege:
- "implement" (megvalósítás)- az alosztályra deklarált absztrakt
metódust konkrét alosztálynak kell megvalósítania
- "extend" (kiterjesztés) - az alosztályra deklarált metódusnak
a szülőosztályra kell meghívnia a metódust (pontosan egyszer)
- "re-implement" (újramegvalósítás) - az alosztályra deklarált
metódusnak nem szabad a metódust a szülőosztályra meghívnia
- "override" (felülbírálás) - az alosztályra deklarált metódus
meghívhatja a metódust a szülőosztályra, amennyiben azt
szükségesnek tartja
-
Biztosítsa a kilépési feltételeket. Visszatéréskor
mindenképpen biztosítsa az API metódusra megadott összes
kilépési feltételnek a megvalósítás általi teljesítését.
-
Megelőző jelleggel ellenőrizze az előfeltételek teljesülését. Ne
induljon ki abból a feltételezésből, hogy az API metódusra
megadott feltételek belépéskor szükségképpen adottak. Bár a
metódus megvalósításának jogában áll eltekinteni a megadott
előfeltételek ellenőrzésétől, általában jó ötlet ezt mégis
megtenni (amennyiben kivitelezhető és költséghatékonysága
ésszerű határokon belül van), így téve lehetővé a rosszul
viselkedő hívók észlelését.
-
Nulleredmény. API metódusból eredményként ne adjon vissza
nullértéket, hacsak (a meghatározó felületre vagy szülőosztályra
vonatkozó) dokumentáció kifejezetten nem jelzi, hogy az eredmény
nullértéke engedélyezett.
-
Adjon vissza másolatokat. API metódus eredményeként ne adjon
vissza nem cserélhető tömböt, kollekciót vagy más változékony
objektumot. Mindig másolatot adjon vissza, így kerülve el
azokat a problémákat, melyeket az objektumot esetlegesen
módosító hívók okozhatnak.
Platformfüggő API felületek megvalósítása
Tervezőik az API felületeknek csupán egy részhalmazát szánták a
ügyfelek általi megvalósításra. Az API felületekhez azok
megvalósításának feltételeit rögzítő szerződések tartoznak. Az
ügyfelek általi megvalósításara szánt felületeket a Javadoc
osztálymegjegyzések kifejezetten jelölik (az "ügyfelek által
megvalósítható", vagy hasonló szavakkal). Ügyfelek akkor és csak
akkor deklarálhatnak egy felülethez alfelületeket, ha azok
megvalósítása számukra engedélyezett.
-
Korlátozott megvalósítók. Ne valósítson meg olyan API
felületet, amely dokumentációjának értelmében csak bizonyos felek
számára elérhető, kivéve, ha Ön is egy ezek közül. Több olyan
helyzet is van, amelyben a felületek használatának célja a
megvalósítás belső részleteinek elrejtése.
Nyilvános API metódusok megvalósítása
Lásd az "API metódusok felülbírálása" c. részt.
Mezők elérése API osztályokban és felületeken
Az API mezők, melyeknek nagy része végleges, az ügyfelek számára
olvashatók. Bizonyos struct jellegű objektumoknak lehetnek olyan nem
végleges nyilvános mezőik, melyek - hacsak nem vonatkozik rájuk ellenkező
értelmű utasítás - az ügyfelek számára olvashatók és írhatók is.
-
Nullmezők. API mezők értékét ne állítsa nullra, kivéve, ha
ez kifejezetten megengedett.
Ismert típusú API objektumok átalakítása
Ismert típusú API objektum csak akkor alakítható át más
típusra, (illetve alakítható át feltételesen az "instanceof"
használatával) ha ezt az API kifejezetten lehetővé teszi.
-
A típusmódosítás és az "instanceof". Ne használjon
"instanceof", illetve típusmódosító kifejezéseket annak
érdekében, hogy többet tudjon meg egy objektumról annál,
amennyit az API támogat.
A helytelen használat véletlenszerűen veszélyeztet olyan
megvalósítási részleteket, amelyekre az API nem vállal
garanciát.
Emellett természetesen minden esetben helytelen bármely objektum
típusának módosítása nem-API osztályra vagy felületre.
Szabályok be nem tartása
Akár tudatosan, akár szándéktalanul történik, a szabályok
megszegésének következményei vannak. Talán minden érintett fél
számára jobb lenne, ha létezne egy olyan API rendőrség, amely
elkapja a szabályok megszegőit. A dolog azonban nem így áll.
Az API feltételeknek való megfelelés jobbára olyan becsületen alapuló
rendszerként működik, melyben minden ügyfél felelős a szabályok ismeretéért
és azok betartásáért.
Az API elemekre vonatkozó szerződések behatárolják a
támogatott és fenntartott viselkedési formát. Az Eclipse
platform érése és fejlődése során az API szerződések fogják a
fejlődés útját kijelölni. Ami ezeken a szerződéseken kívül esik,
az nem támogatott és bármikor külön értesítés nélkül
megváltoztatható (akár ugyanazon kiadáson belül vagy különböző
operációs rendszerekre készült változatok között is). A fenti szabályokat
megszegő ügyfélkód hibásan működhet a platform különféle verzióin és
javítási szintjein, amikor a futtatás alapjául különféle operációs
rendszerek szolgálnak, amikor mások a telepített bedolgozók, vagy akkor,
amikor más munkaterület-nézetben fut, és így tovább. Ami azt illeti, a legkevésbé sem
érdekel senkit annak találgatása, hogyan bosszulhatja meg magát bármely
adott szabályszegés. Azok, akik a szabályok figyelmen kívül hagyását
választják, nem mondhatják, hogy senki nem figyelmeztette őket. Ne is
számítsanak sokkal többre, mint egy együttérző "Én előre megmondtam"
megjegyzés.
Másfelől viszont, az olyan ügyfél bedolgozókódnak, amelyeknek létezését a
fenti szabályok irányítják, a platform különféle verzióin és javítási
szintjein, különféle alapul szolgáló operációs rendszereken is futniuk kell,
és békésen együtt kell élniük más bedolgozókkal. Ha mindenki
betartja a játékszabályokat, az Eclipse platform olyan stabil és
támogatott alapként fog szolgálni, amelyre izgalmas új termékek
építhetők.