07.02 Die Java API-Dokumentation

Das wichtigste Werkzeug am Anfang Ihrer Programmierer-Karriere ist die Java API-Dokumentation (auch JavaDoc genannt). In Ihr finden Sie alle Klassen und Methoden, die Standard-Java für Sie bereit hält. Dieses Kapitel gibt Ihnen einen kurzen Überblick, was diese Dokumentation ist, wo Sie sie finden, und wie Sie mit Ihr umgehen.

Was ist die Java API-Dokumentation?

Dies ist leicht zu erklären, wenn wir uns die Begriffe getrennt voneinander ansehen. Java ist das Thema, um das es geht. API bedeutet ausgeschrieben application programming interface und zu deutsch Programmierschnittstelle. Die Java-API umfasst also alle verfügbaren Schnittstellen (Klassen, Interfaces, Enumerations, …), auf die Sie ohne weiteres in Ihrem Programm zugreifen können. Folglich stellt die Java API-Dokumentation eine Dokumentation dieser Schnittstellen dar.

Es handelt sich aber auch wirklich nur um eine Dokumentation, nicht um ein Tutorial wie die Klassen und Interfaces verwendet werden sollen. Für so etwas gibt es Bücher (wie z. B. das Java Blog Buch) und Online-Hilfen (wie z. B. das Java Blog Buch), oder die offiziellen Tutorials von Oracle, die immer einen Blick wert sind.

Wo finde ich die Java API-Dokumentation?

Sie finden sie auf der Seite von Oracle (java.oracle.com) unter dem Punkt Java APIs. Wie in Kapitel 01.02 Einsatzgebiete von Java erläutert, gibt es mehrere Einsatzorte für Java. Deshalb finden Sie dort auch mehrere Überpunkte zu den unterschiedlichen Entwicklungswerkzeugen – wie z. B. der Standard Edition (Dokumentation zum normalen JDK), der Enterprise Edition (Dokumentation für Entwickler von Webanwendungen) oder der Micro Edition (Dokumentation für Entwickler von mobilen Anwendungen). Da alle Dokumentationen identisch aufgebaut sind, fokussieren wir in diesem Kapitel lediglich die Standard Edition, mit der Sie bis jetzt ausschließlich in diesem Buch programmiert haben.

Unter den Überpunkten finden Sie noch weitere Unterpunkte. Jeder Unterpunkt steht für eine bestimmte Version des Überpunktes. So können Sie u. a. bei der Standard Edition zwischen den Dokumentationen zu den Versionen 7 und 6 wählen. Sie entscheiden sich natürlich immer für die Version, mit der Sie auch programmieren.

Wenn Sie nicht wissen, welche Version Sie einsetzen, können Sie durch den Konsolenaufruf javac -version Ihre Version auslesen – sofern die Umgebungsvariable PATH richtig gesetzt wurde (siehe Kapitel 01.03 Java installieren).

Hier finden Sie u. a. auch noch eine Übersicht der einzelnen Dokumentationen in unterschiedlichen Sprachen und JDK-Programmierrichtlinien (ebenfalls in unterschiedlichen Sprachen).

Eine gute API-Dokumentation auf Deutsch werden Sie leider nicht finden, aber als Programmierer ist es ohnehin wichtig Englisch zumindest verstehen zu können.

Wenn Sie unsere vorhergehenden Kapitel aufmerksam gelesen haben, finden Sie dort auch einige Verweise auf die JavaDoc.

Wie verwende ich die Java API-Dokumentation?

Die Startseite der Dokumentation ist in drei Bereiche unterteilt. Links oben finden Sie eine Übersicht aller Packages. Der restliche, linke Bereich ist alphabetisch mit allen Schnittstellen gefüllt. In der Mitte finden Sie das aktuell ausgewählte Element – zu Beginn ebenfalls eine Übersicht aller Packages mitsamt kurzer Beschreibung.

Wählen Sie im Package-Bereich ein bestimmtes Package aus, wird der Schnittstellen-Bereich an den Inhalt des Packages angepasst. Wählen Sie den Punkt All Classes aus, bekommen Sie wieder die ursprüngliche Ansicht.

