Eclipse-plattform
API-regler som gjelder

Versjon 0.15 - Sist endret 12.00, 30. mai 2001

Her er reglene som gjelder for klienter av APIen for Eclipse-plattformen (og andre komponenter).

Hva det betyr å være API

Eclipse-plattformen definerer API-elementer som skal brukes av klientene, det vil si ISVer som skriver til plugin-moduler. Disse plugin-modulene kan så definere API-elementer for klientene, og så videre. API-elementer er det ansiktet utad: de inneholder en spesifikasjon om hva det er meningen at de skal gjøre, og om hvordan det er meningen at de skal brukes. API-elementer støttes: Eclipse-plattformgruppen vil rette implementeringsfeil der det er avvik fra den spesifiserte virkemåten. Siden det ofte er kostnadskrevende med store API-endringer, vil Eclipse-plattformgruppen også prøve å utvikle API-elementer gradvis gjennom suksessive hovedutgaver.

Hvordan skille API fra ikke-API

API-elementer er av natur dokumentert og har en spesifikasjon, i motsetning til ikke-API-elementer som er interne implementeringer som vanligvis ikke har publisert dokumentasjon eller spesifikasjoner. Så hvis det er noe du ikke finner dokumentasjon om, er det vanligvis en god indikasjon på at det ikke er en API.

For å prøve å gjøre forskjellen tydeligere er kodegrunnlaget delt inn i API-pakker og ikke-API-pakker, der alle API-elementene er oppgitt i definerte API-pakker.

Alt annet blir betraktet som interne implementeringsdetaljer og er forbudt område for alle klienter. Tillatt klientkode må aldri referere til navn på ikke-API-elementer (selv ikke med Java-refleksjon). I noen tilfeller blir Java-språkets tilgjengelighetsregler for navn brukt for å hindre ugyldige referanser. Det er imidlertid mange tilfeller der dette ganske enkelt ikke er mulig. Hvis du følger denne ene enkle regelen, unngår du problemet fullstendig:

Generelle regler

Spesifikasjonene av API-elementer blir generert fra Javadoc-kommentarer i elementets Java-kildekode. For noen typer elementer er spesifikasjonen i form av en kontrakt. Når det for eksempel gjelder metoder, er kontrakten mellom to parter, den som kaller opp metoden, og den som implementerer metoden. Den grunnleggende regelen er: Termen "må" (must), når den er brukt i en API-kontrakt, betyr at parten plikter å sikre at betingelsen alltid blir oppfylt. Hvis parten unnlater å gjøre det, blir det betraktet som en programmeringsfeil med uspesifiserte (og kanskje uventede) konsekvenser. Andre fornuftige regler:

Kalle opp felles API-metoder

For de fleste klienter vil størstedelen av Eclipse-APIen være i form av fellesmetoder i API-grensesnitt eller klasser, slik at klienten kan kalle dem opp ved behov.

Opprette forekomster av plattform-API-klasser

Det er ikke meningen at hvem som helst skal kunne opprette forekomster av alle konkrete API-klasser. API-klasser har en kontrakt om opprettelse av forekomster som viser betingelsene for opprettelse av forekomster. Kontrakten kan også dekke ting som residual initialiseringsansvar (for eksempel konfigurering av en bestemt egenskap før forekomsten er fullstendig aktiv) og tilknyttet livssyklusansvar (for eksempel å kalle opp dispose() for å frigjøre OS-ressurser som forekomsten opptar). Klasser som er utformet slik at klienter kan opprette forekomster av dem, er eksplisitt flagget i Javadoc-klassekommentaren (med ord som "Clients may instantiate.").

Definere subklasser for plattform-API-klasser

Det er bare et delsett av API-klassene som ble utformet med tanke på å definere subklasser. API-klasser har en subklassekontrakt som viser betingelsene for definering av subklasser. Denne kontrakten dekker også initialiseringsansvar og livssyklusansvar. Klasser som er utformet slik at klienter kan definere subklasser for dem, er eksplisitt flagget i Javadoc-klassekommentaren (med ord som "Clients may subclass.").

