Heiner Kücker

JspDoc

Home

Java-Seite

   ASM Improved

   heterogene
   Map, HMap

   Constraint
   Code Generator

   JSP WorkFlow
   PageFlow FlowControl
   Page Flow Engine
   Web Flow Engine
   Control_and_Command

   JSP_Spreadsheet

   Code-Generator
   für Option-Either-Stil
   in Java

   verbesserter
   Comparator

   Fluent-Interface
   Code-Generator
   auf Basis
   einer Grammatik

   Visitor mit Multidispatch

   for-Schleife mit
   yield-return

   Kognitions-Maschine
   semantisches Netz

   Domain Parser

   Codegenerator_für
   hierarchische
   Datenstrukturen

   Expression_Engine
   Formula_Parser

   Thread Preprocessor

   State Transition Engine

   AspectJ

   Java_Explorer

   DBF_Library

   Kalender_Applet

   SetGetGen

   BeanSetGet

   CheckPackage

   LineNumbers

   GradDms

   Excel-Export

   StringTokenizer

   JspDoc

   JspCheck

   JSP-Schulung
   Java Server Pages
   Struts

   Ascii-Tabellen-
   Layouter

   Ascii-Baum-
   Layouter

   Ascii-Art-Fluss-
   Diagramm-
   Parser

   AsciiArt
   AssignmentMatrix
   Layouter

   StringSerial

   Silbentrennung

   JDBC_Schlüssel-
   Generierung

   bidirektional/
   unidirektional
   gelinkte Liste

   Java_Sitemap
   Generator

   XmlBuilder

   RangeMap

   StringFormatter

   VersionSafe
   XCopy

   JTextField

   CommandLine-
   ParamReader

   Bitmap-Grafik

   MultiMarkable-
   Buffered-
   InputStream

   JavaCache

   JdomUtil

   CollectionUtil

   XML Really
   Pull Parser

   Log-Filter

   Remote-Protokoll

   Sudoku-Generator

   Delegation statt
   Mehrfachvererbung

   Disjunct
   Interval Set

   WebCam_Demo

   Weiterentwicklung_Java

Alaska-XBase++-Seite

Projekte

Philosophien
Techniken


Konzepte

Sudoku

Kontakt /
Impressum


Links

SiteMap





Letzte Aktualisierung:
23.01.2003
JspDoc

Tool zum Erzeugen von javadoc-Dokumentationen für Java Server Pages.

javadoc ist der Standard für die Dokumentation von Java-Programmen. Es bietet einen einheitlichen Rahmen für die Dokumentation von Source-Files und erzeugt Dokumentationen im HTML-Format mit Verzeichnissen, Hyperlinks, Vererbungsbäumen und Indizes in gutaussehender und leistungsfähiger Form. Leider sind JSP-Dateien bei der Dokumentation über javadoc aussen vor. Das hier vorgestellte kleine Tool ermöglicht die Anwendung des javadoc-Tools auch auf die für Web-Applikationen wichtigen JSP-Dateien.

Die Arbeitsweise von jspdoc

Jspdoc durchläuft das per Parameter übergebene JSP-Verzeichnis rekursiv und parst die JSP-Dateien ein.
In den JSP-Dateien sucht jspdoc nach der javadoc-Startsequenz
/**
Der hier folgende Block wird bis zum endenden
*/
eingelesen.

Dies setzt voraus, dass die reservierten Sequenzen nicht im HTML-Code benutzt werden. Sonst wäre ein wesentlich aufwändigerer Parser notwendig. Ich habe zwar im Verlaufe meiner Programmiertätigkeit das Reservieren von Zeichen für einen speziellen Zweck (Escape-Sequenzierung) als Quelle allen Übels identifiziert, aber an dieser Stelle ist es wahrscheinlich in Ordnung.

Als Platzhalter für die JSP-Datei wird im per Parameter übergebenen Source-Verzeichnis eine entsprechende Java-Datei mitsamt Sub-Pfad angelegt. Als Klassen-Name wird der Name der JSP-Datei verwendet. Das Package entspricht dem Pfad der JSP-Datei.

