Platforma Eclipse
Praca z interfejsem API

Wersja 0.15 - ostatnia aktualizacja: 30 maja 2001 godzina 12:00

Poniżej przedstawiono reguły korzystania przez klientów z interfejsu API oraz innych elementów platformy Eclipse.

Co to jest interfejs API?

Platforma Eclipse definiuje elementy API na użytek swoich klientów, czyli modułów dodatkowych tworzonych przez niezależnych producentów oprogramowania. Te moduły dodatkowe mogą z kolei zawierać definicje elementów API na użytek swoich klientów i tak dalej. Elementy API to zasoby przeznaczone do użytku publicznego - zawierają specyfikację określającą ich działanie i sposób użycia. Elementy API są obsługiwane przez zespół programistyczny platformy Eclipse, co oznacza, że poprawia on błędy implementacji w miejscach, w których jej działanie różni się od działania określonego przez specyfikację. Ponieważ wprowadzanie poważnych zmian w interfejsach API jest związane z dużymi kosztami, zespół programistyczny platformy Eclipse będzie próbował także rozwijać elementy API w kolejnych wersjach głównych.

Jak odróżnić elementy API od innych elementów?

Elementy API są dobrze udokumentowane i mają określoną specyfikację. W odróżnieniu od nich elementy inne niż elementy API składają się tylko z implementacji wewnętrznej i nie mają opublikowanej dokumentacji lub specyfikacji. Jeśli nie można znaleźć dokumentacji danego elementu, zwykle oznacza to, że nie należy on do interfejsu API.

Aby ten podział był bardziej jasny, kod bazowy platformy jest podzielony na pakiety elementów API i pakiety elementów innych niż API, a wszystkie elementy API są deklarowane w odpowiednich pakietach elementów API.

Pozostałe elementy są traktowane jako implementacja wewnętrzna, która jest niedostępna dla wszystkich klientów. Poprawny kod klienta nie może zawierać odwołań do nazw elementów innych niż elementy API. Nie można odwoływać się do tych nazw nawet przy użyciu introspekcji Java. W niektórych przypadkach niedozwolone odwołania są odrzucane przy użyciu reguł dostępności języka Java. Jest jednak wiele sytuacji, w których taka możliwość nie istnieje. Przestrzeganie jednej prostej reguły pozwala całkowicie uniknąć tego problemu:

Reguły ogólne

Specyfikacja elementów API jest generowana na podstawie komentarzy dokumentacji Javadoc w kodzie źródłowym Java danego elementu. Dla niektórych typów elementów specyfikacja ma formę kontraktu. Na przykład w przypadku metod kontrakt wiąże dwie strony: stronę wywołującą metodę i stronę implementującą metodę. W tej sytuacji obowiązuje żelazna zasada: Słowo "musi" użyte w kontrakcie dotyczącym elementu API oznacza, że dana strona ma obowiązek zadbać, aby dany warunek był zawsze spełniony. Niedopełnienie tego obowiązku będzie traktowane jak błąd programistyczny o nieokreślonych i niemożliwych do przewidzenia skutkach. Inne zdroworozsądkowe reguły:

Wywoływanie metod public elementu API

W przypadku większości klientów największa część interfejsu API platformy Eclipse ma postać zestawu metod public zawartych w interfejsach i klasach API, które mogą być w razie potrzeby wywoływane przez klienta.

Tworzenie instancji klas API platformy

W przypadku niektórych klas konkretnych API nie każdy może tworzyć ich instancje. Klasy API podlegają postanowieniom kontraktu dotyczącego tworzenia instancji, który określa warunki, na jakich mogą być tworzone instancje. Warunki kontraktu mogą dotyczyć także pewnych dodatkowych obowiązków w zakresie inicjowania (np. skonfigurowania konkretnej właściwości przed pełnym aktywowaniem instancji) lub związanych z cyklem życia (np. wywołania metody dispose() w celu zwolnienia zasobów systemu operacyjnego zajętych przez instancję). Klasy zaprojektowane tak, aby klienci mogli tworzyć ich instancje, są wyraźnie oznaczone w komentarzach klasy dokumentacji Javadoc (np. słowami Clients may instantiate - Klient może tworzyć instancje).

Tworzenie podklas klas API platformy

Tylko niektóre klasy API mogą służyć jako podstawa do tworzenia podklas. Klasy API podlegają postanowieniom kontraktów dotyczących tworzenia podklas i określających warunki, na jakich można deklarować podklasy. Kontrakt taki dotyczy także obowiązków w zakresie inicjowania i związanych z cyklem życia. Klasy zaprojektowane tak, aby klienci mogli tworzyć ich podklasy, są wyraźnie oznaczone w komentarzach klasy dokumentacji Javadoc (np. słowami Clients may subclass - Klient może tworzyć podklasy).

