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

 
Inhaltsverzeichnis
Vorwort
1 Java ist auch eine Sprache
2 Imperative Sprachkonzepte
3 Klassen und Objekte
4 Der Umgang mit Zeichenketten
5 Eigene Klassen schreiben
6 Objektorientierte Beziehungsfragen
7 Ausnahmen müssen sein
8 Äußere.innere Klassen
9 Besondere Typen der Java SE
10 Generics<T>
11 Lambda-Ausdrücke und funktionale Programmierung
12 Architektur, Design und angewandte Objektorientierung
13 Komponenten, JavaBeans und Module
14 Die Klassenbibliothek
15 Einführung in die nebenläufige Programmierung
16 Einführung in Datenstrukturen und Algorithmen
17 Einführung in grafische Oberflächen
18 Einführung in Dateien und Datenströme
19 Einführung ins Datenbankmanagement mit JDBC
20 Einführung in <XML>
21 Testen mit JUnit
22 Bits und Bytes und Mathematisches
23 Die Werkzeuge des JDK
A Java SE-Paketübersicht
Stichwortverzeichnis


Download:

- Beispielprogramme, ca. 35,4 MB


Buch bestellen
Ihre Meinung?



Spacer
<< zurück
Java ist auch eine Insel von Christian Ullenboom

Einführung, Ausbildung, Praxis
Buch: Java ist auch eine Insel


Java ist auch eine Insel

Pfeil 23 Die Werkzeuge des JDK
Pfeil 23.1 Java-Quellen übersetzen
Pfeil 23.1.1 Java-Compiler vom JDK
Pfeil 23.1.2 Alternative Compiler
Pfeil 23.1.3 Native Compiler
Pfeil 23.1.4 Java-Programme in ein natives ausführbares Programm einpacken
Pfeil 23.2 Die Java-Laufzeitumgebung
Pfeil 23.2.1 Schalter der JVM
Pfeil 23.2.2 Der Unterschied zwischen java.exe und javaw.exe
Pfeil 23.3 Mit RoboVM geht’s für Java in das iOS-Land *
Pfeil 23.4 Dokumentationskommentare mit Javadoc
Pfeil 23.4.1 Einen Dokumentationskommentar setzen
Pfeil 23.4.2 Mit dem Werkzeug javadoc eine Dokumentation erstellen
Pfeil 23.4.3 HTML-Tags in Dokumentationskommentaren *
Pfeil 23.4.4 Generierte Dateien
Pfeil 23.4.5 Dokumentationskommentare im Überblick *
Pfeil 23.4.6 Javadoc und Doclets *
Pfeil 23.4.7 Veraltete (deprecated) Typen und Eigenschaften
Pfeil 23.4.8 Javadoc-Überprüfung mit DocLint
Pfeil 23.5 Das Archivformat JAR
Pfeil 23.5.1 Das Dienstprogramm jar benutzen
Pfeil 23.5.2 Das Manifest
Pfeil 23.5.3 Applikationen in JAR-Archiven starten
Pfeil 23.5.4 Pack200-Format *
Pfeil 23.6 Zum Weiterlesen
 

Zum Seitenanfang

23.4Dokumentationskommentare mit Javadoc Zur vorigen ÜberschriftZur nächsten Überschrift

Die Dokumentation von Softwaresystemen ist ein wichtiger, aber oft vernachlässigter Teil der Softwareentwicklung. Leider, denn Software wird im Allgemeinen öfter gelesen als geschrieben. Während des Entwicklungsprozesses 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 Wiederverwendung zur Verfügung stellen. Um die Klassen, Schnittstellen, Aufzählungen und Methoden sowie Attribute gut zu verstehen, müssen sie sorgfältig beschrieben werden. Wichtig bei der Beschreibung sind der Typname, der Methodenname, die Art und die Anzahl der Parameter, die Wirkung der Methoden 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 (im Allgemeinen HTML) mit den gewünschten Informationen.[ 275 ](Die Idee ist nicht neu. In den 1980er Jahren 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. )

 