Der Einbau von javadoc-Kommentaren in JSP´s soll aber nicht dem Zupflastern der JSP´s mit Code Vorschub leisten. JSP´s dienen als View; Code zur HTML-Generierung sollte in Custom-Tag-Librarys untergebracht werden und funktionaler Code gehört in Servlets oder like Struts in Action-Methoden.

Weitere Dateien

Im Webordner gibt es ausser den JSP´s noch weitere Dateien:
css - Cascading Style Sheets
js  - Java Script
gif - Grafiken
jpg
Es kann wünschenswert sein, auch Kommentare zu diesen Dateien mitzuführen. Dafür kann in den jeweiligen Verzeichnissen jeweils eine Datei
files.jspdoc
hinterlegt werden. Diese Datei enthält entsprechende Kommentare im bekannten Properties-File-Format
larr.gif = GIF-Grafik Pfeil links,  left arrow
rarr.gif = GIF-Grafik Pfeil rechts, right arrow
Da der Kommentar auf eine Zeile beschränkt ist, wird als Ersatz für den Zeilenumbruch \n verwendet.

Für die Package-Übersichtsdokumentation sind in javadoc die Dateien package.html vorgesehen. jspdoc verwendet dafür die Dateien package.jspdoc. Sie werden unter dem Namen package.html in die Source-Verzeichnisse kopiert.

Beim Zusammenbau einer Web-Applikation zu einem war-File sollten die Dateien files.jspdoc und package.jspdoc ausgeschlossen werden.

Konfigurations-Parameter

Als Startparameter sind nötig:
-JSP-Verzeichnis
-Ziel-Verzeichnis in welches die temporären Java-Quell-Klassen abgelegt werden
-Package für die generierten java-Files
Im Zielverzeichnis wird ein weiterer dem Package entsprechender Unterpfad angelegt. Hier ein Beispiel:
-Ziel-Verzeichnis G:\javaprog\src
-Package          de.javaprog.JSP
-JSP-Datei        web\purchase\purchaseitem.jsp
Daraus entsteht der engültige Pfad:
G:\javaprog\src\de\javaprog\JSP\purchase\purchaseitem
mit dem Package:
de.javaprog.JSP.purchase

Probleme

Die Namen der erzeugten Java-Klassen müssen die Restriktionen für Java- Identifier erfüllen:
  • An erster Stelle muss ein Buchstabe, ein Unterstrich oder eines der drei Währungssymbole Dollar $, Pfund £ oder Yen ¥ stehen.
  • Ab dem zweiten Zeichen können Ziffern verwendet werden.
  • Schlüsselwörter müssen vermieden werden.
Die in Dateibezeichnern oft verwendeten Punkte und andere nicht erlaubte Zeichen wandelt jspdoc in Unterstriche um.

Einbindung in ANT

