Galileo Computing < openbook > Galileo Computing - Professionelle Bücher. Auch für Einsteiger.
Professionelle Bücher. Auch für Einsteiger

 << zurück
Java ist auch eine Insel von Christian Ullenboom
Programmieren für die Java 2-Plattform in der Version 5
Java ist auch eine Insel

Java ist auch eine Insel
5., akt. und erw. Auflage
1454 S., mit CD, 49,90 Euro
Galileo Computing
ISBN 3-89842-747-1
gp Kapitel 6 Eigene Klassen schreiben
  gp 6.1 Eigene Klassen definieren
    gp 6.1.1 Methodenaufrufe und Nebeneffekte
    gp 6.1.2 Argumentübergabe mit Referenzen
    gp 6.1.3 Die this-Referenz
    gp 6.1.4 Überdeckte Objektvariablen nutzen
  gp 6.2 Assoziationen zwischen Objekten
    gp 6.2.1 Gegenseitige Abhängigkeiten von Klassen
  gp 6.3 Privatsphäre und Sichtbarkeit
    gp 6.3.1 Wieso nicht freie Methoden und Variablen für alle?
    gp 6.3.2 Privat ist nicht ganz privat: Es kommt darauf an, wer’s sieht
    gp 6.3.3 Zugriffsmethoden für Attribute definieren
  gp 6.4 Statische Methoden und statische Attribute
    gp 6.4.1 Warum statische Eigenschaften sinnvoll sind
    gp 6.4.2 Statische Eigenschaften mit static
    gp 6.4.3 Statische Eigenschaften über Referenzen nutzen?
    gp 6.4.4 Warum die Groß- und Kleinschreibung wichtig ist
    gp 6.4.5 Statische Eigenschaften und Objekteigenschaften
    gp 6.4.6 Statische Variablen zum Datenaustausch
    gp 6.4.7 Statische Blöcke als Klasseninitialisierer
  gp 6.5 Konstanten und Aufzählungen
    gp 6.5.1 Konstanten über öffentliche statische final-Variablen
    gp 6.5.2 Problem mit finalen Klassenvariablen
    gp 6.5.3 Typsicherere Konstanten
    gp 6.5.4 Aufzählungen mit enum in Java 5
    gp 6.5.5 enum-Konstanten in switch
  gp 6.6 Objekte anlegen und zerstören
    gp 6.6.1 Konstruktoren schreiben
    gp 6.6.2 Einen anderen Konstruktor der gleichen Klasse aufrufen
    gp 6.6.3 Initialisierung der Objekt- und Klassenvariablen
    gp 6.6.4 Finale Werte im Konstruktor und in statischen Blöcken setzen
    gp 6.6.5 Exemplarinitialisierer (Instanzinitialisierer)
    gp 6.6.6 Zerstörung eines Objekts durch den Müllaufsammler
    gp 6.6.7 Implizit erzeugte String-Objekte
    gp 6.6.8 Private Konstruktoren, Utility-Klassen, Singleton und Fabriken
  gp 6.7 Vererbung
    gp 6.7.1 Vererbung in Java
    gp 6.7.2 Einfach- und Mehrfachvererbung
    gp 6.7.3 Gebäude modelliert
    gp 6.7.4 Konstruktoren in der Vererbung
    gp 6.7.5 Sichtbarkeit protected
    gp 6.7.6 Das Substitutionsprinzip
    gp 6.7.7 Automatische und explizite Typanpassung
    gp 6.7.8 Typen testen mit dem binären Operator instanceof
    gp 6.7.9 Array-Typen und Kovarianz
    gp 6.7.10 Methoden überschreiben
    gp 6.7.11 Mit super eine Methode der Oberklasse aufrufen
    gp 6.7.12 Kovariante Rückgabetypen
    gp 6.7.13 Finale Klassen
    gp 6.7.14 Nicht überschreibbare Funktionen
    gp 6.7.15 Zusammenfassung zur Sichtbarkeit
    gp 6.7.16 Sichtbarkeit in der UML
    gp 6.7.17 Zusammenfassung: Konstruktoren und Methoden
  gp 6.8 Object ist die Mutter aller Oberklassen
    gp 6.8.1 Klassenobjekte
    gp 6.8.2 Objektidentifikation mit toString()
    gp 6.8.3 Objektgleichheit mit equals() und Identität
    gp 6.8.4 Klonen eines Objekts mit clone()
    gp 6.8.5 Hashcodes
    gp 6.8.6 Aufräumen mit finalize()
    gp 6.8.7 Synchronisation
  gp 6.9 Die Oberklasse gibt Funktionalität vor
    gp 6.9.1 Dynamisches Binden als Beispiel für Polymorphie
    gp 6.9.2 Keine Polymorphie bei privaten, statischen und finalen Methoden
    gp 6.9.3 Polymorphie bei Konstruktoraufrufen
  gp 6.10 Abstrakte Klassen und abstrakte Methoden
    gp 6.10.1 Abstrakte Klassen
    gp 6.10.2 Abstrakte Methoden
  gp 6.11 Schnittstellen
    gp 6.11.1 Ein Polymorphie-Beispiel mit Schnittstellen
    gp 6.11.2 Die Mehrfachvererbung bei Schnittstellen
    gp 6.11.3 Erweitern von Interfaces – Subinterfaces
    gp 6.11.4 Vererbte Konstanten bei Schnittstellen
    gp 6.11.5 Vordefinierte Methoden einer Schnittstelle
    gp 6.11.6 Abstrakte Klassen und Schnittstellen im Vergleich
    gp 6.11.7 CharSequence als Beispiel einer Schnittstelle
    gp 6.11.8 Die Schnittstelle Iterable
  gp 6.12 Innere Klassen
    gp 6.12.1 Statische innere Klassen und Schnittstellen
    gp 6.12.2 Mitglieds- oder Elementklassen
    gp 6.12.3 Lokale Klassen
    gp 6.12.4 Anonyme innere Klassen
    gp 6.12.5 this und Vererbung
    gp 6.12.6 Implementierung einer verketteten Liste
    gp 6.12.7 Funktionszeiger
  gp 6.13 Generische Datentypen
    gp 6.13.1 Einfache Klassenschablonen
    gp 6.13.2 Einfache Methodenschablonen
    gp 6.13.3 Umsetzen der Generics, Typlöschung und Raw-Types
    gp 6.13.4 Einschränken der Typen
    gp 6.13.5 Generics und Vererbung, Invarianz
    gp 6.13.6 Wildcards
  gp 6.14 Die Spezial-Oberklasse Enum
    gp 6.14.1 Methoden auf Enum-Objekten
    gp 6.14.2 enum mit eigenen Konstruktoren und Methoden
  gp 6.15 Dokumentationskommentare mit javaDoc
    gp 6.15.1 Einen Dokumentationskommentar setzen
    gp 6.15.2 Mit javadoc eine Dokumentation erstellen
    gp 6.15.3 HTML-Tags in Dokumentationskommentaren
    gp 6.15.4 Generierte Dateien
    gp 6.15.5 Weitere Dokumentationskommentare
    gp 6.15.6 javaDoc und Doclets
    gp 6.15.7 Veraltete (deprecated) Klassen, Konstruktoren und Methoden