Zum Seitenanfang

23.4.1Einen Dokumentationskommentar setzen Zur vorigen ÜberschriftZur nächsten Überschrift

In einer besonders ausgezeichneten Kommentarumgebung werden die Dokumentationskommentare (Doc Comments) eingesetzt. Die Kommentarumgebung erweitert einen Blockkommentar und ist vor allen Typen (Klassen, Schnittstellen, Aufzählungen) sowie Methoden und Variablen üblich. Im folgenden Beispiel gibt Javadoc Kommentare für die Klasse, für Attribute und Methoden an:

Listing 23.1com/tutego/insel/javadoc/Room.java

package com.tutego.insel.javadoc;



/**

* This class models a room with a given number of players.

*/

public class Room {



/** Number of players in a room. */

private int numberOfPersons;



/**

* A person enters the room.

* Increments the number of persons.

*/

public void enterPerson() {

numberOfPersons++;

}



/**

* A person leaves the room.

* Decrements the number of persons.

*/

public void leavePerson() {

if ( numberOfPersons > 0 )

numberOfPersons--;

}



/**

* Gets the number of persons in this room.

* This is always greater equals 0.

*

* @return Number of persons.

*/

public int getNumberOfPersons() {

return numberOfPersons;

}

}

Kommentar

Beschreibung

Beispiel

@param

Beschreibung der Parameter

@param a A Value.

@see

Verweis auf ein anderes Paket, einen anderen Typ, eine andere Methode oder Eigenschaft

@see java.util.Date

java.util.Date@see java.lang.String#length()

@version

Version

@version 1.12

@author

Schöpfer

@author Christian Ullenboom

@return

Rückgabewert einer Methode

@return Number of elements.

@exception/@throws

Ausnahmen, die ausgelöst werden können

@exception NumberFormatException

{@link Verweis}

ein eingebauter Verweis im Text im Code-Font; Parameter wie bei @see

{@link java.io.File}

{@linkplain Verweis}

wie {@link}, nur im normalen Font

{@linkplain java.io.File}

{@code Code}

Quellcode im Code-Zeichensatz – auch mit HTML-Sonderzeichen

{@code 1 ist < 2}

{@literal Literale}

Maskiert HTML-Sonderzeichen. Kein Code-Zeichensatz

{@literal 1 < 2 && 2 > 1}

Tabelle 23.3Die wichtigsten Dokumentationskommentare im Überblick

[»]Hinweis

Die Dokumentationskommentare sind so aufgebaut, dass der erste Satz in der Auflistung der Methoden und Attribute erscheint und der Rest in der Detailansicht:

/**

* Ein kurzer Satz, der im Abschnitt "Method Summary" stehen wird.

* Es folgt die ausführliche Beschreibung, die später im

* Abschnitt "Method Detail" erscheint, aber nicht in der Übersicht.

*/

public void foo() { }

