Java Programmierung
Kap.10:  ÜBERSETZUNGSEINHEIT, PAKETE, DOKUMENTATION

Kapitel-Index
  10.1   Übersetzungseinheit 
  10.2   Pakete (package) und Import (import)
  10.3   Dokumentation (javadoc)
  10.4   Testfragen                
  Klassen und Schnittstellen werden in Übersetzungseinheiten (10.1) und Paketen (10.2) zusammengefasst und können mit dem java-Kommando javadoc (10.3) dokumentiert werden.

10.1     Übersetzungseinheit 

  Eine Übersetzungseinheit (CompilationUnit) ist nach Syntaxdiagramm 104 von der Form
104: CompilationUnit              ÜbersetzungsEinheit        
HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH
H                                                                H
H                                           ,-------------,      H
H                      ,-------------,      | ClassOr-    |      H
H                      | Import-     |      | Interface-  |      H
H                    ,-| Declaration |<-, ,-| Declaration |<-,   H
H    ,-------------, | '-------------'  | | '-------------'  |   H
H -->| Package-    |-+------------------->---------------------> H
H  | | Declaration | ^                                           H
H  | '-------------' |                                           H
H  '-----------------'                                           H
H                                                                H
HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH
  Wie man sieht, kann eine Übersetzungseinheit leer sein oder aus einer einzelnen Klasse bestehen, z.B. HelloWorld (1.2.1), oder eine Hierarchie aus mehreren Klassen bzw. Schnittstellen vereinbaren, z.B. MehrfachErbe (9.2.2), oder ein Paket mit Klassen bzw. Schnittstellen vereinbaren, z.B. siehe ESt unten (10.2)
         package pac;public abstract class EStTarif {...}
oder mit Import-Vereinbarungen Pakete beobachtbar (observable) machen, z.B. siehe ESt unten (10.2)
                    import pac.*;class ESt {...}                .
  Eine Übersetzungseinheit, die keine Paket-Vereinbarung aufweist, ist Teil eines unbenannten Pakets. In einer Implementation kann es mehrere unbenannte Pakete geben. Gewöhnlich ist das aktuelle Verzeichnis das unbenannte Paket für eine Übersetzungseinheit, die keine Paket-Vereinbarung aufweist.

10.2     Pakete (package) und Import (import) 

  Eine Paket-Vereinbarung(PackageDeclaration) ist nach Syntaxdiagramm 104 von der Form
102: PackageDeclaration           PaketVereinbarung             
                HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH
                H                                 H
                H   ,-----------------,           H
                H   |  ,------------, |           H
                H ->+->| Annotation |-'           H
                H   |  '------------'             H
                H   |             Package-        H
                H   |             ,------,        H
                H   '-> package ->| Name |-> ; -> H
                H                 '------'        H
                H                                 H
                HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH

          z.B. (siehe EstTarif, EStGrund, EStSplit unten)
                             package pac;
  Im Unterschied zu fertig im Java Development Kit angebotenen Paketen muss der Programmierer fehlende Pfade auf eigene Pakete selbst setzen. Das Setzen von Pfaden erübrigt sich, wenn
   # das Paket mit seinen Quelldateien vereinbart wird 
     in einem Unterverzeichnis des aktuellen Verzeichnisses und

   # das Paket importiert wird in einer Stammdatei
     im aktuellen Verzeichnis.
  Nach der Semantik zum Syntaxdiagramm 070 bedeutet das Fehlen von ugriff-Modifizierern public im selben Paket, aber private für anere. Daher müssen Klassen in Paketen public modifiziert werden.
       ,--------------------------------------------------,
    VVV| Klassen in Paketen public modifizieren (Prinzip) |VVV
    VV '--------------------------------------------------' VV
    VV                                                      VV
    VV  Um  von außerhalb des Pakets importierbar zu sein,  VV
    VV  müssen  im  Paket  Klassen,  ihre  Mitglieder  und  VV
    VV  ihre  Konstruktoren, für  die kein Zugriff-Modifi-  VV
    VV  zierer angegeben wurde, public modifiziert werden.  VV
    VV                                                      VV
    VVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVVV
  Am folgenden Beispiel Est wird die Vereinbarung eines Pakets ac im Unterverzeichnis c:\my\pac des aktuellen Verzeichnisses :\my demonstriert. Im Unterverzeichnis c:\my\pac werden die zum aket pac gehörigen Quelldateien EstTarif.java, EstGrund.java und StSplit angelegt, die jeweils mit "package pac;" beginnen müssen. m ausserhalb des Unterverzeichnisses im aktuellen Verzeichnis aufufbar zu sein, werden die Klassen EstTarif.java, EstGrund.java und StSplit und ihre Methoden hebSteuer(int) public modifiziert.
  Eine Import-Vereinbarung (ImportDeclaration) ist nach Syntaxdiagramm 103 von der Form
