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.
-
API-paket - ett Java-paket som innehåller minst en API-klass eller ett API-gränssnitt. Namnen på API-paket anges i dokumentationen för komponenten. Så långt det är möjligt ingår "internal" i namnet för alla andra paket som endast innehåller implementeringsinformation. Namnen på API-paket kan visas i klientkod. För själva Eclipse-plattformen är paketen de följande:
-
org.eclipse.foo.* - till exempel org.eclipse.swt.widgets,
org.eclipse.ui,
eller org.eclipse.core.runtime
-
org.eclipse.foo.internal.* - inte API, paket för intern implementering
-
org.eclipse.foo.examples.* - inte API, de är exempel
-
org.eclipse.foo.tests.* - inte API, de är testuppsättningar
-
API-klass eller -gränssnitt - en publik klass eller gränssnitt i ett
API-paket eller en publik eller skyddad klass- eller gränssnittsmedlem som deklareras i eller ärvs av någon annan API-klass eller gränssnitt.
Namnen på API-klasser och -gränssnitt kan visas i klientkod.
-
API-metod eller konstruktor - en publik eller skyddad
metod eller konstruktor som antingen deklareras i eller ärvs av en API-klass eller -gränssnitt. Namnen på API-metoder kan visas i klientkod.
-
API-fält - ett publikt eller skyddat
fält som antingen deklareras i eller ärvs av en API-klass eller -gränssnitt. Namnen på API-fält kan visas i klientkod.
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:
-
Använd endast officiellt dokumenterade API-element. Endast referenspaket som
dokumenterats i publicerat API Javadoc för komponenten.
Referera aldrig till paket som tillhör en annan komponent som har ett namn där "internal" ingår - de är aldrig API-paket. Referera aldrig till paket som det inte finns något
publicerat API Javadoc för - de är inte heller API-paket.
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:
-
Uppfyll alla kontrakt. Kontrakten beskrivs i det publicerade
Javadoc-dokumentet för de API-element du använder.
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.
-
Du måste uppfylla "must" (måste). Var särskilt noggrann med att uppfylla villkor där "must" används.
Andra förnuftiga regler:
-
Förlita dig inte på tillfälliga funktioner. Tillfälliga funktioner är funktioner som används i experimentsyfte eller som övning men som inte garanteras av någon API-specifikation.
-
Använd inte null som objekt. Null är mer avsaknad av ett objekt.
Anta att allt är icke-null om inte något annat anges i API-specifikationen.
-
Försök inte fuska med Java-återspegling. Du tjänar inget på att använda Java-återspegling till att kringgå
Java-kompileringskontroll. Det finns inga extra
API-kontrakt för användning av återspegling. Återspegling ökar bara sannolikheten att du förlitar dig på ej angivna funktioner och intern implementeringsinformation.
-
Använd egna paket. Deklarera inte kod i ett paket som tillhör en annan komponent. Använda alltid egen kod i egna paket.
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.
-
Kontrollera förvillkor. Kontrollera att förvillkoren för en API-metod är uppfyllda innan du anropar metoden. Å andra sidan kan den som anropar metoden förlita sig på att
eftervillkoren för metoden har uppfyllts omedelbart efter att anropet gjorts.
-
Null-parametrar. Överför inte null som en parameter till en API-metod
om det inte finns explicit dokumentation om att null tillåts för parametern. Det här kan vara det oftast förekommande programmeringsfelet.
-
Begränsade anropare. Anropa inte en API-metod som dokumenterats som tillgänglig endast för vissa anropare om du inte är en av dem. I vissa
situationer måste vissa anropare (vanligen interna) ha tillgång till metoder som en del av det publika APIt. Om du anropar en sådan metod vid fel tidpunkt får
det ej angivna (och kanske oförutsägbara) konsekvenser.
-
Felsökningsmetoder. Anropa inte en API-metod med en etikett om att den endast ska användas i felsökningssyfte. Till exempel tillhör de flesta toString()-metoder den kategorin.
-
Parameterfångst. Överför inte en matris, en samling eller något annat redigerbart objekt som en parameter till en API-metod för att sedan ändra det överförda objektet. Det är att tigga om problem.
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.").
-
Begränsade instantierare. Instantiera inte en API-klass som dokumenterats som tillgänglig endast för vissa parter om du inte är en av dem.
I vissa
situationer måste vissa parter (vanligen interna) ha tillgång till klasser som en del av det publika APIt. Om du instantierar en sådan klass på fel sätt får
det ej angivna (och kanske oförutsägbara) konsekvenser.
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.").
-
Begränsade behörighet att underordna. Underordna inte en API-klass som inte är ämnad att underordnas. Behandla de här klasserna som om de deklarerats som slutgiltiga. (De kan kallas "soft final" (preliminärt slutgiltiga).
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.
-
Åsidosätt inte en publik eller skyddad API-metod om det inte explicit angetts att det är tillåtet. Om inte annat anges behandlar du alla metoder som om de deklarerats som slutgiltiga. (De kan kallas "soft final" (preliminärt slutgiltiga).
Typ av åsidosättande som tillåts:
- "implementera" - den abstrakta metod som deklarerats för den underordnade klassen måste
implementeras av en konkret underordnad klass
- "utöka" - den metod som deklarerats för den underordnade klassen måste anropa
metoden för den överordnade klassen (precis en gång)
- "implementera igen" - den metod som deklarerats för den underordnade klassen får inte anropa
metoden för den överordnade klassen
- "åsidosätt" - den metod som deklarerats för den underordnade klassen kan anropa
metoden för den överordnade klassen enligt behov
-
Kontrollera eftervillkor. Kontrollera att eventuella eftervillkor som angetts för API-metoden uppfylls av implementeringen när den returneras.
-
Kontrollera förvillkor på ett aktivt sätt Förutsätt inte att de förvillkor som angetts för API-metoden har uppfyllts. Även om det inte innebär något fel om
det inte görs någon kontroll av förvillkor vid metodimplementeringen är det vanligen en god idé att kontrollera förvillkor (när det är möjligt och kan göras till en rimlig kostnad) för att förvarna om anropare som inte sköter sig som de ska.
-
Null-resultat. Returnera inte null som ett resultat från en API-metod om det inte
finns explicit dokumentation (för det aktuella gränssnittet eller den överordnade klassen) om att resultatet får vara null.
-
Returnera kopior. Returnera inte en oersättlig matris eller samling eller något annat redigerbart objekt som ett resultat av en API-metod. Returnera alltid en kopia för att undvika problem med anropare som kan ändra objektet.
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.
-
Begränsade implementerare. Implementera inte ett API-gränssnitt som dokumenterats som tillgängligt endast för vissa parter om du inte är en av dem. I många situationer används gränssnitt till att dölja intern implementeringsinformation.
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.
-
Null-fält. Ange inte värdet null för ett API-fält om det inte explicit angetts att det är tillåtet.
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.
-
Typomvandling och instanceof. Använd inte instanceof eller typomvandlingsuttryck till att utöka vad som är känt om objektet utöver vad API:t har funktioner för.
Felaktig användning exponerar tillfällig implementeringsinformation som det inte finns garantier för i API:t.
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.