Im Schnittstellen-Bereich können Sie eine Klasse oder ein Interface (Interfaces sind kursiv geschrieben) auswählen. Diese Schnittstelle wird anschließend in der Mitte angezeigt.

In der Mitte finden Sie (je nach ausgewählten Element) standardisierte Navigationshilfen.

• Sie können zur Startseite mit Overview zurückkehren
• Ein Klick auf Package öffnet das Package der ausgewählten Schnittstelle
• Class bringt Sie zur normalen Definition der Schnittstelle, welche wir uns später noch genauer ansehen werden
• Use gibt einen detaillierten Überblick über die Schnittstelle – z. B. wo sie überall verwendet wird
• Über den Punkt Tree erhalten Sie eine hierarchische Übersicht
• Deprecated gibt Ihnen einen Überblick, was alles beim Programmieren nicht mehr verwendet werden sollte
• Der Index ist eine alphabetische Anordnung von allem, was diese API-Dokumentation beinhaltet
• Unter Help finden Sie eine Hilfe zur Verwendung und Organisation der Dokumentation
• Über die Links FRAMES und NO FRAMES können Sie die Linke Seite (Package-, und Schnittstellen-Bereich) ein, oder ausblenden

Am Häufigsten werden Sie Wohl mit der Definition der Schnittstelle arbeiten (diese Ansicht wird auch standardmäßig geöffnet, wenn Sie eine Schnittstelle auswählen). Deshalb folgt jetzt ein kleiner Überblick, wie diese Seite aufgebaut ist.

Kopf der Schnittstellen-Definition

1. Nennung des Packages
2. Name der Schnittstelle
3. Vererbungshierarchie/bei Interfaces ggf. vorhandene Superinterfaces
4. Implementierende Interfaces/bei Interfaces ggf. vorhandene Subinterfaces
5. Bei Interfaces alle Klassen, die dieses Interface implementieren

Erklärung der Schnittstelle

1. Kopf der Schnittstelle
2. Erklärung was die Schnittstelle macht/für was Sie nötig ist
3. Ggf. weitere Informationen wie z. B. „Seit wann existiert diese Schnittstelle“ oder „Welche anderen Schnittstellen sind in diesem Zusammenhang auch interessant“

Attribute, Konstruktoren und Methoden

Im Bereich unter der Erklärung der Schnittstelle finden Sie eine Auflistung aller Methoden, Attribute und Konstruktoren, die diese Schnittstelle zur Verfügung stellt. Eine kleine Erklärung inbegriffen. Auch finden Sie alle Attribute und Methoden von ggf. vorhandenen Elternklassen. Unter dieser Zusammenfassung findet sich letztendlich noch eine erweiterte Beschreibung der Methoden, Konstruktoren und Attribute. Diese enthalten auch weitere Hinweise wie z. B. „welche Fehler können geworfen werden“, „was wird zurückgegeben“, „welche Parameter werden erwartet“, oder „was sollte in diesem Zusammenhang noch berücksichtigt werden“.

Das ist erstmal alles, was Sie über die Java API-Dokumentation wissen müssen. Auch hier gilt der selbe Grundsatz wie beim Programmieren: Setzen Sie die Dokumentation nie ein, lernen Sie auch nicht den (überaus wichtigen) Umgang mit ihr. Denn mit ziemlich hoher Wahrscheinlichkeit werden sich Programmieranfänger nur sehr schwer mit der Java API-Dokumentation anfreunden können. Hier gilt aber die Devise dranbleiben und weiter versuchen! Ohne diese Dokumentation fällt Ihnen das Programmieren sehr viel schwerer, da Sie sich unmöglich alle Klassendefinitionen merken können.

Eine Dokumentation für die eigenen Klassen und Interfaces erstellen

Wenn Sie eine eigene Dokumentation erstellen möchten, ist dies ohne Probleme möglich. Mehr hierzu erfahren Sie aber später bei der Verwendung des Programms javadoc.