Eclipse-ympäristö
Ohjelmointirajapinnan (API) käyttösäännöt

Versio 0.15 - viimeksi muutettu 30.5.2001 klo 12.00

Seuraavassa esitetään Eclipse-ympäristön sovellusohjelmaliittymän (ja muiden komponenttien) asiakkaita koskevat käyttösäännöt.

Sovellusohjelmaliittymän olemus

Eclipse-ympäristö määrittää API-elementtejä asiakkaidensa (eli lisäosia kirjoittavien riippumattomien ohjelmistotoimittajien) käyttöön. Näissä lisäosissa voidaan puolestaan määrittää API-elementtejä niiden asiakkaita varten, ja niin edelleen. API-elementit edustavat julkista osaa: ne sisältävät määrityksen siitä, mitä niiden oletetaan tekevän ja miten niitä on tarkoitus käyttää. API-elementtejä tuetaan: Eclipse-ympäristön työryhmä korjaa toteutusvirheet, jos poikkeamia määritetystä toiminnasta esiintyy. Koska suuret sovellusohjelmaliittymän muutokset ovat usein kalliita, Eclipse-ympäristön työryhmä pyrkii myös kehittämään API-elementtejä sulavasti julkaisemalla toisiaan seuraavia päälaitoksia.

Sovellusohjelmaliittymän erottaminen muista elementeistä

Luonteensa mukaisesti API-elementit ovat dokumentoituja ja niillä on määritys, toisin kuin muut elementit, jotka ovat sisäisiä toteutustietoja ja joihin ei tavallisesti liity julkaistua dokumentaatiota tai julkaistuja määrityksiä. Jos siis dokumentaatiota ei löydy, se yleensä osoittaa, ettei kyseessä ole sovellusohjelmaliittymä.

Eron selventämiseksi ympäristön koodilähde on jaettu API-paketteihin ja muihin kuin API-paketteihin ja kaikki API-elementit esitellään määritetyissä API-paketeissa.

Kaikkea muuta pidetään sisäisenä toteutustietona, joka on kielletty kaikilta asiakkailta. Kelvollinen asiakkaan koodi ei saa koskaan viitata muiden kuin API-elementtien nimiin (ei edes Java-peilauksen kautta). Joissakin tapauksissa luvattomat viittaukset hylätään Java-kielen nimenkäyttösääntöjen avulla. Monissa tapauksissa tämä ei kuitenkaan ole yksinkertaisesti mahdollista. Seuraavan yksinkertaisen säännön noudattaminen poistaa ongelman kokonaan:

Yleisiä sääntöjä

API-elementtien määritys muodostetaan elementin Java-lähdekoodissa olevista Javadoc-kommenteista. Joidenkin elementtityyppien osalta määritys on sopimuksen muodossa. Esimerkiksi metodien kohdalla sopimus on kahden osapuolen, metodin kutsujan ja metodin toteuttajan, välinen. Perussääntö on seuraava: Jos API-sopimuksessa käytetään termiä "täytyy", se tarkoittaa, että osapuoli on velvollinen varmistamaan, että ehto täyttyy aina. Jos niin ei tapahdu, kyseessä on ohjelmointivirhe, jolla on määrittämättömiä (ja kenties odottamattomia) seurauksia. Seuraavassa on muita käytännön ohjeita:

Julkisten API-metodien kutsuminen

Useimpien asiakkaiden kohdalla pääosa Eclipse-sovellusohjelmaliittymästä on API-rajapintojen tai -luokkien julkisina metodeina, joita asiakas voi tarvittaessa kutsua.

Ympäristön API-luokkien ilmentymien luonti

Ei ole tarkoitus, että kuka tahansa luo kaikkien konkreettisten API-luokkien ilmentymiä. API-luokilla on ilmentymänluontisopimus, jossa on määritetty ehdot, joiden mukaan ilmentymiä voi luoda. Sopimuksen piiriin voivat kuulua myös esimerkiksi jäljelle jääneet alustusvelvollisuudet (esimerkiksi jonkin tietyn ominaisuuden määritys, ennen kuin ilmentymästä tulee täysin aktiivinen) ja elinkaareen liittyvät velvollisuudet (esimerkiksi dispose()-metodin kutsuminen vapauttamaan ilmentymän varaamia käyttöjärjestelmän resursseja). Luokat, joista asiakkaiden on tarkoitus luoda ilmentymiä, on merkitty erikseen Javadoc-luokkakommenttiin (esimerkiksi Asiakkaat voivat luoda ilmentymiä -tekstillä).

Aliluokkien määritys ympäristön API-luokista

Vain osa API-luokista on tarkoitettu aliluokkien määritystä varten. API-luokilla on aliluokkasopimus, jossa on määritetty ehdot, joiden mukaan aliluokkia voi esitellä. Tämän sopimuksen piiriin kuuluvat myös alustusvelvollisuudet ja elinkaareen liittyvät velvollisuudet. Luokat, joista asiakkaiden on tarkoitus määrittää aliluokkia, on merkitty erikseen Javadoc-luokkakommenttiin (esimerkiksi Asiakkaat voivat määrittää aliluokkia -tekstillä).

