Eclipse-plattformen
API-regler för användning

Version 0.15 - Senast uppdaterad 12.00 30 maj 2001

Nedan följer regler för användning för klienter till API för Eclipse-plattformen (och andra komponenter).

Vad API innebär

I Eclipse-plattformen definieras API-element som används av klienterna i plattformen, dvs. ISV:er som skapar insticksprogram. I det här insticksprogrammen kan i sin tur API-element definieras för klienterna för dem osv. API-element är det publika gränssnittet: de innehåller en specifikation om vad de ska göra och hur de ska användas. API-element kan användas: Eclipse-plattformsgruppen korrigerar implementeringsfel där avvikelser från angivna funktioner förekommer. Eftersom ändringar av API ofta innebär stora kostnader försöker Eclipse-plattformsgruppen även att smidigt vidareutveckla API-element för stora versioner som följer på varandra.

Så här avgör du om ett element är ett API-element

API-element är per definition dokumenterade och har specifikationer. Element som inte är API-element är intern implementeringsinformation och för dem finns vanligen varken publicerad dokumentation eller specifikationer. Om du inte kan hitta dokumentationen för något är det vanligen ett tecken på att det inte är ett API-element.

Det går att särskilja elementen på ett mer absolut sätt då kodbasen för plattformen är indelad i API- och icke-API-paket och alla API-element deklareras i tilldelade API-paket.

Allt annat anses vara intern implementeringsinformation som inte är tillgänglig för klienter. I giltig klientkod får det aldrig finnas referenser till namn på element som inte är API-element (inte ens när Java-återspegling används). I vissa fall används namntillgänglighetsregler för Java-språket för att ange vilka referenser som inte är tillåtna. I många fall går det dock inte att göra. Du kan undvika problemet helt och hållet genom att följa den här enkla regeln:

Allmänna regler

Specifikationen för API-element genereras från Javadoc-kommentarer i Java-källkoden för elementet. För vissa typer av element genereras specifikationen i form av ett kontrakt. Till exempel beträffande metoder gäller kontraktet två parter, den som anropar metoden och den som implementerar metoden. Den grundläggande regeln är: Termen "must" (måste) innebär, när den används i ett API-kontrakt, att det åligger den ena parten att säkerställa att villkoret alltid uppfylls. I annat fall anses det vara ett programmeringsfel med ej angivna (och möjligen oförutsägbara) konsekvenser. Andra förnuftiga regler:

Anropa publika API-metoder

De flesta klienter använder huvuddelen av Eclipse API som publika metoder i API-gränssnitt eller -klasser. Klienten kan anropa metoderna vid behov.

Instantiera plattforms-API-klasser

Alla konkreta API-klasser är inte avsedda att instantieras av vem som helst. API-klasser har instantieringskontrakt som anger under vilka förhållanden förekomster kan skapas. Kontraktet kan även inbegripa olika typer av ansvar, till exempel residualt initieringsansvar (till exempel konfiguration av en viss egenskap innan förkomsten helt aktiveras) och relaterat livscykelansvar (till exempel anrop av dispose() för att frigöra OS-resurser som förekomsten använder). Klasser som är skapade för att instantieras av klienter är explicit flaggade i Javadoc-klasskommentaren (till exempel med orden "Klienter kan instantiera.").

Underordna plattforms-API-klasser

Endast en delmängd av API-klasserna har skapats för att användas som underordnade klasser. API-klasser har ett kontrakt gällande underordnad klass som anger de villkor som måste vara uppfyllda för att underordnade klasser ska kunna deklareras. Det kontraktet täcker även initieringsansvar och livscykelansvar. Klasser som är skapade för att kunna användas som underordnade klasser av klienter är explicit flaggade i Javadoc-klasskommentaren (till exempel med orden "Klienter kan underordna klassen.").

Anroopsskyddade API-metoder

Det är vanligen tillåtet att anropa ärvda, skyddade och publika, metoder från underordnade klasser. Det kräver dock ofta större noggrannhet än vid anrop till publika metoder som inte görs inifrån hierarkin.

Åsidosätta API-metoder

Endast en delmängd av de publika och skyddade API-metoderna har skapats för att åsidosättas. Varje API-metod har ett kontrakt gällande underordnad klass som anger de villkor som måste vara uppfyllda för att en underordnad klass ska kunna åsidosätta den. Som standard är det inte tillåtet att åsidosätta metoder. Det är viktigt att kontrollera kontraktet gällande underordnad klass för den faktiska metodimplementering som åsidosätts. Villkoren i kontrakt gällande underordnad klass överförs inte automatiskt när metoden åsidosätts.

Implementera plattforms-API-gränssnitt

Endast en delmängd av API-gränssnitten har skapats för att implementeras av klienter. API-gränssnitt har ett kontrakt som anger de villkor som måste vara uppfyllda för att det ska kunna implementeras. Gränssnitt som är skapade för att implementeras av klienter är explicit flaggade i Javadoc-klasskommentaren (till exempel med orden "Klienter kan implementera."). En klient kan deklarera ett underordnat gränssnitt till ett API-gränssnitt endast om klienten har behörighet att implementera det.

Implementera publika API-metoder

Läs mer i "Åsidosätta API-metoder".

Åtkomst till fält i API-klasser och -gränssnitt

Klienter kan läsa API-fält, av vilka de flesta är slutliga. Vissa struktliknande objekt kan ha publika fält som inte är slutliga och som klienter kan läsa och skriva om inte annat anges.

Typomvandla objekt av en känd API-typ

Ett objekt av en känd API-typ kan endast typomvandlas till en annan API-typ (eller villkorligt typomvandlas med hjälp av instanceof) om det explicit angetts som tillåtet i API.

Dessutom är det förstås aldrig lämpligt att typomvandla ett objekt till en klass eller ett gränssnitt som inte är en API-klass eller -gränssnitt.

Bryta mot reglerna

Oavsett om det görs medvetet eller inte får det alltid konsekvenser när reglerna inte tillämpas. Det skulle kanske vara enklare för alla inblandade om det fanns API-poliser som tog fast de som bröt mot reglerna. Några sådana finns dock inte. För det mesta fungerar iakttagande av API-reglerna som ett hederssystem där varje klient ansvarar för att känna till och tillämpa dem.

Kontrakt för API-elementen begränsar vilka funktioner som kan användas och bibehålls. Allt eftersom att Eclipse-plattformen arbetas fram och utvecklas kommer det att vara API-kontrakten som styr hur utvecklingen sker. Det finns inga funktioner för sådant som inte täcks av kontrakten och det kan när som helst ändras utan meddelande (till och med under det att versionen släpps eller mellan olika OS-plattformar). Klientkod som avviker från ovanstående regler kan misslyckas till exempel i följande fall: i olika versioner och uppdateringsnivåer för plattformen, när den körs i olika underliggande operativsystem, när den körs med en blandning av insticksprogram som används samtidigt eller när den körs med ett annat arbetsmiljöperspektiv. I själva verket är ingen särskilt intresserad av att spekulera i exakt vilka följder en viss överträdelse kan få. Om du väljer att ignorera reglerna kan du inte säga att du inte blev varnad. Och förvänta dig inte mycket mer än ett medkännande "Vad var det jag sa ...".

Å andra sidan bör insticksprogramkod där ovanstående regler tillämpas fungera i olika versioner och uppdateringsnivåer av plattformen och olika underliggande operativsystem och bör även gå att använda tillsammans med andra insticksprogram utan problem. Om alla följer reglerna är Eclipse-plattformen en stabil grund för utveckling av spännande nya produkter.