103: ImportDeclaration            ImportVereinbarung                                          
HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH
H              ClassOrInterface-                -,               H
H               ,------,                         | Single-       H
H -> import --->| Name |----------------------,  |-TypeImport-   H
H            |  '------'                      |  | Declaration   H
H            | starts with                    |  |               H
H            | PackageName                    | -'               H
H            |                                |                  H
H            | PackageOr-                     | -,               H
H            | ClassOrInterface-              |  |               H
H            |  ,------,                      |  | TypeImport-   H
H            |->| Name |-> . -> * ------------|  |-OnDemand-     H
H            |  '------'                      |  | Declaration   H
H            | starts with                    |  |               H
H            | PackageName                    | -'               H
H            |                                |                  H
H ,----------' ClassOrInterface- StaticMember-| -,               H
H |             ,------,       ,------------, |  | Single-       H
H '-> static -->| Name |-> . ->| Identifier |-|  |-StaticImport- H
H            |  '------'       '------------' |  | Declaration   H
H            | starts with                    |  |               H
H            | PackageName                    | -'               H
H            |                                |                  H
H            | ClassOrInterface-              | -,               H
H            |  ,------,                      |  | StaticImport- H
H            '->| Name |-> . -> * ------------|  |-OnDemand-     H
H               '------'                      |  | Declaration   H
H              starts with                    |  |               H
H              PackageName                    | -'               H
H                                             '-> ; ->           H
HHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH

 z.B. einzelne Typ-Import-Vereinbarung (CupApplet, 1.2.2)
               import java.applet.Applet;                             

 z.B. Typ-Import-Vereinbarung auf Anfrage (ESt unten)         
               import pac.*;

 z.B. einzelne Static-Import-Vereinbarung (PrimZahl, 5.3.1)
               import static java.lang.System.Math.sqrt;

 z.B. Static-Import-Vereinbarung auf Anfrage (UmsatzSteuer, 3.1)
               import static java.lang.System.*;
Die Typ-Import-Vereinbarung auf Anfrage
               import java.lang.*;
ist implizit vorgegeben.


  Das folgende Beispiel ESt mit Vereinbarung der Klassen EStTarif, EStGrund und EStSplit im Paket pac entspricht dem Beispiel EinkommenSteuer (9.1.4) mit Vereinbarung der Klassen Tarif, Grund und Split in der Übersetzungseinheit.
//************************** ESt.java ****************************
//                                                               *
//                Grund- und Splitting-Tarif 2010.               *
//              Command: java ESt Einkommen [split]              *
//                                                               *
//  Dateien im Unterverz. C:\my\pac des aktuellen Verz. C:\my :  *
//                                                               *
//  ********************** EStTarif.java **********************  *
//  package pac;                                                 *
//  public abstract class EStTarif                               *
//   {protected int setzTarif(int x)                             *
//     {if     (x<=8004)  {return 0;}                            *
//      else if(x<=13469) {double y=0.0001*(x-8004);             *
//                         return(int)((912.17*y+1400)*y);}      *
//      else if(x<=52881) {double z=0.0001*(x-13469);            *
//                         return(int)((228.74*z+2397)*z+1038);} *
//      else if(x<=250730){return(int)(0.42*x-8172);}            *
//      else              {return(int)(0.45*x-15694);}           *
//     }                                                         *
//    public abstract int hebSteuer(int einkommen);              *
//   }                                                           *
//  ********************** EStGrund.java **********************  *
//  package pac;                                                 *
//  public class EStGrund extends EStTarif                       *
//   {public int hebSteuer(int einkommen)                        *
//                        {return setzTarif(einkommen);}}        *
//  ********************** EStSplit.java **********************  *
//  package pac;                                                 *
//  public class EStSplit extends EStTarif                       *
//   {public int hebSteuer(int einkommen)                        *
//                        {return 2*setzTarif(einkommen/2);}}    *
//****************************************************************

//     java.lang.                                 Object
import pac .*;                              //     `EStTarif
                                            // EStGrund' `EStSplit
class ESt          
{public static void main(String[] args) // args[0],args[1] genutzt
 {int                 einkommen=(int)Double.parseDouble(args[0]);
  if                 (args.length==1)
   {System.out.printf("%7d",new EStGrund().hebSteuer(einkommen));}
  else
   {System.out.printf("%7d",new EStSplit().hebSteuer(einkommen));}
 }
}

//****************************************************************

                                                     Hierarchie
| Command                               | Output        Tarif
+------------------------------------   +-------          |
|java EinkommenSteuer 100000.00         |  33828       ,-----,
|java EinkommenSteuer  10000.00         |    315       |     |
|java EinkommenSteuer 110000.00 split   |  29856     Grund Split

