Platforma Eclipse
Pravidla rozhraní API závazku

Verze 0.15 - Poslední revize 12:00, 30. květen 2001

V tomto textu uvádíme pravidla závazku pro klienty rozhraní API platformy Eclipse (a jiných komponent).

Co znamená API

Platforma Eclipse definuje prvky API pro účely svých klientů, tj. nezávislých dodavatelů modulů plug-in. Tyto moduly plug-in mohou naopak definovat prvky rozhraní API pro své klienty atd. Prvky API představují vnější tvář: nesou specifikaci o účelu a způsobu svého použití. Pro prvky API je poskytována podpora: pracovní skupina platformy Eclipse opravuje chyby implementace na místech výskytu odchylek od specifikovaného chování. Protože obvykle v souvislosti s výraznými změnami rozhraní API vznikají vysoké náklady, pokusí se pracovní skupina platformy Eclipse rovněž o zapracování oprav prvků API do hlavních verzí.

Jak rozeznat prvky API od prvků mimo API

Na rozdíl od prvků mimo API, které jsou vnitřní implementací a obvykle k nim není poskytnuta dokumentace či specifikace, prvky API jsou zásadně dokumentovány a opatřeny specifikacemi. Nemůžete-li nalézt dokumentaci určitého prvku, jde o spolehlivý příznak skutečnosti, že nejde o prvek rozhraní API.

V zájmu výraznějšího odlišení je kódovací báze platformy rozdělena na balíčky rozhraní API a balíčky mimo API a všechny prvky rozhraní API jsou deklarovány ve vyhrazených balíčcích API.

Vše ostatní je považováno za podrobnost vnitřní implementace a mimo dosah všech klientů. Správný kód klienta nesmí odkazovat na názvy prvků mimo API (ani používat obraz Java). V určitých případech se pravidla přístupnosti názvů jazyka Java používají ke znemožnění nepovolených odkazů. Je však řada případů, ve kterých to není možné. Dodržováním následujícího jednoduchého pravidla se problému zcela vyhnete:

Obecná pravidla

Specifikace prvků API je vygenerována z komentářů dokumentace Javadoc ve zdrojovém kódu Java prvku. Pro určité typy prvků má specifikace formu kontraktu. Například v případě metod tento kontrakt uzavírají dvě strany, objekt volající metodu a objekt, který metodu implementuje. Základní pravidlo: Termín "je třeba" použitý v kontraktu API znamená, že daná strana má za povinnost zajistit splnění podmínky za všech okolností; jakékoli selhání v této věci je považováno za chybu programování s nespecifikovanými (a možná i nepředvídatelnými) následky. Ostatní smysluplná pravidla:

Volání veřejných metod API

Pro většinu klientů má celek rozhraní API Eclipse formu veřejných metod rozhraní či tříd API, které může klient volat dle potřeby.

Vytváření instalací tříd API platformy

Některé třídy API neumožňují vytváření svých instancí komukoli. Třídy API mají kontrakt o vytváření instancí, který uvádí podmínky vytvoření instance. Tento kontrakt může upravovat rovněž kompetence zbytkové inicializace (např. konfigurace určitých vlastností před úplnou aktivací instance) a kompetence přiřazeného životního cyklu (např. volání dispose() za účelem uvolnění zdrojů operačního systému, které byly použity instancí). Třídy určené k vytváření instancí klienty jsou výslovně označeny v komentáři Javadoc třídy (slovy "Klienti mohou vytvářet instance").

Vytvoření podtřídy tříd API platformy

Pouze podmnožina tříd API umožňuje vytváření podtříd. Třídy API mají kontrakt o podtřídě, který uvádí podmínky deklarace podtříd. Tento kontrakt rovněž upravuje kompetence inicializace a životního cyklu. Třídy určené k vytváření podtříd klienty jsou výslovně označeny v komentáři Javadoc třídy (slovy "Klienti mohou vytvářet podtřídy").

Volání chráněných metod API

V obecném případě je povoleno volání zděděných chráněných a veřejných metod z podtřídy; nicméně je v takovýchto případech často zapotřebí postupovat s větší obezřetností, než při volání veřejných metod z místa mimo hierarchii.

Potlačení metod API

Potlačovat lze pouze podmnožinu veřejných a chráněných metod API. Každá z metod API má kontrakt o podtřídě, jež určuje podmínky, za kterých lze podtřídu potlačit. Ve výchozím nastavení není potlačení povoleno. Je zapotřebí kontrolovat smlouvu o podtřídě potlačované implementace třídy; podmínky smlouvy podtřídy nejsou při potlačení metody automaticky předávány.

Implementace rozhraní API platformy

Pouze podmnožina rozhraní API je určena k implementaci klienty. Rozhraní API mají kontrakt, jenž určuje podmínky jejich implementace. Rozhraní určená k implementaci klienty jsou výslovně označena v komentáři Javadoc třídy (slovy "Klienti mohou implementovat"). Klient může deklarovat podřízené rozhraní pro rozhraní API pouze v případě, že může toto rozhraní implementovat.

Implementace veřejných metod API

Viz "Potlačení metod API".

Přístup do polí tříd a rozhraní API

Klienti mohou číst pole API. Většina těchto polí je konečná. Určité objekty typu struct mohou obsahovat nefinální veřejná pole. Není-li uvedeno jinak, mohou klienti tato pole číst a zapisovat do nich.

Přetypování objektů známého typu API

Objekt známého typu může být převeden pouze na jiný známý typ API (příp. může být přetypován podmíněně s použitím instanceof), pokud je to v API výslovně povoleno. Rovněž není vhodné měnit typ objektu na třídu či rozhraní mimo API.

Nedodržení pravidel

Vědomé i neúmyslné překročení pravidel má své následky. Pro všechny zúčastněné by bylo snadnější, kdyby byly k dispozici postupy API, které by vám umožnili porušovat stanovená pravidla. Situace je však odlišná. Z větší části pracuje API na základě důvěry a jednotliví klienti nesou odpovědnost za znalost a dodržování pravidel.

Kontrakty prvků API omezují podporované a udržované chování. Platforma Eclipse se vyvíjí a dospívá. Tímto procesem ji provádějí kontrakty API. Mimo tyto kontrakty není nic podporováno a vše se mění bez předchozího upozornění (dokonce i mezi verzemi a různými operačními systémy). Kód klienta překračující výše uvedená pravidla může selhávat na různých verzích a úrovních oprav platformy, při provozu v různých operačních systémech, při provozu s různými kombinacemi současně použitých modulů plug-in nebo při provozu v různých perspektivách pracovní plochy atd. Ve skutečnosti se nikdo nezabývá úvahami o způsobech, kterými mohou jednotlivá přestoupení pravidel nepříznivě ovlivňovat činnost systému. Pokud uvedená pravidla budete ignorovat, nestěžujte si, že jste nebyli varováni. Neočekávejte více než soucitné "Vždyť jsme vám to říkali".

Naopak kód klientského modulu plug-in dodržující výše uvedená pravidla by měl pracovat v různých verzích a úrovních oprav platformy, v různých operačních systémech a měl by bez potíží pracovat vedle ostatních modulů plug-in. Budete-li postupovat podle pravidel, poskytne vám platforma Eclipse stabilní a podporovaný základ vytváření skvělých nových produktů.