Eclipse-Plattform
Verwendungsregeln für API

Version 0.15 - Last revised 12:00 May 30, 2001

Hier finden Sie alle Verwendungsregeln zu den Clients der API der Eclipse-Plattform (und anderen Komponenten).

Bedeutung einer API

Die Eclipse-Plattform definiert API-Elemente, die durch ihre Clients verwendet werden, vor allem durch unabhängige Softwarehersteller, die Plug-ins schreiben. Diese Plug-ins können wiederum API-Elemente für ihre eigenen Clients definieren usw. API-Elemente kommunizieren auf gewisse Weise mit dem Benutzer: sie geben an, welche Aufgaben sie übernehmen und wie sie eingesetzt werden sollen. API-Elemente werden unterstützt: Das Eclipse-Plattformteam korrigiert Programmfehler einer Implementierung, wenn eine Abweichung vom angegebenen erhalten festgestellt wird. Da umfangreiche API-Änderungen häufig erhebliche Kosten nach sich ziehen, versucht das Eclipse-Plattformteam außerdem, API-Elemente über erfolgreiche Haupt-Releases problemlos weiterzuentwickeln.

Kommunikation zwischen API-Elementen und anderen Elementen

API-Elemente sind ihrem Charakter nach so angelegt, dass sie dokumentiert werden und über eine Spezifikation verfügen. Sie bilden hierdurch einen Gegensatz zu anderen, nicht für eine API gedachten Elementen, bei denen es sich um interne Implementierungsdetails handelt, für die in der Regel weder Dokumentation noch Spezifikationen publiziert werden. Wenn Sie also nicht in der Lage sind, die Dokumentation für ein bestimmtes Element aufzufinden, ist dies normalerweise ein Hinweis darauf, dass es sich nicht um eine API handelt.

Um die Trennung zwischen diesen beiden Elementtypen noch deutlicher zu ziehen, ist die Codebasis für die Plattform in API- und Nicht-API-Pakete unterteilt, und alle API-Elemente werden in designierten API-Pakete deklariert.

Alle anderen Elemente werden als interne Implementierungsdetails betrachtet und sind für keinen Client zugänglich. Ein ordnungsgemäßer Client-Code darf nie auf die Namen von Elementen verweisen, die keine API-Elemente sind, nicht einmal unter Verwendung einer Java-Spiegelung. In manchen Fällen werden unzulässige Verweise durch die Regeln für die Zugriffsmöglichkeit auf Namen verboten, die in der Java-Sprache definiert sind. In vielen Fällen ist dies jedoch schlichtweg nicht möglich. Zur völligen Umgehung dieses Problems ist es jedoch ausreichend, lediglich eine einzige einfache Regel zu beachten:

Allgemeine Regeln

Die Spezifikation von API-Elementen wird aus den Javadoc-Kommentaren im Java-Quellcode des Elements generiert. Bei einigen Elementtypen wird die Spezifikation in Form einer Vereinbarung bereitgestellt. Beispielsweise besteht bei Methoden die Vereinbarung zwischen zwei Partnern: dem Modul, das die Methode aufruft, und dem Modul, das die Methode implementiert. Hierbei gilt die folgende Grundregel: Wenn in einer API-Vereinbarung der Begriff "muss" ("must") verwendet wird, bedeutet dies, dass der Vereinbarungspartner selbst für die Einhaltung der beschriebenen Bedingung sorgen muss. Alle Fälle, in denen dies nicht sichergestellt wird, werden als Programmierfehler mit nicht genauer definierten (und möglicherweise unvorhersehbaren) Folgen betrachtet. Weitere allgemein gültige Regeln:

Öffentliche API-Methoden aufrufen

Bei den meisten Clients besteht der Hauptteil der Eclipse-API aus öffentlichen Methoden für API-Schnittstellen oder -Klassen, die der Client aufrufen kann, wenn dies erforderlich ist.

Plattform-API-Klassen als Exemplare erstellen

Nicht alle konkreten API-Klassen können durch jeden Benutzer als Exemplar erstellt werden. API-Klassen enthalten eine Vereinbarung über die Exemplarerstellung, die die Bedingungen angibt, unter denen Exemplare erstellt werden können. Die Vereinbarung kann außerdem andere Aspekte wie die Verantwortlichkeiten für die lokale Initialisierung (z. B. das Konfigurieren einer bestimmten Eigenschaft, bevor das Exemplar gänzlich aktiv ist) sowie Zuständigkeiten für den zugeordneten Lebenszyklus (z. B. das Aufrufen der Methode dispose() zum Freigeben von Betriebssystemressourcen, die durch das Exemplar belegt wurden) behandeln. Klassen, die von Clients als Exemplare erstellt werden können, sind im Javadoc-Kommentar zur Klasse explizit gekennzeichnet (mit Angaben wie "Clients may instantiate" = "Clients können Exemplare erstellen" o. ä.).

Plattform-API-Klassen als Unterklassen aufnehmen

Nur ein Teil der API-Klassen kann als Unterklasse aufgenommen werden. API-Klassen enthalten eine Vereinbarung über Unterklassen. Diese gibt die Bedingungen an, unter denen Unterklassen deklariert werden können. Diese Vereinbarung behandelt auch die Verantwortlichkeiten für Initialisierung und Lebenszyklus. Klassen, die von Clients als Unterklassen aufgenommen werden können, sind im Javadoc-Kommentar zur Klasse explizit gekennzeichnet (mit Angaben wie "Clients may subclass" = "Clients können Unterklassen aufnehmen" o. ä.).