10.3     Dokumentation (javadoc)

  Die Dokumentation von Klassen bzw. Schnittstellen mit HTML-Ausgabe der Hierarchie, Übersichtslisten und Einzelbeschreibungen, soweit sie für die Benutzung wichtig sind, ist in einfacher Weise möglich durch Aufruf des javadoc-Kommandos.

  Als Beispiel wird die Klasse EStTarif (10.2) mit Dokumentationskommentar (1.3.4) versehen und dann dokumentiert.
//************************ EStTarif.java *************************
//       Quelldatei des Pakets pac im Verzeichnis C:\my\pac      *
//****************************************************************
package pac;

/**
 *                     Einkommensteuer-Tarif
 */
public abstract class EStTarif 
 {
  /**
   *                   Setzt Tarif.
   * @param            x ganze Zahl.
   * @return           Tarif, abgerundet auf ganze Zahl.
   */
  protected int setzTarif(int x)                              
   {if     (x<=8004)  {return 0;}                             
    else if(x<=13469) {double y=0.0001*(x-8004);              
                       return(int)((912.17*y+1400)*y);}       
    else if(x<=52881) {double z=0.0001*(x-13469);             
                       return(int)((228.74*z+2397)*z+1038);}  
    else if(x<=250730){return(int)(0.42*x-8172);}              
    else              {return(int)(0.45*x-15694);}             
   }                                                          

  /**
   *                   Hebt Steuer.
   * @param            einkommen ganze Zahl.
   * @return           Steuer, abgerundet auf ganze Zahl.
   * @see              #hebSteuer
   */
  public abstract int hebSteuer(int einkommen);
 }

//****************************************************************
  Um die originale JDK-Dokumentation nicht zu verändern, sollte man das javadoc-Kommando nur im Verzeichnis C:\my\pac der zu dokumentierenden Klasse EStTarif aufrufen!
                  C:\my\pac>javadoc EStTarif.java
  Es wird dann im Verzeichnis von EStTarif die Dokumentation von EStTarif erzeugt, u.a. das mit einem Browser lesbare HTML-Dokument EStTarif.html.

Fig.10.3a.gif
Fig. 10.3a: EStTarif Dokumentation           


Fig.10.3b.gif
Fig. 10.3b: EStTarif Dokumentation           

  Über Aufbau und optionale Argumente des javadoc-Kommandos kann man sich durch Aufruf ohne Argument informieren:
                              javadoc
  Standardmäßig werden folgende "Dokumentations-Paragraphen" im Dokumentations-Kommentar (1.3.4) berücksichtigt:
 @param      Paragraph  nimmt erstes Wort als Parameternamen
 @return     Paragraph  kommentiert den Rückgabewert
 @exception  Paragraph  dokumentiert die ausgeworfene Ausnahme
 @deprecated Paragraph  markiert folgenden Bezeichner deprecated
 @see        Paragraph  verweist auf anderes Ziel in diesem  Paket
 @see  Paket#Paragraph  verweist auf anderes Ziel in anderem Paket
  Wie man an obigem Beispiel EStTarif sieht, bezieht sich ein Paragraph immer auf den nachfolgenden Programm-Text. DokumentationsZeilen anführende * Zeichen samt umgebender Wortzwischenraum -Zeichen (Syntax.A.1.1) werden ignoriert.


10.4      Testfragen

zu    Frage                                  | abdeckbare Antwort
---------------------------------------------+--------------------
                                             |
10.1     Können  in einer Übersetzungseiheit | ja
      mehrere Klassen mit main() vereinbart  |
      werden?                                |
                                             |
10.1/2   Zu  welchem Paket gehört gewöhnlich | zum aktuellen Ver-
      eine  Übersetzungseinheit,  die  keine |  zeichnis, ein
      Paket-Vereinbarung aufweist?           |  unbenanntes Paket
                                             |
10.2     Mit welchem Namen kann im Unterver- | Paket-Vereinbarung
      zeichnis   c:\my\pac\tools  ein  Paket |  package pac.tools;
      vereinbart   werden,  das   in   c:\my | Paket mit Namen
      importierbar ist?                      |  pac.tools
                                             |
10.2    Wie müssen Klassen und ihre Methoden | public oder 
      in  einem  benannten Paket modifiziert |  protected
      werden,  um  von  außerhalb des Pakets |
      importierbar zu sein?                  |
                                             |
10.3     Welche "Dokumentations-Paragraphen" |
      berücksichtigt javadoc standardmäßig?  |
                                             |
         @param   ...                        | standardmäßig
         @return  ...                        |    "
         @author  ...                        | nur mit Argumenten,
         @version ...                        |    siehe javadoc
                                             |
    Java Programmierung
  Kap.11