Kalle opp beskyttede API-metoder

Det er vanligvis tillat å kalle opp arvede beskyttede metoder og fellesmetoder fra en subklasse. Du må imidlertid ofte være mer forsiktig når du gjør det, enn når du kaller opp fellesmetoder fra utenfor hierarkiet.

Overstyre API-metoder

Det er bare et delsett av felles og beskyttede API-metoder som ble utformet med tanke på å bli overstyrt. Hver API-metode har en subklassekontrakt som viser betingelsene for at en subklasse kan overstyre den. Som standard er overstyring ikke tillat. Det er viktig å kontrollere subklassekontrakten for metodeimplementeringen som faktisk blir overstyrt. Betingelsene i subklassekontrakter blir ikke sendt automatisk når metoden blir overskrevet.

Implementere plattform-API-grensesnitt

Det er bare et delsett av API-grensesnitt som ble utformet med tanke på å bli implementert av klienter. API-grensesnitt har en kontrakt som viser betingelsene for å implementere dem. Grensesnitt som er utformet slik at klienter kan implementere dem, er eksplisitt flagget i Javadoc-klassekommentaren (med ord som "Clients may implement."). En klient kan deklarere et delgrensesnitt for et API-grensesnitt hvis, og bare hvis, det er tillatt at klienter implementerer det.

Implementere felles API-metoder

Se "Overstyre API-metoder".

Få tilgang til felt i API-klasser og grensesnitt

Klienter kan lese API-felt, og de fleste er endelige. Enkelte strukturliknende objekter har kanskje fellesfelt som ikke er endelige, og disse kan klientene lese og skrive til, hvis ikke annet er oppgitt.

Omdanne objekter av en kjent API-type

Et objekt av en kjent API-type kan bare omdannes til en annen API-type (eller betinget omdannes med instanceof) hvis dette er eksplisitt tillatt i APIen.

Og det er selvfølgelig alltid uheldig å omdanne et objekt til en ikke-API-klasse eller et grensesnitt.

Hvis reglene ikke følges

Enten det gjøres bevisst eller uforvarende får det konsekvenser hvis reglene ikke overholdes. Det ville kanskje vært enklere for alle parter hvis det var et API-politi som arresterte deg hvis du brøt reglene. Slik er det imidlertid ikke. API-samsvar fungerer stort sett som et system som ikke kontrolleres, der hver klient har ansvar for å kjenne til reglene og følge dem.

Kontraktene for API-elementene setter grenser for virkemåten som støttes og opprettholdes. Etter som Eclipse-plattformen modnes og utvikles, er det API-kontraktene som styrer hvordan denne utviklingen skjer. Utenfor disse kontraktene støttes ingenting, og alt kan endres uten forvarsel og når som helst (selv mellom utgaver eller mellom forskjellige OS-plattformer). Klientkode som bryter reglene over, mislykkes kanskje på forskjellige versjoner og rettelsesnivåer av plattformen, når de kjøres på forskjellige underliggende operativsystemer, når de kjøres med en annen blanding av plugin-moduler som ligger i minnet, når de kjøres med et annet arbeidsbenkperspektiv, og så videre. Det er ingen som er spesielt interessert i å spekulere på nøyaktig hvilke konsekvenser et bestemt regelbrudd kan få. Til de av dere som velger å ignorere reglene, kan dere ikke komme og si at dere ikke ble advart. Og ikke forvent stort mer enn en et medfølende "Hva var det jeg sa".

På den annen side, plugin-kode fra klienter som følger reglene over, skal fortsette å virke på forskjellige versjoner og rettelsesnivåer av plattformen, på forskjellige underliggende operativsystemer, og skal kunne eksistere sammen med andre plugin-moduler uten problemer. Hvis alle følger spillereglene, gir Eclipse-plattformen en stabil og støttet basis som det kan bygges spennende nye produkter på.