Galileo Computing

6.15 Dokumentationskommentare mit javaDoc  downtop

Die Dokumentation von Softwaresystemen ist ein wichtiger, aber oft vernachlässigter Teil der Softwareentwicklung. Im Entwicklungsprozess müssen die Entwickler Zeit in Beschreibungen der einzelnen Komponenten investieren, besonders dann, wenn weitere Entwickler diese Komponenten in einer öffentlichen Bibliothek anderen Entwicklern zur Verfügung stellen und wieder verwenden. Um die Klassen und Funktionen gut finden und nutzen zu können, müssen die Schnittstellen sorgfältig beschrieben werden. Wichtig bei der Beschreibung sind der Klassenname, der Methodenname, die Art und die Anzahl der Parameter, die Wirkung der Funktionen und das Laufzeitverhalten. Da das Erstellen einer externen Dokumentation – also einer Beschreibung außerhalb der Quellcodedatei – fehlerträchtig und deshalb nicht gerade motivierend für die Beschreibung ist, werden spezielle Dokumentationskommentare in den Java-Quelltext eingeführt. Ein spezielles Programm generiert aus den Kommentaren Beschreibungsdateien wie HTML mit den gewünschten Informationen.


Galileo Computing

6.15.1 Einen Dokumentationskommentar setzen  downtop

