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.

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ő.

Á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ő: 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ő. További ésszerű szabályok:

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.

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).

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).

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.

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.

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.

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. 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.