Der Aufruf von jspdoc wird in das javadoc-Target gelegt. Ein Target ist eine auszuführende Aufgabe, die aus mehreren Kommandos, in ANT heissen die Kommandos Tasks, besteht. Am einfachsten ist ein Target mit einer Prozedur vergleichbar. In ANT ist es über den Build-In-Task <java> möglich, Java-Programme zu starten. Darüber wird jspdoc ein- oder mehrmals gestartet um die temporären Klassen zu erzeugen. Danach wird der javadoc-Task aufgerufen. Nach dem Erzeugen der javadoc-HTML- Files werden die temporären Klassen mit allen dazugehörenden Verzeichnissen gelöscht. Im aufgelisteten Beispiel wird die javadoc-Generierung im Sinne einer Script-Strukturierung in ein javadoc-Target und ein init-Target aufgeteilt.

  <!-- =================================================================== -->
  <!-- Initialization target                                               -->
  <!-- =================================================================== -->
  <target name="init">
    <!-- JspDoc parameters -->
    <property name="jspdocprog.dir" value="../jspdocprog"/>
    <property name="jsp.dir" value="./web"/>
    <property name="jspdocetc.dir" value="./etc"/>
    <property name="jspdocdest.dir" value="./src"/>
    <property name="jspdoc.package" value="de.jspdoctest.JSP"/>
    <property name="jspdocetc.package" value="de.jspdoctest.etc"/>
    <property name="jspdoc.tempdir" value="${jspdocdest.dir}\de\jspdoctest"/>
  </target>

  <!-- =================================================================== -->
  <!-- Creates the API documentation                                       -->
  <!-- =================================================================== -->
  <target name="javadoc" depends="init">
    <delete dir="${jspdoc.tempdir}"/> <!-- temporaere java-Files loeschen -->
    <!-- Aufruf jspdoc fuer JSP-Dateien -->
    <echo message="***********  JspDoc ${jsp.dir}  ***********"/>
    <java classname="JspDoc" fork="true" failonerror="true">
      <classpath>
        <pathelement path="${jspdocprog.dir}"/>
      </classpath>
      <arg value="${jsp.dir}"/>
      <arg value="${jspdocdest.dir}"/>
      <arg value="${jspdoc.package}"/>
    </java>

    <!-- Aufruf jspdoc fuer etc-Dateien -->
    <echo message="***********  JspDoc ${etc.dir}  ***********"/>
    <java classname="JspDoc" fork="true" failonerror="true">
      <classpath>
        <pathelement path="${jspdocprog.dir}"/>
      </classpath>
      <arg value="${jspdocetc.dir}"/>
      <arg value="${jspdocdest.dir}"/>
      <arg value="${jspdocetc.package}"/>
    </java>

    <mkdir dir="${build.javadocs}"/>
    <javadoc packagenames="${packages}"
             classpath="${classpath}"
             sourcepath="${build.src}"
             destdir="${build.javadocs}"
             author="true"
             version="true"
             use="true"
             splitindex="true"
             noindex="false"
             windowtitle="${apptitle} API"
             doctitle="${apptitle}"
             bottom="Heiner Kuecker www.heiner-kuecker.de"
    />
    <delete dir="${jspdoc.tempdir}"/> <!-- temporaere java-Files loeschen -->
  </target>


Download der Quelldateien jspdoc.zip

Mitgelieferte Dateien:

jspdoc.zip enthält eine für JSP-Web-Applikationen typische Verzeichnis-Struktur:

\jspdoc\checkpackage Prüfprogramm für die package-Deklaration
\jspdoc\jspdocprog Programm zum Erzeugen der temporären Java-Klassen
\jspdoc\jspdoctest Ant-Starter build.bat und Ant-Script build.xml
\jspdoc\jspdoctest\etc Konfigurationsdateien der Web-App
\jspdoc\jspdoctest\javadoc Generierte javadoc-HTML-Dokumentation, Start mit index.html
\jspdoc\jspdoctest\lib Verzeichnis für jar-Files
\jspdoc\jspdoctest\src Java-Sourcen des Projekts
\jspdoc\jspdoctest\src\de\jspdoctest temporäre Java-Sourcen für jspdoc
\jspdoc\jspdoctest\web Verzeichnis für JSP-Dateien, HTML-Dateien, Grafiken und Cascading Style Sheets etc.
Voraussetzung zum Nachvollziehen der Beispiele ist die Installation eines JDK und des ANT-Build-Tools. Die Umgebungsvariablen JAVA_HOME und ANT_HOME müssen in der Windows-Systemsteuerung oder entsprechenden .profile-Files richtig gesetzt sein. Danach sollte der Aufruf des ANT-Starters build.bat funktionieren.

Installation:

Entpacken in Verzeichnis Ihrer Wahl (z.B. G:\jspdoc)

Start mit build.bat im Verzeichnis /jspdoc/jspdoctest

Andere ähnliche Tools

Es gibt noch einige vergleichbare Tools. Eine Suche auf Google hilft hier weiter:

Google-Suche nach jspdoc

Achtung: Erweiterungen und Fixes stelle ich ohne Historie und ohne Ankündigung hier bereit.
Deshalb am besten immer die letzte Version runterladen.

Lizenzbedingungen:

Die Programme, Quelltexte und Dokumentationen können ohne irgendwelche Bedingungen kostenlos verwendet werden.
Sie sind Freeware und Open Source. Für Fehler und Folgen wird keinerlei Haftung übernommen.

Hinweise zur Fehlerbeseitigung und Verbesserung sind mir willkommen.

Ich freue mich auch über Feedback bezüglich der erfolgreichen Verwendung meiner Sourcen.

Bei Fragen helfe ich gern mit Hinweisen oder zusätzlicher Dokumentation, falls ich dafür Zeit habe.