In einer besonders ausgezeichneten Kommentarumgebung werden die DokumentationskommentareDoc Comments«) eingesetzt. Die Kommentarumgebung erweitert ein Blockkommentar und ist vor allen Typen (Klassen, Schnittstellen, Aufzählungen) sowie Methoden und Variablen üblich.

Im folgenden Beispiel gibt Java-Doc Kommentare für die Klasse, Attribute und Methoden an.

Listing 6.85   com/javatutor/insel/javadoc/Disko.java

package com.javatutor.insel.javadoc;
/**
 * Modelliert eine Disko.
 */
public class Disko
{
  /** Anzahl Personen in der Disko */
  int anzahlPersonen;
  /**
   * Person betritt in die Disko.
   * Erhöht den internen Zähler für die Anzahl Besucher.
   */
  void personRein() {
    anzahlPersonen++;
  }
  /**
   * Person verlässt die Disko.
   * Vermindert den internen Zähler für die Anzahl Besucher.
   */
  void personRaus() {
    if ( anzahlPersonen > 0 )
      anzahlPersonen--;
  }
  /**
   * Liefert die Anzahl Personen in der Disko.
   *
   * @return Anzahl Personen.
   */
  int anzahlPersonen() {
    return anzahlPersonen;
  }
}

Hinweis   Die Dokumentationskommentare sind so aufgebaut, dass der erste Satz in der Auflistung der Methoden und Attribute erscheint und der Rest in der Detailansicht.
/**
 *   Das ist ein kurzer Satz.
 *   Das ist die ausführliche Beschreibung.
 *   Die ausführliche Beschreibung erscheint
 *   später im Abschnitt "Method Detail".
 *   Der kurze Satz erscheint im Abschnitt "Method Summary".
 */
public void foo() { }

