Arbeiten mit der Dokumentation

Installieren Sie die Java Dokumentation wie im Hello World Tutorial beschrieben.

Zu den grossen Stärken von Java gehört die umfangreiche Klassenbibliothek, die einheitlich auf allen Betriebssystem zur Verfügung steht und dem Programmierer viel Routinearbeit abnehmen kann. Voraussetzung dafür ist aber, dass man die Bibliothek auch kennt. Das ist angesichts ihres Umfangs nicht so einfach. Deshalb sollte man früh anfangen, mit der Dokumentation zu arbeiten, um möglichst bald ein Gefühl für ihre Systematik zu entwickeln.

Navigieren in der Dokumentation

Öffnen Sie daher bitte jetzt Ihre Java Dokumentation und klicken Sie API & Language/ Java 2 Plattform API Specification an, so dass Sie dieses hiersehen:

Sie erkennen ein Frameset mit drei Frames. Oben links finden wir eine Auflistung aller Java Packages, darunter sind die Klassen aufgelistet, die zu dem jeweiligen Package gehören. Klicken Sie dort eine Klasse an, so erscheint ihre Dokumentation in dem großen Frame.

Alle Java Klassen sind in Packages organisiert. Die Packages erleichtern das Auffinden der Klassen und bilden einen thematischen Rahmen für die ihnen zugehörigen Klassen.Wählen Sie das Package java.awt aus, das Klassen für die Programmierung von grafischen Benutzerschnittstellen enthält („abstract window toolkit").

Im Frame links unten werden nun alle Interfaces, Klassen, Exceptions und Errors angezeigt, die zu diesem Package gehören. Excepitons und Errors sind nur der Übersichtlichkeit halber als eigene Punkte aufgeführt, könnten aber ebenso gut unter „Classes" stehen, das es ja ebenfalls Klassen sind. Aus den Namen der Klassen und Interfaces lässt sich oft auf ihre Funktion schließen (Button, Label).

Wählen Sie die schon bekannte Klasse Frame und öffnen Sie die Dokumentation dieser Klasse in das große Fenster. Was sagt uns diese Dokumentation? Wir wollen die Dokumentation der Klasse java.awt.Frame exemplarisch betrachten:

Informationen zur Klasse

Zunächst erkennen wir auf einen Blick die Objekthierarchie.

Java.awt.Frame ist von java.awt.Window abgeleitet, das wiederum von java.awt.Container, schließlich über java.awt.Component zu java.lang.Object. Java.lang.Object ist die „Mutter aller Objekte"; alle Java-Klassenleiten sich über kurz oder lang von java.lang.Object ab.

Abgeleitet sein ist aber nicht nur ein theoretisches Konstrukt, sondern hat praktische Konsequenzen. „Frame" erbt alle Methoden und Felder, die die „Elternklassen" zur Verfügung stellen.

Anschließend werden die Interfaces aufgeführt, die „Frame" implementiert.

Eine Klasse kann in Java nur von einer Klasse abgeleitet sein (keine Mehrfachvererbung), aber sie kann eine beliebige Anzahl Interfaces implementieren. Alle Methoden und Felder, die diese Interfaces deklarieren, sind in unserer Klasse ebenfalls zu finden.

Schließlich gibt es Verweise auf Klassen, die sich von „Frame" ableiten. In unserem Fall ist das nur eine, javax.swing.JFrame.

Es folgen Erklärungen, was „Frame" ist und wie die Klasse zubenutzen ist. Am Ende dieser Erklärung haben Sie meist den Hinweis, seit welcher Java Version die Klasse zur Verfügung steht.

Bitte beachten Sie, dass einzelne Methoden der Klasse durchaus neueren Datums sein können, auch wenn Frame von Anfang an dabei ist.

Members

Anschließend kommen die „Members" dieser Klasse. Members sind Objekte oder primitive Datentypen, die zu dieser Klasse gehören. Wenn die Klassen dieser Objekte innerhalb der Klasse „Frame" definiert ist, handelt es sich um „Innere Klassen", die zuerst aufgeführt werden:

Handelt es sich um Objekte, deren Klassen nicht innerhalb von „Frame", definiert sind, oder handelt es sich um primitive Datentypen wie Integer (int), Long(long) , Float (float) usw. spricht man von Feldern.

Hier sehen wir etwas von den Java – Erblasten, die Bezeichnung deprecated.

Felder, Methoden, Konstruktoren oder auch Klassen, die als deprecated gekennzeichnet sind, sollen nicht mehr benutzt werden. Sie sind fehlerhaft oder stellen häufig auch nur schlechten Stil dar. In diesem Fall ist eine Konstante aus der Klasse „Frame" in eine eigene Klasse, nämlich „java.awt.Cursor" gewandert. Die Klasse „Cursor" wurde inder Java – Version 1.1 eingeführt und man fand wohl, dass CROSSHAIR_CURSOR dort besser aufgehoben ist.

Konstruktoren

Um eine Objekt zu benutzen, müssen wir es zunächst erzeugen. In Java benutzt man dazu eine spezielle Methode einer Klasse, den sogenannten Konstruktor. Wie Sie sehen, bietet uns die Klasse „Frame" direkt eine ganze Reihe von Konstruktoren an:

Klicken Sie auf einen Konstruktor – Link; das Dokument scrollt nach unten und zeigt weitere Informationen zu dem Konstruktor:

Hier können Sie erfahren, was passiert, wenn ein Parameter „null" ist, oder ob der Konstruktor eine Exception werfen kann, wenn irgendetwas schief geht.

Methoden

Darunter finden Sie die Methoden der Klasse. Die Methoden unterscheiden sich vom Konstruktor dadurch, dass sie einen Rückgabetyp besitzen. Der Rückgabetyp ist stets angegeben. Zunächst kommen die Methoden dran, die in der Klasse selbst definiert sind. Auch hier gibt's wieder die Links zu den Details. Anschließend gibt es Links zu allen Methoden der Klassen, von denen „Frame" abgeleitet ist:

Dies ist eine wichtige Hilfe. Beachten Sie stets die Methoden der Elternklasse, denn dort werden Sie vielfach das Gesuchte finden. Ein Klick auf den Link führt zur Dokumentation der entsprechenden Elternklasse.

Tools: JavaDoc

Die Dokumentation wird aus dem Quellcode selbst erzeugt, d.h. aus den JavaDoc Kommentaren des Quellcodes. Dabei werden Kommentare, die zwischen den Zeichen /** [..] */ und direkt über Methoden, Klassen oder Interface-Definitionen stehen, berücksichtigt. Kommentare zwischen /* [..] */ (nur ein Asterix am Anfang) und einzeilige Kommentare mit „//" werden ignoriert. Sie finden deshalb häufig ausladende „JavaDoc- Kommentare über den Methoden, weil die Programmierer auf diese Weise die Dokumentation ihrer Klassen gleich mit erledigen können.

Eine solche HTML Dokumentation lässt sichganz einfach mit dem JDK- Tool JavaDoc erzeugen, dass sich in $JAVA_HOME/bin, also in dem Verzeichnis, in dem auch der Compiler ist, befindet. Wechseln Sie in Ihr Source- Verzeichnis und geben Sie an einer Konsole

javadoc basicjava.kap1 –d help

ein. JavaDoc erstellt dann eine Dokumentation des Packages basicjava.kap1, die imUnterverzeichnis „help" angelegt wird.

Einzelheiten zu javadoc gibt'sin der Java-Dokumentation unter: Tool Docs / Basic Tools / (javadoc) windows.