Geschützte API-Methoden aufrufen

Das Aufrufen von übernommenen geschützten und öffentlichen Methoden aus einer Unterklasse heraus ist generell zulässig. Häufig ist es jedoch komplizierter, auf einen korrekten Aufruf zu achten, als öffentliche Methoden außerhalb der Hierarchie aufzurufen.

API-Methoden überschreiben

Nur ein Teil der öffentlichen und geschützten API-Methoden kann überschrieben werden. API-Klassen enthalten eine Vereinbarung über Unterklassen. Diese gibt die Bedingungen an, unter denen sie durch eine Unterklasse überschrieben werden kann. Standardmäßig ist es nicht zulässig, eine Klasse zu überschreiben. Die Vereinbarung über Unterklassen in der tatsächlichen Methodenimplementierung, die überschrieben werden soll, muss genau überprüft werden. Die Bedingungen der Vereinbarungen über Unterklassen werden nicht automatisch übergeben, wenn diese Methode überschrieben wird.

Plattform-API-Schnittstellen implementieren

Nur ein Teil der API-Schnittstellen kann durch Clients implementiert werden. API-Schnittstellen enthalten eine Vereinbarung mit den Bedingungen, unter denen sie implementiert werden können. Schnittstellen, die durch Clients implementiert werden können, sind im Javadoc-Kommentar zur Klasse explizit gekennzeichnet (mit Angaben wie etwa "Clients may implement" = "Implementierung durch Clients ist zulässig" o. ä.). Ein Client kann eine Unterschnittstelle einer API-Schnittstelle nur und ausschließlich dann deklarieren, wenn ihre Implementierung zulässig ist.

Öffentliche API-Methoden implementieren

Siehe "API-Methoden überschreiben".

Auf Felder in API-Klassen und -Schnittstellen zugreifen

Clients können API-Felder lesen, von denen die meisten final sind. Bestimmte strukturähnliche Objekte können nicht als "final" definierte öffentliche Felder enthalten, die Clients lesen und schreiben können, sofern nichts anderes angegeben ist.

Objekte eines bekannten API-Typs umsetzen

Ein Objekt mit einem bekannten API-Typ kann nur dann in einen anderen API-Typ umgesetzt (oder mit "instanceof" bedingt umgesetzt) werden, wenn dies in der API ausdrücklich zulässig ist. Außerdem und logischerweise ist das Umsetzen eines Objekts in ein eine Klasse oder Schnittstelle, die keine API-Klasse oder -Schnittstelle ist, immer ungeeignet.

Folgen bei Nichteinhaltung der Regeln

Regelübertretungen - seien sie nun vorsätzlich oder unbeabsichtigt - sind nie folgenlos. Es wäre wahrscheinlich einfacher für alle Beteiligten, wenn es eine Art "API-Polizei" gäbe, die solche Regelübertretungen entsprechend sanktioniert. Dies ist jedoch nicht der Fall. Die Berücksichtigung der API-Regeln erfolgt größtenteils auf Vertrauensbasis. Bei diesem System ist jeder Client dafür verantwortlich, die Regeln zu kennen und zu befolgen.

Die Vereinbarungen in den API-Elementen beschränken das unterstützte und ordnungsgemäße Verhalten. Da sich die Eclipse-Plattform weiterentwickelt und ausreift, können Sie anhand der API-Vereinbarungen verfolgen, wie sich diese Entwicklung vollzieht. Alles, was nicht in diesen Vereinbarungen angegeben ist, wird nicht unterstützt und kann jederzeit und ohne vorherige Ankündigung geändert werden (sogar mitten in einem Release oder zwischen unterschiedlichen Betriebssystemplattformen. Client-Code, der gegen die vorstehenden Regeln verstößt, kann auf unterschiedlichen Versionen und Programmkorrekturstufen der Plattform fehlschlagen, außerdem bei der Ausführung auf verschiedenen Betriebssystemen, bei einer Ausführung mit einem unterschiedlichen Mix aus ebenfalls residenten Plug-ins oder bei der Verwendung mit einer anderen Workbench-Perspektive usw. Natürlich ist es für niemanden besonders interessant, genau vorherzusagen, in welcher Form sich eine bestimmte Regelübertretung negativ auswirken kann. Diejenigen, die die Regeln ignorieren wollen, sollten später nur nicht behaupten, dass sie nicht gewarnt worden wären, oder mehr als ein mitfühlendes "Wir haben es ja vorhergesagt" erwarten.

Ein Client-Plug-in-Code, der die oben beschriebenen Regeln hingegen befolgt, sollte auch über unterschiedliche Versionen oder Programmkorrekturstufen der Plattform hinweg und auf verschiedenen zu Grunde liegenden Betriebssystemen weiterhin funktionieren und problemlos mit anderen Plug-ins koexistieren können. Wenn alle Beteiligten sich an die Regeln halten, bietet die Eclipse-Plattform eine stabile und unterstützte Basis, auf der interessante neue Produkte erstellt werden können.

Copyright IBM Corporation und Andere 2000, 2003.