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.
-
API-paketti - Java-paketti, jossa on vähintään yksi API-luokka tai -rajapinta. API-pakettien nimet mainitaan kyseisen komponentin dokumentaatiossa. Jos mahdollista, kaikkien muiden vain toteutustietoja sisältävien pakettien nimissä on "internal"-osa. API-pakettien nimet saavat näkyä asiakkaan koodissa. Varsinaisessa Eclipse-ympäristössä nämä paketit ovat seuraavat:
-
org.eclipse.foo.* - esimerkiksi org.eclipse.swt.widgets,
org.eclipse.ui tai org.eclipse.core.runtime
-
org.eclipse.foo.internal.* - eivät ole sovellusohjelmaliittymiä vaan sisäisiä toteutuspaketteja
-
org.eclipse.foo.examples.* - eivät ole sovellusohjelmaliittymiä vaan esimerkkejä
-
org.eclipse.foo.tests.* - eivät ole sovellusohjelmaliittymiä vaan testipaketteja
-
API-luokka tai -rajapinta - API-paketissa oleva julkinen luokka tai rajapinta tai julkinen tai suojattu luokka- tai rajapintajäsen, joka on esitelty jossakin toisessa API-luokassa tai -rajapinnassa tai jonka tällainen luokka tai rajapinta on perinyt.
API-luokkien ja -rajapintojen nimet saavat näkyä asiakkaan koodissa.
-
API-metodi tai konstruktori - julkinen tai suojattu metodi tai konstruktori, joka on esitelty jossakin toisessa API-luokassa tai -rajapinnassa tai jonka tällainen luokka tai rajapinta on perinyt. API-metodien nimet saavat näkyä asiakkaan koodissa.
-
API-kenttä - julkinen tai suojattu kenttä, joka on esitelty jossakin toisessa API-luokassa tai -rajapinnassa tai jonka tällainen luokka tai rajapinta on perinyt. API-kenttien nimet saavat näkyä asiakkaan koodissa.
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:
-
Käytä virallisesti dokumentoituja sovellusohjelmaliittymiä. Viittaa vain sellaisiin paketteihin, jotka on dokumentoitu komponenttiin liittyvässä julkaistussa API Javadoc -asiakirjassa.
Älä koskaan viittaa pakettiin, joka kuuluu sellaiseen toiseen komponenttiin, jonka nimessä on "internal"-osa. Tällainen paketti ei koskaan ole sovellusohjelmaliittymä. Älä koskaan viittaa pakettiin, jolla ei ole julkaistua API Javadoc -asiakirjaa. Tällainen paketti ei myöskään ole sovellusohjelmaliittymä.
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:
-
Kunnioita kaikkia sopimuksia. Sopimukset kuvataan käyttämiäsi API-elementtejä koskevassa julkaistussa Javadoc-asiakirjassa.
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.
-
Kunnioita "täytyy"-sanaa. Kiinnitä erityistä huomiota ehtoihin, joissa "täytyy"-sanaa käytetään.
Seuraavassa on muita käytännön ohjeita:
-
Älä luota sattumanvaraiseen toimintaan. Sattumanvarainen toiminta on kokemuksen perusteella tai käytännössä havainnoitua toimintaa, jota mikään API-määritys ei takaa.
-
Älä pidä null-arvoa objektina. Null-arvo tarkoittaa pikemminkin objektin puutetta.
Kannattaa olettaa, että arvo on muu kuin null, ellei API-määrityksessä mainita muuta.
-
Älä yritä huijata käyttämällä Java-peilausta. Java-peilauksen käyttö Java-kääntäjän tekemän tarkistuksen kiertämiseen ei tuo muuta etua. Peilauksen käyttötapoihin ei liity muita API-sopimuksia. Peilaus vain lisää todennäköisyyttä, että luotetaan määrittämättömään toimintaan ja sisäiseen toteutustietoon.
-
Käytä omia pakettejasi. Älä esittele koodia paketissa, joka kuuluu johonkin toiseen komponenttiin. Esittele oma koodisi aina omissa paketeissasi.
Julkisten API-metodien kutsuminen
Useimpien asiakkaiden kohdalla pääosa Eclipse-sovellusohjelmaliittymästä on API-rajapintojen tai -luokkien julkisina metodeina, joita asiakas voi tarvittaessa kutsua.
-
Varmista ennakkoehdot. Muista varmistaa, että API-metodin ennakkoehdot täyttyvät ennen metodin kutsumista. Vastaavasti kutsuja voi turvallisesti olettaa, että metodin jälkiehdot ovat täyttyneet heti kutsusta palattaessa.
-
Null-parametrit. Älä välitä null-arvoa parametrina API-metodille, ellei parametria ole yksiselitteisesti dokumentoitu null-arvon sallivaksi. Tämä on ehkä yleisin ohjelmointivirhe.
-
Rajoitetut kutsujat. Älä kutsu API-metodia, joka on dokumentoitu vain joidenkin kutsujien käytettäväksi, ellet ole yksi heistä. Joissakin tapauksissa metodien täytyy olla osa julkista sovellusohjelmaliittymää tietyn (usein sisäisten) kutsujien luokan hyödyksi. Jos jotakin tällaista metodia kutsutaan väärään aikaan, sillä on määrittämättömiä (ja kenties odottamattomia) seurauksia.
-
Vianmääritysmetodit. Älä kutsu API-metodia, joka on määritetty vain vianmääritystarkoituksiin. Esimerkiksi useimmat toString()-metodit kuuluvat tähän luokkaan.
-
Parametrin sieppaus. Älä välitä taulukkoa, kokoelmaa tai muuta muuttuvaa objektia parametrina API-metodille ja muokkaa sitten välitettyä objektia. Jos teet niin, ongelmia seuraa.
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ä).
-
Rajoitetut ilmentymien luojat. Älä luo ilmentymää API-luokasta, joka on dokumentoitu vain joidenkin osapuolten käytettäväksi, ellet ole yksi niistä.
Joissakin tapauksissa luokkien täytyy olla osa julkista sovellusohjelmaliittymää tietyn (usein sisäisen) osapuolen hyödyksi. Jos jonkin tällaisen luokan ilmentymä luodaan väärin, sillä on määrittämättömiä (ja kenties odottamattomia) seurauksia.
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ä).
-
Rajoitetut aliluokkien määrittäjät. Älä määritä aliluokkia API-luokasta, josta ei ole tarkoitus määrittää aliluokkia. Käsittele tällaisia luokkia ikään kuin ne olisi esitelty lopullisina. (Näitä luokkia kutsutaan toisinaan ehdollisesti lopullisiksi.)
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.
-
Älä korvaa julkista tai suojattua API-metodia, ellei se ole erikseen sallittua. Ellei toisin mainita, käsittele kaikkia metodeja ikään kuin ne olisi esitelty lopullisina. (Näitä metodeja kutsutaan toisinaan ehdollisesti lopullisiksi.)
Sallittujen korvauslajien merkitykset ovat seuraavat:
- implement - konkreettisen aliluokan täytyy toteuttaa aliluokassa esitelty abstrakti metodi
- extend - aliluokassa esitellyn metodin täytyy kutsua yliluokan metodia (vain kerran)
- re-implement - aliluokassa esitelty metodi ei saa kutsua yliluokan metodia
- override - aliluokassa esitelty metodi voi kutsua vapaasti yliluokan metodia tarpeen mukaan
-
Varmista jälkiehdot. Muista varmistaa, että toteutus täyttää API-metodille määritetyt jälkiehdot palattaessa.
-
Tarkista ennakkoehdot etukäteen. Älä oleta, että API-metodille määritetyt ennakkoehdot olisivat välttämättä täyttyneet syötön yhteydessä. Vaikka metodin toteutus voisikin oikeutetusti jättää määritetyt ennakkoehdot tarkistamatta, niiden tarkistaminen on tavallisesti suositeltavaa (jos se on järkevästi toteutettavissa eikä tule suhteettoman kalliiksi), jotta kurittomien kutsujien toiminta saataisiin loppumaan.
-
Null-tulos. Älä palauta null-arvoa API-metodin tuloksena, ellei erikseen ole dokumentoitu (määrittävässä rajapinnassa tai yliluokassa), että null-arvo on sallittu tulokseksi.
-
Palauta kopioita. Älä palauta korvaamatonta taulukkoa, kokoelmaa tai muuta muuttuvaa objektia API-metodin tuloksena. Palauta aina kopio, jotta välttyisit ongelmilta, joita objektia mahdollisesti muokkaavat kutsujat voivat aiheuttaa.
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.
-
Rajoitetut toteuttajat. Älä toteuta API-rajapintaa, joka on dokumentoitu vain joidenkin osapuolten käytettäväksi, ellet ole yksi niistä. Monissa tapauksissa rajapintojen avulla piilotetaan sisäiset toteutustiedot näkymästä.
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.
-
Null-kentät. Älä aseta API-kenttään null-arvoa, ellei sitä ole erikseen sallittu.
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ä.
-
Cast- ja instanceof-lausekkeet. Älä tee instanceof- ja cast-lausekkeiden avulla objektia koskeviin tietoihin sellaisia lisäyksiä, joita sovellusohjelmaliittymä ei tue.
Jos käytät lausekkeita sopimattomasti, käyttöön tulee satunnaisia toteutustietoja, joita sovellusohjelmaliittymä ei takaa.
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.