Da ein Dokumentationskommentar /** mit /* beginnt, ist es für den Compiler ein normaler Blockkommentar. Die javaDoc-Kommentare werden oft optisch aufgewertet, indem am Anfang ein Sternchen steht. Dieses wird von javaDoc ignoriert.


Galileo Computing

6.15.2 Mit javadoc eine Dokumentation erstellen  downtop

Aus dem mit Kommentaren versehenen Quellcode generiert ein externes Programm die Zieldokumente. Sun liefert beim SDK das Konsolen-Programm javadoc mit, dem als Parameter ein Dateiname der zu kommentierenden Klasse übergeben wird; aus compilierten Dateien können natürlich keine Beschreibungsdateien erstellt werden. Wir starten javadoc im Verzeichnis, in dem auch die Klassen liegen, und erhalten unsere HTML-Dokumente.


Beispiel   Möchten wir Dokumentationen für das gesamte Verzeichnis erstellen, so geben wir alle Dateien mit der Endung .java an:
$   javadoc *.java  

javaDoc geht durch den Quelltext, parst die Deklarationen und zieht die Dokumentation heraus. Daraus generiert das Tool eine Beschreibung, die in der Regel als HTML-Seite zu uns kommt.

Eclipse

In Eclipse lässt sich eine Dokumentation mit javaDoc sehr einfach erstellen. Im Menü File, Export ist der Eintrag Javadoc zu wählen und nach ein paar Einstellungen ist die Dokumentation generiert.


Galileo Computing

6.15.3 HTML-Tags in Dokumentationskommentaren  downtop

In den Kommentaren können HTML-Tags verwendet werden, beispielsweise <b>bold</b> und <i>italic</i>, um Textattribute zu setzen. Sie werden direkt in die Dokumentation übernommen und müssen korrekt geschachtelt sein, damit die Ausgabe nicht falsch dargestellt wird. Die Überschriften-Tags <h1>..</h1> und <h2>..</h2> sollten jedoch nicht verwendet werden. javaDoc verwendet sie zur Gliederung der Ausgabe und weist ihnen Formatvorlagen zu.

Eclipse

In Eclipse zeigt die View javadoc in einer Vorschau das Ergebnis des Dokumentationskommentars an.


Galileo Computing

6.15.4 Generierte Dateien  downtop

Für jede öffentliche Klasse erstellt javaDoc eine HTML-Datei. Sind Klassen nicht öffentlich, muss ein Schalter angegeben werden. Die HTML-Dateien werden zusätzlich mit Querverweisen zu den anderen dokumentierten Klassen versehen. Daneben erstellt javaDoc weitere Dateien:

gp  index-all.html Die Übersicht aller Klassen, Schnittstellen, Ausnahmen, Methoden und Felder in einem Index
gp  overview-tree.html Zeigt in einer Baumstruktur die Klassen an, damit die Vererbung deutlich sichtbar ist.
gp  allclasses-frame.html Anzeige aller dokumentierten Klassen in allen Unterpaketen
gp  deprecated-list.html Liste der veralteten Methoden und Klassen
gp  serialized-form.html Listet alle Klassen auf, die Serializable implementieren. Jedes Attribut erscheint mit einer Beschreibung in einem Absatz.
gp  help-doc.html Eine Kurzbeschreibung von javaDoc
gp  index.html javaDoc erzeugt eine Ansicht mit Frames. Das ist die Hauptdatei, die die rechte und linke Seite referenziert. Die linke Seite ist die Datei allclasses-frame.html. Rechts im Frame wird bei fehlender Paketbeschreibung die erste Klasse angezeigt.
gp  stylesheet.css Formatvorlage für HTML-Dateien, in der sich Farben und Zeichensätze einstellen lassen, die dann alle HTML-Dateien nutzen.
gp  packages.html Eine veraltete Datei. Sie verweist auf die neuen Dateien.

Galileo Computing

6.15.5 Weitere Dokumentationskommentare  downtop


Tabelle 6.3   Die wichtigsten Dokumentationskommentare im Überblick

Kommentar Beschreibung
@see Klassenname Verweis auf eine andere Klasse
@see Klassenname oder Methodenname Verweis auf eine andere Methode
@see Ausgeschriebener Klassenname Verweis auf eine voll qualifizierte Klasse
@see Ausgeschriebener Klassenname oder Methodenname Verweis auf eine voll qualifizierte Methode
@version Versionstext Version
@author Autor Schöpfer
@return Rückgabetext Rückgabewert
@param Parametername oder Parametertext Beschreibung der Parameter
@exception Exception-Klassenname oder Exceptiontext Ausnahmen, die ausgelöst werden können
@throws Exception-Klassenname oder Exceptiontext Synonym zu oben
{@link Verweis } Einen eingebauten Verweis im Text. Parameter sind wie bei @see.

Beispiele


Beispiele: Eine externe Zusatzquelle angeben:
@see <a href="spec.html#section">Java Spec</a>.
Verweis auf eine Funktion, die mit der beschriebenen Funktion verwandt ist:
@see String#equals(Object) equals
Dokumentiere eine Variable. Gib einen Verweis auf eine Methode an:
/**
 * The X-coordinate of the component.
 *
* @see #getLocation()
 */
 int x = 1263732;