Weil ein Dokumentationskommentar /** mit /* beginnt, ist er für den Compiler ein normaler Blockkommentar. Die Javadoc-Kommentare werden oft optisch aufgewertet, indem am Anfang jeder Zeile ein Sternchen steht – dieses ignoriert Javadoc.

 

Zum Seitenanfang

23.4.2Mit dem Werkzeug javadoc eine Dokumentation erstellen Zur vorigen ÜberschriftZur nächsten Überschrift

Aus dem mit Kommentaren versehenen Quellcode generiert ein externes Programm die Zieldokumente. Das JDK liefert das Konsolenprogramm javadoc mit aus, 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.

[zB]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 eine HTML-Seite ist.

inline In Eclipse lässt sich eine Dokumentation mit Javadoc sehr einfach erstellen: Im Menü FileExport ist der Eintrag Javadoc zu wählen, und nach einigen Einstellungen ist die Dokumentation generiert.

[»]Hinweis

Die Sichtbarkeit spielt bei Javadoc eine wichtige Rolle. Standardmäßig nimmt Javadoc nur öffentliche Dinge in die Dokumentation auf.

 

Zum Seitenanfang

23.4.3HTML-Tags in Dokumentationskommentaren * Zur vorigen ÜberschriftZur nächsten Überschrift

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.

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

 

Zum Seitenanfang

23.4.4Generierte Dateien Zur vorigen ÜberschriftZur nächsten Überschrift

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:

  • index-all.html liefert eine Übersicht aller Klassen, Schnittstellen, Ausnahmen, Methoden und Felder in einem Index.

  • overview-tree.html zeigt in einer Baumstruktur die Klassen an, damit die Vererbung deutlich sichtbar ist.

  • allclasses-frame.html zeigt alle dokumentierten Klassen in allen Unterpaketen auf.

  • deprecated-list.html bietet eine Liste der veralteten Methoden und Klassen.

  • serialized-form.html listet alle Klassen auf, die Serializable implementieren. Jedes Attribut erscheint mit einer Beschreibung in einem Absatz.

  • help-doc.html zeigt eine Kurzbeschreibung von Javadoc.

  • 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.

  • stylesheet.css ist eine Formatvorlage für HTML-Dateien, in der sich Farben und Zeichensätze einstellen lassen, die dann alle HTML-Dateien nutzen.

  • packages.htm ist eine veraltete Datei. Sie verweist auf die neuen Dateien.

 

Zum Seitenanfang

23.4.5Dokumentationskommentare im Überblick * Zur vorigen ÜberschriftZur nächsten Überschrift

Einige Javadoc-Kommentare kann der Entwickler in den Block setzen, so wie @param oder @return zur Beschreibung der Parameter oder Rückgaben, andere auch in den Text, wie {@link} zum Setzen eines Verweises auf einen anderen Typ oder eine andere Methode. Tags der ersten Gruppe heißen Block-Tags, die anderen Inline-Tags. Bisher erkennt das Javadoc-Tool die folgenden Tags (ab welcher Version, steht in Klammern):[ 276 ](http://tutego.de/go/javadoctags)

  • Block-Tags: @author (1.0), @deprecated (1.0), @exception (1.0), @param (1.0), @return (1.0), @see (1.0), @serial (1.2), @serialData (1.2), @serialField (1.2), @since (1.1), @throws (1.2), @version (1.0), @apiNote (1.8), @implSpec (1.8), @implNote (1.8)

  • Inline-Tags: {@code} (1.5), {@docRoot} (1.3), {@inheritDoc} (1.4), {@link} (1.2), {@linkplain} (1.4), {@literal} (1.5), {@value} (1.4)

Beispiele

Eine externe Zusatzquelle geben wir wie folgt an:

@see <a href="spec.html#section">Java Spec</a>.

Verweis auf eine Methode, die mit der beschriebenen Methode verwandt ist:

@see String#equals(Object) equals

Von @see gibt es mehrere Varianten:

@see #field

@see #method(Type, Type,...)

@see #method(Type argname, Type argname,...)

@see #constructor(Type, Type,...)

@see #constructor(Type argname, Type argname,...)

@see Class#field

@see Class#method(Type, Type,...)

@see Class#method(Type argname, Type argname,...)

@see Class#constructor(Type, Type,...)

@see Class#constructor(Type argname, Type argname,...)

@see Class.NestedClass

@see Class

@see package.Class#field

@see package.Class#method(Type, Type,...)

@see package.Class#method(Type argname, Type argname,...)

@see package.Class#constructor(Type, Type,...)

@see package.Class#constructor(Type argname, Type argname,...)

@see package.Class.NestedClass

@see package.Class

@see package

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)}

*/

Anstatt HTML-Tags wie <tt> oder <code> für den Quellcode zu nutzen, ist {@code} viel einfacher:

