26.2 Werkzeuge zur Dokumentation und Archivierung
Aufruf
javadoc [ options ] { package | sourcefile }
|
Beschreibung
javadoc
ist ein Programm, das aus Java-Quelltexten Dokumentationen im HTML-Format
erstellt. Dazu verwendet es die öffentlichen Klassen-, Interface-
und Methodendeklarationen und fügt zusätzliche Informationen
aus eventuell vorhandenen Dokumentationskommentaren hinzu. Zu jeder
Klassendatei xyz.java wird eine
HTML-Seite xyz.html generiert,
die über verschiedene Querverweise mit den anderen Seiten desselben
Projekts in Verbindung steht. Zusätzlich generiert javadoc
diverse Index- und Hilfsdateien, die das Navigieren in den Dokumentationsdateien
erleichtern.
Bereits ohne zusätzliche Informationen erstellt javadoc
aus dem Quelltext eine brauchbare Beschreibung aller Klassen und Interfaces.
Durch das Einfügen von Dokumentationskommentaren kann die Ausgabe
zusätzlich bereichert werden. Ein Dokumentationskommentar beginnt
mit /**
und endet mit */ und ähnelt
damit einem gewöhnlichen Kommentar. Er muß im Quelltext
immer unmittelbar vor dem zu dokumentierenden Item plaziert werden
(einer Klassendefinition, einer Methode oder einer Instanzvariable).
Er kann aus mehreren Zeilen bestehen. Die erste Zeile des Kommentars
wird später als Kurzbeschreibung verwendet.
|
Zur Erhöhung der Übersichtlichkeit darf am Anfang jeder
Zeile ein Sternchen stehen, es wird später ignoriert. Innerhalb
der Dokumentationskommentare dürfen neben normalem Text auch
HTML-Tags vorkommen. Sie werden unverändert in die Dokumentation
übernommen und erlauben es damit, bereits im Quelltext die Formatierung
der späteren Dokumentation vorzugeben. Die Tags <h1>
und <h2> sollten möglichst
nicht verwendet werden, da sie von javadoc
selbst zur Strukturierung der Ausgabe verwendet werden. |
 |
