home *** CD-ROM | disk | FTP | other *** search
/ Internet News 1999 October / INEWS_10_CD.ISO / pc / jdk / jdk1.2.2 / docs / tooldocs / javadoc / source / standard / PackageWriter.java < prev    next >
Encoding:
Java Source  |  1999-09-19  |  11.0 KB  |  314 lines
  1. /*
  2.  * @(#)PackageWriter.java    1.30 98/08/18
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package com.sun.tools.doclets.standard;
  16.  
  17. import com.sun.tools.doclets.*;
  18. import com.sun.javadoc.*;
  19. import java.io.*;
  20. import java.lang.*;
  21. import java.util.*;
  22.  
  23. /**
  24.  * Class to generate file for each package contents in the right-hand 
  25.  * frame. This will list all the Class Kinds in the package. A click on any
  26.  * class-kind will update the frame with the clicked class-kind page.
  27.  *
  28.  * @author Atul M Dambalkar
  29.  */
  30. public class PackageWriter extends AbstractPackageWriter {
  31.  
  32.     /** 
  33.      * The prev package name in the alpha-order list.
  34.      */
  35.     protected PackageDoc prev;
  36.  
  37.     /** 
  38.      * The next package name in the alpha-order list.
  39.      */
  40.     protected PackageDoc next;
  41.  
  42.     /**
  43.      * Constructor to construct PackageWriter object and to generate 
  44.      * "package-summary.html" file in the respective package directory. 
  45.      * For example for package "java.lang" this will generate file 
  46.      * "package-summary.html" file in the "java/lang" directory. It will also 
  47.      * create "java/lang" directory in the current or the destination directory
  48.      * if it doesen't exist.
  49.      *
  50.      * @param path Directories in this path will be created if they are not 
  51.      * already there.
  52.      * @param filename Name of the package summary file to be generated, 
  53.      * "package-frame.html".
  54.      * @param packagedoc PackageDoc under consideration.
  55.      * @param prev Previous package in the sorted array.
  56.      * @param next Next package in the sorted array.
  57.      */
  58.     public PackageWriter(String path, String filename, PackageDoc packagedoc,
  59.                          PackageDoc prev, PackageDoc next) 
  60.                          throws IOException, DocletAbortException {
  61.         super(path, filename, packagedoc);
  62.         this.prev = prev;
  63.         this.next = next;
  64.     }
  65.  
  66.     /**
  67.      * Generate a package summary page for the right-hand frame. Construct
  68.      * the PackageFrameWriter object and then uses it generate the file.
  69.      *
  70.      * @param pkg The package for which "pacakge-summary.html" is to be
  71.      * generated.
  72.      * @param prev Previous package in the sorted array.
  73.      * @param next Next package in the sorted array.
  74.      */
  75.     public static void generate(PackageDoc pkg, PackageDoc prev,
  76.                                 PackageDoc next) throws DocletAbortException {
  77.         PackageWriter packgen;
  78.         String path = DirectoryManager.getDirectoryPath(pkg);
  79.         String filename = "package-summary.html";
  80.         try {
  81.             packgen = new PackageWriter(path, filename, pkg, prev, next);
  82.             packgen.generatePackageFile();
  83.             packgen.close();
  84.             packgen.copyDocFiles(path);
  85.         } catch (IOException exc) {
  86.             Standard.configuration().standardmessage.
  87.                 error("doclet.exception_encountered", exc.toString(), filename);
  88.             throw new DocletAbortException();
  89.         }
  90.     }
  91.  
  92.     /**
  93.      * Generate class listing for all the classes in this package. Divide class
  94.      * listing as per the class kind and generate separate listing for 
  95.      * Classes, Interfaces, Exceptions and Errors.
  96.      */
  97.     protected void generateClassListing() {
  98.         generateClassKindListing(packagedoc.interfaces(), 
  99.                                  getText("doclet.Interface_Summary"));
  100.         generateClassKindListing(packagedoc.ordinaryClasses(),
  101.                                  getText("doclet.Class_Summary"));
  102.         generateClassKindListing(packagedoc.exceptions(),
  103.                                  getText("doclet.Exception_Summary"));
  104.         generateClassKindListing(packagedoc.errors(),
  105.                                  getText("doclet.Error_Summary"));
  106.     }
  107.     
  108.     /** 
  109.      * Generate specific class kind listing. Also add label to the listing.
  110.      *
  111.      * @param arr Array of specific class kinds, namely Class or Interface or
  112.      * Exception or Error.
  113.      * @param label Label for the listing
  114.      */
  115.     protected void generateClassKindListing(ClassDoc[] arr, String label) {
  116.         if(arr.length > 0) {
  117.             Arrays.sort(arr);    
  118.             tableIndexSummary();
  119.             printFirstRow(label);
  120.             for (int i = 0; i < arr.length; i++) {
  121.                 boolean deprecated = arr[i].tags("deprecated").length > 0;
  122.                 if (Standard.configuration().nodeprecated && deprecated) {
  123.                     continue;
  124.                 }
  125.                 if (!isCoreClass(arr[i])) {
  126.                     continue;
  127.                 }
  128.                 trBgcolorStyle("white", "TableRowColor");
  129.                 summaryRow(15);
  130.                 bold();
  131.                 printClassLinkForSameDir(arr[i]);
  132.                 boldEnd();
  133.                 summaryRowEnd();
  134.                 summaryRow(0);
  135.                 if (deprecated) {
  136.                     boldText("doclet.Deprecated");
  137.                     space();
  138.                     printSummaryDeprecatedComment(arr[i].tags("deprecated")[0]);
  139.                 } else {
  140.                     printSummaryComment(arr[i]);
  141.                 }
  142.                 summaryRowEnd();
  143.                 trEnd();
  144.             }
  145.             tableEnd();
  146.             println(" ");
  147.             p();
  148.         }
  149.     }
  150.  
  151.     /**
  152.      * Print the table heading for the class-listing.
  153.      *
  154.      * @param label Label for the Class kind listing.
  155.      */
  156.     protected void printFirstRow(String label) {
  157.         tableHeaderStart("#CCCCFF");
  158.         bold(label);
  159.         tableHeaderEnd();
  160.     }
  161.  
  162.     /**
  163.      * Print the package comment as specified in the "packages.html" file in 
  164.      * the source package directory.
  165.      */
  166.     protected void printPackageComment() {
  167.         if (packagedoc.inlineTags().length > 0) {
  168.             anchor("package_description");
  169.             h2(getText("doclet.Package_Description", packagedoc.name()));
  170.             p();
  171.             printInlineComment(packagedoc);
  172.             p();
  173.         }
  174.     }
  175.    
  176.     /**
  177.      * Print the package description and the tag information from the
  178.      * "packages.html" file.
  179.      */ 
  180.     protected void printPackageDescription() throws IOException {
  181.         printPackageComment();
  182.         generateTagInfo(packagedoc);
  183.     }
  184.     
  185.     /**
  186.      * Print one line summary cooment for the package at the top of the page and
  187.      * add link to the description which is generated at the end of the page.
  188.      *
  189.      * @param heading Package name.
  190.      */                            
  191.     protected void printPackageHeader(String heading) {
  192.         navLinks(true);
  193.         hr();
  194.         h2(getText("doclet.Package") + " " + heading);
  195.         if (packagedoc.inlineTags().length > 0) {
  196.             printSummaryComment(packagedoc);
  197.             p();
  198.             bold(getText("doclet.See"));
  199.             br();
  200.             printNbsps();
  201.             printHyperLink("", "package_description",
  202.                            getText("doclet.Description"), true);
  203.             p();
  204.         }
  205.     }   
  206.  
  207.     /**
  208.      * Print the navigation bar links at the bottom also print the "-bottom"
  209.      * if specified on the command line.
  210.      */                            
  211.     protected void printPackageFooter() {
  212.         hr();
  213.         navLinks(false);
  214.         printBottom();
  215.     }
  216.  
  217.     /**
  218.      * Copy the "doc-files" directory contents from the source package directory
  219.      * to the generated documentation directory. For example for a package 
  220.      * java.lang this method find out the source location of the package using
  221.      * {@link SourcePath} and if "doc-files" directory is found in the source
  222.      * directory structure, copy the entire directory, to the generated 
  223.      * documentation hierarchy.
  224.      *
  225.      * @param path The sourcepath.
  226.      */
  227.     protected void copyDocFiles(String path) throws DocletAbortException {
  228.         SourcePath sourcePath = new SourcePath(
  229.                                   Standard.configuration().sourcepath);
  230.         String docfilesdir = path + fileseparator + "doc-files";
  231.         File sourcedir = sourcePath.getDirectory(docfilesdir);
  232.         if (sourcedir == null) {
  233.             return;
  234.         }
  235.         String destname = destdir;
  236.         if (destname.length() > 0 && !destname.endsWith(fileseparator)) {
  237.             destname += fileseparator;      
  238.         }
  239.         String src = sourcedir.toString();
  240.         String dest = destname + path + fileseparator + "doc-files";
  241.         try {
  242.             File srcdir = new File(src);
  243.             File destdir = new File(dest);
  244.             DirectoryManager.createDirectory(dest);
  245.             String[] files = srcdir.list();
  246.             for (int i = 0; i < files.length; i++) {
  247.                 File srcfile = new File(srcdir, files[i]);
  248.                 File destfile = new File(destdir, files[i]);
  249.                 if (srcfile.isFile()) {
  250.                     notice("doclet.Copying_File_0_To_Dir_1", 
  251.                             srcfile.toString(), destdir.toString());
  252.                     Standard.copyFile(destfile, srcfile); 
  253.                 }
  254.             }
  255.         } catch (SecurityException exc) {
  256.             throw new DocletAbortException();
  257.         } catch (IOException exc) {
  258.             throw new DocletAbortException();
  259.         }
  260.     }
  261.                 
  262.     /**
  263.      * Print "Use" link for this pacakge in the navigation bar.
  264.      */
  265.     protected void navLinkClassUse() {
  266.         navCellStart();
  267.         printHyperLink("package-use.html", "", getText("doclet.navClassUse"),
  268.                        true, "NavBarFont1");
  269.         navCellEnd();
  270.     }
  271.  
  272.     /**
  273.      * Print "PREV PACKAGE" link in the navigation bar.
  274.      */
  275.     protected void navLinkPrevious() {
  276.         if (prev == null) {
  277.             printText("doclet.Prev_Package");
  278.         } else {
  279.             String path = DirectoryManager.getRelativePath(packagedoc.name(),
  280.                                                            prev.name());
  281.             printHyperLink(path + "package-summary.html", "",
  282.                            getText("doclet.Prev_Package"), true);
  283.         }
  284.     }
  285.                                 
  286.     /**
  287.      * Print "NEXT PACKAGE" link in the navigation bar.
  288.      */
  289.     protected void navLinkNext() {
  290.         if (next == null) {
  291.             printText("doclet.Next_Package");
  292.         } else {
  293.             String path = DirectoryManager.getRelativePath(packagedoc.name(),
  294.                                                            next.name());
  295.             printHyperLink(path + "package-summary.html", "",
  296.                            getText("doclet.Next_Package"), true);
  297.         }
  298.     }
  299.  
  300.     /**
  301.      * Print "Tree" link in the navigation bar. This will be link to the package
  302.      * tree file.
  303.      */
  304.     protected void navLinkTree() {
  305.         navCellStart();
  306.         printHyperLink("package-tree.html", "", getText("doclet.Tree"),
  307.                        true, "NavBarFont1");
  308.         navCellEnd();
  309.     }
  310. }
  311.  
  312.  
  313.  
  314.