Eclipse-platform
API-regler

Version 0.15 - sidst revideret 30. maj 2001 kl. 12

I det følgende beskrives reglerne for klienters brug af Eclipse-platformens API og andre komponenter.

Hvad betyder det at være API

Eclipse-platformen definerer API-elementer, der kan bruges af dens kunder, som er ISV'er, der skriver plugins. Disse plugins kan også selv definere API-elementer for deres kunder osv. API-elementer er ansigtet udadtil: de indeholder en angivelse af, hvad de skal gøre, og hvordan de skal bruges. API-elementer er understøttet: Eclipse-platformsteamet retter implementeringsfejl, hvor der er en afvigelse fra den angivne funktionsmåde. Eftersom der ofte er en høj omkostning forbundet med at introducere API-ændringer, vil Eclipse-platformsteamet også forsøge at udvikle API-elementer gradvist gennem på hinanden følgende store releases.

Sådan skelner du mellem API'er og ikke-API'er

API'er er i følge deres natur dokumenterede og har en specifikation i modsætning til ikke-API-elementer, som er interne implementeringsdetaljer, der normalt udgives uden dokumentation eller specifikationer. Hvis du derfor ikke kan finde dokumentationen til et element, er det normalt en god indikation af, at det ikke er API.

Som et forsøg på at trække skillelinjen mere kraftigt op, er kodebasen for platformen delt i API- og ikke-API-pakker, hvor alle API-elementer er erklæret i præcist angivne API-pakker.

Alt andet anses for at være interne implementeringsdetaljer, som ingen klienter har adgang til. Lovlig klientkode må aldrig referere til navnene på ikke-API-elementer, heller ikke ved brug af Java-refleksion. I nogle tilfælde bruges Java-sprogets navneadgangsregler til at afvise ugyldige referencer. Der er imidlertid mange tilfælde, hvor det ikke er muligt. Hvis du overholder følgende regel, kan du undgå problemet:

Generelle regler

Specifikationen af API-elementer genereres ud fra Javadoc-kommentarer i elementets Java-kildekode. For visse elementtyper er specifikationen i form af en kontrakt. I tilfældet med metoder er kontrakten f.eks. mellem to parter, kalderen af metoden og implementoren af metoden. Grundreglen er: Udtrykket "must" i en API-kontrakt betyder, at det er partens pligt at sikre, at betingelsen altid opfyldes. Hvis denne pligt ikke opfyldes, anses det for at være en programmeringsfejl med uspecificerede og muligvis uforudsigelige konsekvenser. Andre fornuftige regler:

Kald af offentlige API-metoder

For de fleste klienter fungerer størstedelen af Eclipse-API'et som offentlige metoder til API-grænseflader eller -klasser, som klienten kan kalde, når det er nødvendigt.

Oprettelse af forekomster af platforms-API-klasser

Det er ikke alle konkrete API-klasser, som hvem som helst kan oprette forekomster af. API-klasser kan have en oprettelseskontrakt, som angiver vilkårene for oprettelse af forekomster. Kontrakten kan også dække andre emner som f.eks. tilbageværende ansvar for initialisering (f.eks. konfiguration af en bestemt egenskab, før forekomsten er fuldstændigt aktiv) og tilhørende ansvar for livscyklus (f.eks. kald af dispose() for at frigive styresystemressourcer, som forekomsten benytter). De klasser, der er designet til, at klienter kan oprette forekomster af dem, er udtrykkeligt markeret i Javadoc-klassekommentaren med sætninger som f.eks. "Clients may instantiate".

Oprettelse af underklasser af platforms-API-klasser

Kun en delmængde af API-klasserne er designet til at kunne oprettes som underklasser. API-klasser har en underklassekontrakt, som angiver vilkårene for erklæring af underklasser. Kontrakten dækker også ansvar for initialisering og livscyklus. De klasser, der er designet til, at klienter kan oprette underklasser af dem, er udtrykkeligt markeret i Javadoc-klassekommentaren med sætninger som f.eks. "Clients may subclass".