Eine veraltete Methode, die auf eine Alternative zeigt:
/**
 * @deprecated  As of JDK 1.1,
 * replaced by {@link #setBounds(int,int,int,int)}
 */


Galileo Computing

6.15.6 javaDoc und Doclets  downtop

Die Ausgabe von javaDoc kann den eigenen Bedürfnissen angepasst werden, indem Doclets eingesetzt werden. Ein Doclet ist ein Java-Programm, das auf der Doclet-API aufbaut und die Ausgabedatei schreibt. Das Programm liest dabei wie das bekannte javaDoc-Tool die Quelldateien ein und erzeugt daraus ein beliebiges Ausgabeformat. Dieses Format kann selbst gewählt und implementiert werden. Wer also neben dem von JavaSoft beigefügten Standard-Doclet für HTML-Dateien, Framemaker-Dateien (MIF) oder RTF-Dateien erzeugen möchte, muss ein eigenes Doclet programmieren oder kann auf Doclets unterschiedlicher Hersteller zurückgreifen. Die Webseite http://www.doclet.com/ listet zum Beispiel Doclets auf, die Docbook generieren oder UML-Diagramme mit aufnehmen.

Daneben dient ein Doclet aber nicht nur der Schnittstellendokumentation. Ein Doclet kann auch aufzeigen, ob es zu jeder Methode eine Dokumentation gibt oder ob jeder Parameter und jeder Rückgabewert korrekt beschrieben ist. Auch zur Generierung zusätzlicher Programmdateien und XML-Deskriptoren können Doclets verwendet werden. XDoclet (http://xdoclet.sourceforge.net/) ist ein populäres Beispiel, wie aus annotiertem Quellcode Mappings-Dateien für relationale Datenbanken generiert oder für Enterprise Java Beans Dateien abgeleitet werden.


Galileo Computing

6.15.7 Veraltete (deprecated) Klassen, Konstruktoren und Methoden  toptop

Während der Phase eines Programms ändert sich die Sicht auf die Methoden, und das laufende Angebot eines Objekts oder einer Klasse muss unter Umständen eingeschränkt und verändert werden. Gründe gibt es viele:

gp  Methoden können nicht wirklich plattformunabhängig programmiert werden, wurden aber einmal angeboten. Nun soll die Methode nicht mehr unterstützt werden. (Ein Beispiel ist die Methode stop() eines Threads.)
gp  Die Java-Namenskonvention soll eingeführt und ältere Methodennamen sollen nicht mehr verwendet werden. Das betrifft in erster Linie spezielle setXXX()/getXXX()-Methoden, die seit Version 1.1 eingeführt wurden. So finden wir beim AWT viele Beispiele dafür. Nun heißt es zum Beispiel statt size() bei einer grafischen Komponente getSize().
gp  Entwickler haben sich beim Methodennamen verschrieben. So hieß es in FontMetrics vorher getMaxDecent() und nun getMaxDescent(), und im HTMLEditorKit wird insertAtBoundry() zu insertAtBoundary().

Hinweis   Veraltetes hat sich im Laufe der Zeit angesammelt; in Java 5 sind über 300 Methoden/Konstruktoren, etwas mehr als 50 Variablen/Konstanten, 21 Klassen (zuzüg-lich 4 Execptions) und 16 Schnittstellen.

Es ist ungünstig, die Methoden jetzt einfach zu löschen, denn dann kommt es zu Compilerfehlern. Eine Lösung wäre daher, die Methode beziehungsweise den Konstruktor deprecated zu deklarieren. Deprecated ist ein eigener Dokumentationskommentar; das sieht dann etwa so aus (Ausschnitt aus der Klasse java.util.Date):

/**
 * Sets the day of the month of this <tt>Date</tt> object to the
 * specified value. ….
 *
 * @param   date   the day of the month value between 1–31.
 * @see     java.util.Calendar
 * _saito_fett_  @deprecated As of JDK version 1.1,
 * replaced by <code>Calendar.set(Calendar.DAY_OF_MONTH, int date)</code>.
 _saito_fettout_  */
public void setDate(int date) {
  setField(Calendar.DATEdate);
}

Die Kennung @deprecated gibt an, dass die Methode/der Konstruktor nicht mehr verwendet werden soll. Ein guter Kommentar gibt auch Alternativen an, sofern vorhanden. Die Alternative, die hier genannt wird, ist die Methode set() aus dem Calendar-Objekt. Da das Kommentar in die generierte API-Dokumentation übernommen wird, erkennt der Entwickler, dass eine Methode veraltet ist.


Hinweis   Wenn die Kennung einer Methode »veraltet« anlastet, heißt das noch nicht, dass es sie nicht mehr geben muss. Es ist nur ein Hinweis, dass die Methoden nicht mehr verwendet werden sollten und Unterstützung nicht mehr gegeben ist.


Beispiel   Der Compiler gibt bei veralteten Methoden eine kleine Meldung auf dem Bildschirm aus. Testen wir das an der Klasse AlterSack.

Listing 6.86   AlterSack.java

public class AlterSack
{
  java.util.Date d = new java.util.Date( 62, 3, 4 );
}

Jetzt rufen wir ganz normal den Compiler auf.
$   javac AlterSack.java
  Note: AlterSack.java uses or overrides a deprecated API.
Note: Recompile with -deprecation for details.

Der Compiler sagt uns schon, was wir machen können: Der Schalter -deprecation zeigt uns mehr. Was wird das wohl sein?

$   javac -deprecation AlterSack.java
  AlterSack.java:5: warning: Date(int,int,int) in java.util.Date has been deprecated
  Date d = new Date( 6234 );
           ^
1 warning

Die Ausgabe gibt genau die Zeile mit der veralteten Anweisung an. Alternativen nennt er nicht. Allerdings ist schon interessant, dass der Compiler in die Dokumentationskommentare sieht. Er gibt jedoch keine Alternativen an. Eigentlich hat er mit den auskommentierten Blöcken nichts zu tun und überliest jeden Kommentar. Für die speziellen Kommentare gibt es das Extra-Tool Javadoc, das wiederum mit dem Java-Compiler nichts zu tun hat.


Hinweis   Auch Klassen lassen sich als deprecated kennzeichnen (siehe etwa java.io.LineNumberInputStream). Dies finden wir jedoch selten, und es sollte vermieden werden.

Die Annotation @Deprecated

Seit Java 5 gibt es Annotationen, die zusätzliche Modifizierer sind. Eine Annotation @Deprecated (groß geschrieben) ist vordefiniert und ermöglicht es ebenfalls, Dinge als veraltet zu kennzeichnen. Dazu wird die Annotation wie ein üblicher Modifizierer etwa für Methoden vor den Rückgabetyp gestellt. Sun hat die oben genannte Funktion setDate() mit dieser Annotation gekennzeichnet, wie es der folgende Ausschnitt zeigt:

/** ...
 * @deprecated As of JDK version 1.1,
 * replaced by <code>Calendar.set(Calendar.DAY_OF_MONTH, int date)</code>.
 */
@Deprecated
public void setDate(int date) { ... }



1  Die Idee ist nicht neu. In den Achtzigerjahren verwendete Donald E. Knuth das WEB-System zur Dokumentation von TeX. Das Programm wurde mit den Hilfsprogrammen weave und tangle in ein Pascal-Programm und eine TeX-Datei umgewandelt.

 << zurück




Copyright © Galileo Press GmbH 2005
Für Ihren privaten Gebrauch dürfen Sie die Online-Version natürlich ausdrucken. Ansonsten unterliegt das <openbook> denselben Bestimmungen, wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


[Galileo Computing]

Galileo Press GmbH, Rheinwerkallee 4, 53227 Bonn, Tel.: 0228.42150.0, Fax 0228.42150.77, info@galileo-press.de