|
|
javadoc
erkennt des weiteren markierte Absätze innerhalb von Dokumentationskommentaren.
Die Markierung muß mit dem Zeichen @
beginnen und - abgesehen von Leerzeichen - am Anfang der Zeile stehen.
Jede Markierung leitet einen eigenen Abschnitt innerhalb der Beschreibung
ein, alle Markierungen eines Typs müssen hintereinander stehen.
Tabelle 26.5 gibt eine Übersicht
der wichtigsten Markierungen und beschreibt, wie sie verwendet werden.
| Markierung und Parameter |
Dokumentation |
Verwendung in |
| @author
name |
Erzeugt einen Autoreneintrag. |
Klasse, Interface |
| @version
version |
Erzeugt einen Versionseintrag. Darf höchstens
einmal je Klasse oder Interface verwendet werden. |
Klasse, Interface |
| @since
jdk-version |
Beschreibt, seit wann das beschriebene Feature
existiert. |
Klasse, Interface |
| @see
reference |
Erzeugt einen Querverweis auf eine andere
Klasse, Methode oder einen beliebigen anderen Teil der Dokumentation.
Gültige Verweise sind:
- @see java.util.Vector
- @see Vector
- @see Vector#addElement
- @see <a href="Spez.html">Spez</a>
|
Klasse, Interface, Instanzvariable, Methode
|
| @param
name description |
Parameterbeschreibung einer Methode. |
Methode |
| @return
description |
Beschreibung des Rückgabewerts einer
Methode. |
Methode |
| @exception
classname description |
Beschreibung einer Ausnahme, die von dieser
Methode ausgelöst wird. |
Methode |
| @deprecated
description |
Markiert eine veraltete Methode, die zukünftig
nicht mehr verwendet werden sollte. |
Methode |
Tabelle 26.5: Markierungen in Dokumentationskommentaren
Aufruf von javadoc
Um javadoc
aufzurufen, sollte zunächst in das Verzeichnis gewechselt werden,
in dem sich die zu dokumentierenden Quelldateien befinden. Anschließend
kann durch Eingabe des folgenden Kommandos die Erzeugung der Dokumentationen
für alle Quelldateien gestartet werden:
javadoc *.java
Das Programm erzeugt eine Reihe von HMTL-Dateien, die die zu den jeweiligen
Quellen korrespondierenden Dokumentationen enthalten. Zusätzlich
werden eine Reihe von Hilfsdateien zur Darstellung und Indexierung
der Dokumentationsdateien erstellt.
Alternativ zum Aufruf mit einer Reihe von Quelldateien kann javadoc
auch mit Paketnamen als Argument aufgerufen werden. Wenn der Klassenpfad
korrekt gesetzt ist, spielt es dann keine Rolle mehr, aus welchem
Verzeichnis das Programm gestartet wird, denn die Klassendateien werden
automatisch korrekt gefunden. Wenn nicht per Schalter -d
etwas anderes angegeben wurde, erzeugt javadoc
die Dokumentationsdateien im aktuellen Verzeichnis.
|
In den JDKs 1.0 und 1.1 erzeugt javadoc
zwei unterschiedliche Arten von Standardverweisen. Bei der ersten
Art werden Grafiken eingebunden, um Überschriften für die
verschiedenen Dokumentationsabschnitte zu generieren. Damit diese
im Browser korrekt angezeigt werden, muß ein Unterverzeichnis
images angelegt und die erforderlichen
Grafikdateien dorthin kopiert werden (beispielsweise aus \jdk1.1.2\docs\api\images).
Ab dem JDK 1.2 werden dagegen keine Grafikdateien mehr benötigt. |
|
|
|
Die zweite Art von Verweisen ist die auf Klassen oder Methoden der
Java-Klassenbibliothek (z.B. java.lang.String).
Im JDK 1.1 geht javadoc
davon aus, daß sich die Dokumentationsdateien zu allen externen
Klassen und Methoden im selben Verzeichnis wie die zu erstellenden
Dokumentationsdateien befinden. Damit also externe Verweise funktionieren,
müßte man die HTML-Files der Originaldokumentation des
JDK in sein eigenes Dokumentationsverzeichnis kopieren, was sicherlich
nicht immer praktikabel ist.
|
Im JDK 1.2 wurde die Option -link
eingeführt, mit der ein Pfad auf die Dokumentation der Standardklassen
angegeben werden kann. Der Pfad muß als URL angegeben werden
und das Verzeichnis beschreiben, in dem die Datei package-list
der Dokumentationsdateien liegt. In der Dokumentation zu javadoc
gibt SUN folgendes Beispiel an:
javadoc -link http://java.sun.com/products/jdk/1.2/docs/api ...
|
|
|
|
Dadurch wird bei Standard-Klassennamen auf die auf dem SUN-Server
liegende Originaldokumentation verwiesen. Soll dagegen auf eine lokal
installierte Dokumentation verwiesen werden, kann auch ein file-URL
angegeben werden. Liegt die Dokumentation des JDK beispielsweise im
Verzeichnis c:\jdk1.2\docs (und
somit die API-Dokumentation im Verzeichnis c:\jdk1.2\docs\api),
kann javadoc
wie folgt aufgerufen werden:
javadoc -link file:///c:/jdk1.2/docs/api ...
Optionen
| Option |
Bedeutung |
| -classpath path |
Gibt die Liste der Pfade zur Suche von Klassendateien
an |
| -public |
Nur Elemente des Typs public
werden dokumentiert |
| -protected |
Elemente des Typs public
und protected
werden dokumentiert (das ist die Voreinstellung) |
| -package |
Elemente des Typs package,
public
und protected
werden dokumentiert |
| -private |
Alle Elemente werden dokumentiert |
| -version |
Versionseintrag generieren |
| -author |
Autoreneintrag generieren |
| -sourcepath path |
Pfad mit den Quelldateien |
| -d directory |
Verzeichnis, in dem die generierten Dokumentationsdateien
abgelegt werden. Standardmäßig werden sie im aktuellen
Verzeichnis angelegt. |
| -verbose |
Ausgabe zusätzlicher Meldungen während
der Dokumentationserstellung |
Tabelle 26.6: Einige Optionen von javadoc
|
Neben den hier erwähnten Schaltern kennt javadoc
(insbesondere im JDK 1.2) eine ganze Reihe zusätzlicher Optionen,
mit denen die Codeerzeugung beeinflußt werden kann. Bemerkenswert
ist dabei auf jeden Fall das Konzept der Doclets,
mit denen das Verhalten von javadoc
und das Aussehen der generierten Dokumentationsdateien weitgehend
verändert werden kann. Doclets sind Zusatzmodule für javadoc,
deren Aufgabe es ist, auf der Basis des Doclet-APIs und der geparsten
Quelltexte die Ausgabedateien zu erzeugen. Ob der generierte Code
dabei im HTML-, RTF- oder einem anderen Format erzeugt wird, spielt
keine Rolle. Das mit dem JDK 1.2 ausgelieferte Standard-Doclet erzeugt
die Dokumentationsdateien im HTML-Format. |
|
|
|
Aufruf
jar [ commands ] archive { input-file }
|
Beschreibung
jar
ist ein Archivierungswerkzeug, das Dateien und komplette Unterverzeichnisse
komprimieren und in eine gemeinsame Archivdatei packen kann. Es verwendet
ein Kompressionsformat, das den diversen zip-/unzip-Programmen
ähnelt, und wird analog dem UNIX-Tool tar
bedient. Ein Vorteil von jar
ist seine Portabilität, die sowohl für das erzeugte Dateiformat
als auch für das (in Java geschriebene) Programm selbst gilt.
Wichtigster Einsatzzweck von jar
ist es, alle zu einem Applet gehörenden Dateien (.class-,
Image-, Sound-Dateien usw.) in einer einzigen Datei zusammenzufassen.
Dadurch müssen Web-Browser nicht für jede einzelne Datei,
die in einem Applet benötigt wird, eine eigene GET-Transaktion
absetzen, sondern können alle erforderlichen Files in einem Schritt
laden. Die Ladezeit von Applets wird dadurch drastisch verringert,
insbesondere, wenn viele kleine Dateien benötigt werden.
Kommandos
Im Gegensatz zu den übrigen Programmen, die in diesem Kapitel
vorgestellt wurden, kennt jar
keine Optionsparameter, sondern erwartet Kommandos an ihrer
Stelle. Ein Kommando besteht aus einem Buchstaben, der ohne den Präfix
- angegeben wird. Sollen mehrere
Kommandos kombiniert werden, so werden die zugehörigen Buchstaben
ohne Lücken direkt hintereinander geschrieben. Diese abweichende
Syntax stammt von dem Kommando tar,
das auf UNIX-Rechnern zur Archivierung von Dateien eingesetzt wird.
Tabelle 26.7 gibt eine Übersicht
der verfügbaren Kommandos.
| Kommando |
Bedeutung |
| c |
Erzeugt eine neue Archivdatei (create).
Kann nicht zusammen mit t oder x verwendet werden. |
| t |
Gibt das Inhaltsverzeichnis der Archivdatei
aus (table of contents). Kann nicht zusammen mit c oder x verwendet
werden. |
| x file |
Extrahiert eine oder mehrere Dateien aus
dem Archiv (extract). Kann nicht zusammen mit c oder t verwendet
werden. |
| u |
Fügt die angegebenen Dateien in die
bestehende Archivdatei ein. |
| f |
Gibt an, daß der nächste Parameter
der Name der Archivdatei ist. Wird das Kommando f nicht angegeben,
verwendet jar statt dessen die Standardein- und ausgabe. |
| v |
Gibt zusätzliche Informationen aus
(verbose). Kann zusätzlich zu einem der anderen Kommandos
verwendet werden. |
| 0 |
Die Dateien werden ohne Kompression gespeichert.
|
Tabelle 26.7: Kommandos von jar
|
Sollen beispielsweise alle .java-Dateien
des aktuellen Verzeichnisses in ein Archiv mit der Bezeichnung xyz.jar
gepackt werden, so kann dazu folgendes Kommando verwendet werden:
jar cf xyz.jar *.java
|
|
|
|
Das Inhaltsverzeichnis des Archivs kann folgendermaßen abgerufen
werden:
jar tf xyz.jar
Etwas ausführlicher geht es mit:
jar tvf xyz.jar
Um die Datei Test.java aus dem
Archiv zu extrahieren, kann das folgende Kommando verwendet werden
(das natürlich auch ohne den Zusatz v
funktioniert):
jar xvf xyz.jar Test.java
Verwendung von jar-Dateien in Applets
Die Verwendung von jar-Dateien
in Applets erfolgt mit Hilfe des ARCHIVE-Parameters
des APPLET-Tags (siehe Kapitel 25).
Soll beispielsweise das »Hello, World«-Programm HWApplet.java
aus Listing 25.7 aus einem jar-Archiv
hello.jar ausgeführt werden,
so ist in den folgenden Schritten vorzugehen.
Zunächst werden die Dateien HWApplet.class,
hello.au und world.au
in ein jar-Archiv
gepackt:
jar cvf hello.jar HWApplet.class hello.au world.au
Anschließend wird die HTML-Datei HWApplet.html
zum Aufruf des Applets erstellt:
001 <html>
002 <head>
003 <title>HWApplet</title>
004 </head>
005 <body>
006 <h1>HWApplet</h1>
007 <applet
008 code=HWApplet.class
009 archive=hello.jar
010 width=300
011 height=200>
012 Hier steht das Applet HWApplet.class
013 </applet>
014 </body>
015 </html>
|
HWApplet.html |
Listing 26.1: HTML mit ARCHIVE-Tag
Nun kann das Applet wie bisher gestartet werden, benötigt aber
zum Laden aller Dateien nur noch eine einzige HTTP-Transaktion.
|
Leider unterstützen noch nicht alle Browser das jar-Format,
so daß seine Verwendung zum heutigen Zeitpunkt überlegt
sein will. Für die nahe Zukunft ist es aber ein wichtiger Schritt
zur Verbesserung der Ladezeiten von Applets. |
|
|
|
Aufruf
javap [ options ] classname
|
Beschreibung
Der Disassembler javap
liest den übersetzten Code einer Klasse und gibt Informationen
darüber auf der Standardausgabe aus. Dabei können entweder
nur Informationen über Variablen und Methoden oder der komplette
Bytecode der Klasse ausgegeben werden. javap
ist nicht in der Lage, den Java-Quellcode einer Klassendatei wieder
herzustellen. Beim Aufruf ist der Name der Klasse ohne die Erweiterung
.class anzugeben, also beispielsweise:
javap -c java.lang.String
Optionen
| Option |
Bedeutung |
| -classpath path |
Gibt die Liste der Pfade zur Suche von Klassendateien
an. |
| -public |
Nur die Klassenelemente des Typs public
werden angezeigt. |
| -protected |
Nur die Klassenelemente des Typs public
und protected
werden angezeigt. |
| -package |
Die Klassenelemente des Typs public,
protected
und die Elemene mit Paketsichtbarkeit werden angezeigt. Das ist die
Voreinstellung. |
| -private |
Alle Klassenelemente werden angezeigt. |
| -c |
Disassemblieren des Codes. |
| -s |
Ausgabe der Methodensignaturen. |
| -l |
Ausgabe von Zeilennummern. |
Tabelle 26.8: Optionen von javap