Kald af beskyttede API-metoder

Det er generelt tilladt at kalde overtagne beskyttede og offentlige metoder inde fra en underklasse. Det kræver imidlertid ofte mere omhyggelighed at kalde dem på denne måde end at kalde offentlige metoder uden for hierarkiet.

Tilsidesættelse af API-metoder

Kun en delmængde af de offentlige og beskyttede API-metoder er designet til at blive tilsidesat. Hver API-metode har en underklassekontrakt, som angiver vilkårene for, at en underklasse kan tilsidesætte den. Tilsidesættelse er som standard ikke tilladt. Det er vigtig at undersøge underklassekontrakten for den aktuelle metodeimplementering, der tilsidesættes, fordi vilkårene i underklassekontrakterne ikke automatisk overføres sammen med den metode, der tilsidesættes.

Implementering af platforms-API-grænseflader

Kun en delmængde af API-grænsefladerne er designet til at kunne implementeres af klienter. API-grænseflader har en kontrakt, som angiver vilkårene for deres implementering. De grænseflader, der er designet til at blive implementeret af klienter, er udtrykkeligt markeret i Javadoc-klassekommentaren med sætninger som f.eks. "Clients may implement". En klient kan kun erklære en undergrænseflade af en API-grænseflade, hvis klienten har tilladelse til at implementere den.

Implementering af offentlige API-metoder

Se "Tilsidesættelse af API-metoder".

Adgang til felter i API-klasse og -grænseflader

Klienter kan læse API-felter, hvoraf de fleste er "final". Visse struct-lignende objekter har ikke-final offentlige felter, som klienter kan læse og skrive, medmindre andet er angivet.

Konvertering af objekter med en kendt API-type

Et objekt med en kendt API-type kan kun konverteres til en anden API-type (eller konverteres betinget vha. instanceof), hvis det udtrykkeligt er tilladt i API'et.

Det er naturligvis altid uhensigtsmæssigt at konvertere et objekt til en ikke-API-klasse eller grænseflade.

Hvis reglerne ikke følges

Der er en konsekvens ved at overtræde reglerne, uanset om det er tilsigtet eller uforvarende. Det ville måske være lettere for alle involverede parter, hvis der var et API-politi, som straffede for overtrædelse af reglerne. Det er imidlertid ikke tilfældet. Overholdelsen af API'er er mest baseret på tillid, hvor hver klient er ansvarlig for at kende og overholde reglerne.

Kontrakterne på API-elementerne afgrænser den funktionsmåde, der er understøttet og anerkendt. Efterhånden som Eclipse-platformen modnes og udvikler sig, vil det være API-kontrakterne, der styrer udviklingen. Uden for disse kontrakter er intet understøttet og kan når som helst ændres uden varsel, selv mellem releases eller forskellige styresystemer. Hvis klientkoden ikke overholder de ovenstående regler, kan der opstå fejl på forskellige versioner og rettelsesniveauer af platformen. Der kan også opstå fejl, når koden afvikles på de underliggende styresystemer, med en forskellige blanding af samtidigt installerede pluginS, med et andet arbejdsbænkperspektiv og så videre. Der er ingen, som interesserer sig for, præcist hvordan en bestemt overtrædelse senere kan skabe problemer for dig. Til dem, som vælger at ignorere reglerne: Sig ikke, at du ikke blev advaret. Og forvent ikke andet end: "Hvad sagde vi".

På den anden side skal enhver klient-plugin-kode, som overholder de ovenstående regler, kunne fungere på forskellige versioner og rettelsesniveauer af platformen, på de forskellige underliggende styresystemer og i fredelig sameksistens med andre plugins. Hvis alle følger reglerne, udgør Eclipse-platformen en stabil og understøttet basis for nye og spændende produkter.