Suojattujen API-metodien kutsuminen

Perittyjen suojattujen ja julkisten metodien kutsuminen aliluokasta on yleensä sallittua. On kuitenkin oltava huolellisempi näiden metodien kutsumisessa, jotta se tapahtuisi oikein, kuin julkisten metodien kutsumisessa hierarkian ulkopuolelta.

API-metodien korvaus

Vain osa julkisista ja suojatuista API-metodeista on tarkoitettu korvattavaksi. Jokaisella API-metodilla on aliluokkasopimus, jossa on määritetty ehdot, joiden mukaan aliluokka voi korvata sen. Oletusarvoisesti korvaus ei ole sallittua. On tärkeää käydä läpi korvattavaa metodin toteutusta koskeva aliluokkasopimus. Aliluokkasopimusten ehtoja ei välitetä automaattisesti, kun metodi korvataan.

Ympäristön API-rajapintojen toteutus

Vain osa API-rajapinnoista on tarkoitettu asiakkaiden toteutettavaksi. API-rajapinnoilla on sopimus, jossa on määritetty ehdot, joiden mukaan ne voidaan toteuttaa. Asiakkaiden toteutettaviksi tarkoitetut rajapinnat on merkitty erikseen Javadoc-luokkakommenttiin (esimerkiksi Asiakkaat voivat toteuttaa -tekstillä). Asiakas voi esitellä API-rajapinnan alirajapinnan vain, jos asiakkaan sallitaan toteuttaa se.

Julkisten API-metodien toteutus

Katso kohta API-metodien korvaus.

API-luokkien ja -rajapintojen kenttien käyttö

Asiakkaat voivat lukea API-kenttiä, joista useimmat ovat lopullisia. Tietyissä struct-tyyppisissä objekteissa voi olla ei-lopullisia julkisia kenttiä, joita asiakkaat voivat lukea ja joihin he voivat kirjoittaa, ellei muuta mainita.

Tunnettuun API-lajiin kuuluvien objektien lajinvaihto

Tunnettuun API-lajiin kuuluvan objektin laji voidaan vaihtaa toiseksi API-lajiksi (tai vaihtaa ehdollisesti toiseksi instanceof-lausekkeen avulla) vain, jos se on erikseen sallittu sovellusohjelmaliittymässä.

Objektin lajinvaihto siten, että tuloksena on muu kuin API-luokka tai -rajapinta, ei myöskään ole koskaan sopivaa.

Sääntöjen noudattamatta jättäminen

Sääntöjen tietoisella tai tahattomalla rikkomisella on seurauksia. Kaikille osapuolille voisi olla helpompaa, jos olisi API-poliisi, joka pidättäisi sääntöjen rikkojat. Sellaista ei kuitenkaan ole. Suurimmaksi osaksi sovellusohjelmaliittymän yhdenmukaisuus perustuu siihen, että kaikki asiakkaat tuntevat säännöt ja noudattavat niitä.

API-elementtejä koskevat sopimukset rajoittavat tuettuja ja ylläpidettyjä toimintatapoja. Eclipse-ympäristön edelleen kehittyessä API-sopimukset ohjaavat sen kehitystä. Sopimuksia lukuun ottamatta kaikki muu on tuen ulkopuolella ja muutettavissa ilman erillistä ilmoitusta milloin tahansa (jopa kesken laitoksen tai eri käyttöjärjestelmäympäristöjen välillä). Edellä esitettyjä sääntöjä rikkova asiakkaan koodi ei välttämättä toimi ympäristön eri versioissa ja eri korjaustasoilla tai silloin, kun sitä ajetaan esimerkiksi eri käyttöjärjestelmissä, kun käytössä on erilainen rinnakkaisten lisäosien yhdistelmä tai kun sen ajossa käytetään eri työympäristöperspektiiviä. Kukaan ei edes ole kovinkaan kiinnostunut arvailemaan, millä tavalla sääntöjen rikkomus kostautuu niiden rikkojalle. Jos joku päättää rikkoa sääntöjä, häntä on ainakin varoitettu. Eikä kannata odottaa juuri muuta kuin, että joku sanoo myötätuntoisesti "minähän sanoin".

Toisaalta edellä esitettyjen sääntöjen mukaisen asiakkaan lisäosakoodin pitäisi toimia ympäristön eri versioissa ja korjaustasoilla, eri käyttöjärjestelmissä ja muiden lisäosien kanssa. Jos kaikki toimivat sääntöjen mukaan, Eclipse-ympäristö muodostaa vakaan ja tuetun perustan, jolle voidaan kehittää kiinnostavia uusia tuotteita.