Wywoływanie metod protected interfejsu API

Wywoływanie dziedziczonych metod protected i public z podklasy jest zwykle dozwolone. Często jednak poprawne wykonanie tej operacji wymaga większej ostrożności niż wywoływanie metod public spoza hierarchii.

Przesłanianie metod API

Tylko niektóre metody public i protected interfejsu API zaprojektowano tak, aby można było je przesłaniać. Każda z metod API podlega postanowieniom kontraktu dotyczącego tworzenia podklasy, który określa warunki, na jakich dopuszczalne jest jej przesłanianie przez podklasę. Domyślnie przesłanianie jest niedozwolone. Ważne jest, aby zapoznać się z warunkami kontraktu dotyczącego tworzenia podklas bieżącej implementacji przesłanianej metody. Przesłonięcie metody nie oznacza, że warunki tego kontraktu są automatycznie spełnione.

Implementowanie interfejsów API platformy

Tylko niektóre interfejsy API zaprojektowano tak, aby możliwe było ich implementowanie przez klientów. Interfejsy API podlegają postanowieniom kontraktów określających warunki, na jakich mogą być implementowane. Interfejsy zaprojektowane tak, aby klienci mogli je implementować, są wyraźnie oznaczone w komentarzach klasy dokumentacji Javadoc (np. słowami Clients may implement - Klient może implementować). Klient może deklarować podinterfejs dla interfejsu API tylko wtedy, gdy jest to dozwolone.

Implementowanie metod public interfejsu API

Patrz: Przesłanianie metod API.

Dostęp do pól w klasach i interfejsach API

Pola API są dostępne dla klientów do odczytu i większość z nich jest polami final. Niektóre obiekty typu struct mogą mieć pola public, które nie będą polami final oraz będą mogły być odczytywane i zapisywane przez klientów (jeśli nie stwierdzono inaczej w dokumentacji).

Rzutowanie obiektów znanego typu API

Obiekt znanego typu API może być rzutowany tylko na inny typ API (lub rzutowany warunkowo przy użyciu operatora instanceof). Jest to możliwe pod warunkiem, że takie działanie jest dozwolone w przypadku danego interfejsu API. Oczywiście rzutowanie obiektu na klasę lub interfejs nie będący elementem API jest zawsze błędem.

Nieprzestrzeganie reguł

Rozmyślne lub przypadkowe naruszenie reguł zawsze ma określone konsekwencje. Właściwie dla wszystkich zainteresowanych byłoby najlepiej, gdyby powołano specjalną jednostkę policji ścigającą osoby naruszające reguły pracy z interfejsami API. Niestety, nie jest to możliwe. W tej sytuacji zgodność z regułami stosowania interfejsów API jest wymogiem swoistego kodeksu honorowego, według którego każdy klient jest sam odpowiedzialny za znajomość reguł i ich przestrzeganie.

Kontrakty związane z poszczególnymi elementami API określają granice, w ramach których działanie tych elementów jest obsługiwane i uznawane. Dalszy rozwój platformy Eclipse będzie postępował według ścieżek wyznaczanych przez kontrakty dotyczące elementów API. Wszystko, czego nie uwzględniono w tych kontraktach, nie jest gwarantowane i może ulec zmianie bez uprzedzenia oraz w dowolnym momencie (nawet podczas dystrybucji oprogramowania bez zmiany numeru wersji oraz w wersjach przeznaczonych dla różnych systemów operacyjnych). Kod klienta nieprzestrzegający tych reguł może działać błędnie w przypadku innej wersji platformy lub platformy z innym zestawem poprawek, po uruchomieniu w innym systemie operacyjnym, w środowisku z innym zestawem modułów dodatkowych, w innej perspektywie środowiska roboczego itd. W praktyce nikt nie zastanawia się, w jaki sposób naruszenie określonej reguły może obrócić się przeciwko niemu. Osoby decydujące się na ignorowanie reguł robią to na własną odpowiedzialność. W razie kłopotów nie powinny one potem oczekiwać niczego poza pełnymi współczucia słowami: "a przecież ostrzegaliśmy".

Natomiast kod modułu dodatkowego klienta, który opracowano zgodnie z powyższymi regułami, powinien poprawnie pracować, bez względu na używaną wersję platformy, stosowany zestaw poprawek, zainstalowany system operacyjny i inne moduły dodatkowe. Osobom przestrzegającym reguł platforma Eclipse zapewni stabilną podstawę, na której można tworzyć wiele nowych i atrakcyjnych produktów.