/**

* Compares this current object with another object.

* Uses {@code equals()} an not {@code ==}.

*/
 

Zum Seitenanfang

23.4.6Javadoc und Doclets * Zur vorigen ÜberschriftZur nächsten Überschrift

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, der muss ein eigenes Doclet programmieren oder kann auf Doclets unterschiedlicher Hersteller zurückgreifen. Die (schon etwas angestaubte) 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 sind.

 

Zum Seitenanfang

23.4.7Veraltete (deprecated) Typen und Eigenschaften Zur vorigen ÜberschriftZur nächsten Überschrift

Während der Entwicklungsphase einer Software ändern sich immer wieder Methodensignaturen, oder Methoden kommen hinzu oder fallen weg. Gründe gibt es viele:

  • Methoden können nicht wirklich plattformunabhängig programmiert werden, wurden aber einmal so angeboten. Nun soll die Methode nicht mehr unterstützt werden (ein Beispiel ist die Methode stop() eines Threads).

  • Die Java-Namenskonvention soll eingeführt, ältere Methodennamen sollen nicht mehr verwendet werden. Das betrifft in erster Linie spezielle setXXX(…)/getXXX()-Methoden, die seit Version 1.1 zur Verfügung standen. So finden wir beim AWT viele Beispiele dafür. Nun heißt es zum Beispiel statt size() bei einer grafischen Komponente getSize().

  • Entwickler haben sich beim Methodennamen verschrieben. So hieß es in FontMetrics vorher getMaxDecent(), und nun heißt es getMaxDescent(), und im HTMLEditorKit wird insertAtBoundry(…) zu insertAtBoundary(…).

Es ist ungünstig, die Methoden jetzt einfach zu löschen, weil es dann zu Compilerfehlern kommt. Eine Lösung wäre daher, die Methode oder den Konstruktor als deprecated zu deklarieren. @deprecated ist ein eigener Dokumentationskommentar. Sein Einsatz sieht dann etwa folgendermaßen aus (Ausschnitt aus der Klasse java.util.Date):

Listing 23.2java.util.Date.java, Ausschnitt

/**

* 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

* @deprecated As of JDK version 1.1,

* replaced by <code>Calendar.set(Calendar.DAY_OF_MONTH, int date)</code>. */



public void setDate(int date) {

setField(Calendar.DATE, date);

}

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

[»]Hinweis

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

Compilermeldungen bei veralteten Methoden

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

Listing 23.3OldSack.java

public class OldSack {

java.util.Date d = new java.util.Date( 62, 3, 4 );

}

Jetzt rufen wir ganz normal den Compiler auf:

$ javac OldSack.java

Note: OldSack.java uses or overrides a deprecated API.

Note: Recompile with -deprecation for details.

Der Compiler sagt uns, dass der Schalter -deprecation weitere Hinweise gibt:

$ javac -deprecation OldSack.

OldSack.java:5: warning: Date(int,int,int) in java.util.Date has been deprecated

Date d = new Date( 62, 3, 4 );

^

1 warning

Die Ausgabe gibt genau die Zeile mit der veralteten Anweisung an; Alternativen nennt der Compiler nicht. Allerdings ist schon interessant, dass der Compiler in die Dokumentationskommentare sieht. Eigentlich hat er mit den auskommentierten Blöcken ja nichts zu tun und überliest jeden Kommentar. Zur Auswertung der speziellen Kommentare gibt es schließlich das Extra-Tool javadoc, das wiederum mit dem Java-Compiler nichts zu tun hat.

[»]Hinweis

Auch Klassen lassen sich als deprecated markieren (siehe etwa java.io.LineNumberInputStream). Dies finden wir jedoch selten in der Java-Bibliothek, und bei eigenen Typen sollte es vermieden werden.

Die Annotation »@Deprecated«

Annotationen sind eine Art zusätzlicher Modifizierer. Die Annotation @Deprecated (großgeschrieben) ist vorgegeben 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. Oracle hat die oben genannte Methode setDate(…) mit dieser Annotation gekennzeichnet, wie 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) { ... }

Der Vorteil der Annotation @Deprecated gegenüber dem Javadoc-Tag besteht darin, dass die Annotation auch zur Laufzeit sichtbar ist. Liegt vor einem Methodenaufruf ein @Deprecated-Tester, so kann dieser die veralteten Methoden zur Laufzeit melden. Bei dem Javadoc-Tag übersetzt der Compiler das Programm in Bytecode und gibt zur Compilezeit eine Meldung aus, im Bytecode selbst gibt es aber keinen Hinweis.

Veraltete Bibliotheken

Veraltetes hat sich im Laufe der Zeit genug angesammelt. In der Version Java 8 sind 21 Klassen (zuzüglich 5 Exceptions), 18 Schnittstellen (viele aus CORBA), 3 Annotationstypen und 1 Annotationselement, ca. 350 Methoden, 20 Konstruktoren sowie 60 Variablen/Konstanten als veraltet eingestuft.[ 277 ](https://docs.oracle.com/javase/8/docs/jre/api/security/smartcardio/spec/javax/smartcardio/package-summary.html)

 

Zum Seitenanfang

23.4.8Javadoc-Überprüfung mit DocLint Zur vorigen ÜberschriftZur nächsten Überschrift

Das Javadoc-Tool kann in den Javadoc-Kommentaren Fehler aufspüren; aktiviert wird diese Prüfung mit dem Schalter Xdoclint. DocLint erkennt folgende Gruppen von Fehlern, die auch als Option angegeben werden können:

Gruppe

Beschreibung

accessibility

Prüft auf Probleme mit der Zugänglichkeit der Dokumentation, dass etwa Tabellen immer eine Zusammenfassung besitzen.

html

Erkennt HTML-Fehler, wie fehlende schließende spitze Klammern.

missing

Prüft auf fehlende Elemente, wenn zum Beispiel ein Kommentar fehlt oder @return.

reference

Prüft alle Referenzen in den Javadoc-Tags, etwa bei @see oder auch ungültige Namen bei @param.

syntax

Prüft allgemeine Syntaxfehler wie nicht ausmaskierte HTML-Zeichen wie <, > oder & und nicht existierende Javadoc-Tags.

Tabelle 23.4Mögliche Gruppen bei Javadoc und dem DocLint-Werkzeug

Zu weiteren Optionen der Javadoc-Erweiterung siehe http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html.

 


Ihr Kommentar

Wie hat Ihnen das <openbook> gefallen? Wir freuen uns immer über Ihre freundlichen und kritischen Rückmeldungen.

>> Zum Feedback-Formular
<< zurück
 Zum Katalog
Zum Katalog: Java ist auch eine Insel Java ist auch eine Insel

Jetzt bestellen


 Ihre Meinung?
Wie hat Ihnen das <openbook> gefallen?

Ihre Meinung



 Buchempfehlungen
Zum Katalog: Java ist auch eine Insel

Java ist auch eine Insel




Zum Katalog: Java SE 9-Standard-Bibliothek

Java SE 9-Standard-Bibliothek




Zum Katalog: Professionell entwickeln mit Java EE 8

Professionell entwickeln mit Java EE 8




Zum Katalog: Entwurfsmuster

Entwurfsmuster




Zum Katalog: IT-Projektmanagement

IT-Projektmanagement




 Shopping
Versandkostenfrei bestellen in Deutschland und Österreich

InfoInfo



 

 


Copyright © Rheinwerk Verlag GmbH 2017

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.

 

[Rheinwerk Computing]



Rheinwerk Verlag GmbH, Rheinwerkallee 4, 53227 Bonn, Tel.: 0228.42150.0, Fax 0228.42150.77, service@rheinwerk-verlag.de