home *** CD-ROM | disk | FTP | other *** search
/ Internet News 1999 October / INEWS_10_CD.ISO / pc / jdk / jdk1.2.2 / docs / tooldocs / javadoc / source / Configuration.java < prev    next >
Encoding:
Java Source  |  1999-09-19  |  12.4 KB  |  348 lines
  1. /*
  2.  * @(#)Configuration.java    1.15 98/09/22
  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;
  16.  
  17. import com.sun.javadoc.*;
  18. import java.util.*;
  19. import java.io.*;
  20.  
  21. /**
  22.  * Configure the output based on the options. Doclets should sub-class 
  23.  * Configuration, to configure and add their own options. This class contains
  24.  * all user options which are supported by the 1.1 doclet and the standard
  25.  * doclet.
  26.  *
  27.  * @author Robert Field.
  28.  * @author Atul Dambalkar.
  29.  */
  30. public abstract class Configuration {
  31.     /**
  32.      * The Root of the generated Program Structure from the Doclet API.
  33.      */
  34.     public static RootDoc root;
  35.  
  36.     /**
  37.      * Destination directory name, in which doclet will generate the entire
  38.      * documentation. Default is current directory.
  39.      */
  40.     public String destdirname = "";
  41.  
  42.     /**
  43.      * Encoding for this document. Default is default encoding for this 
  44.      * platform.
  45.      */
  46.     public String docencoding = null;
  47.  
  48.     /**
  49.      * Encoding for this document. Default is default encoding for this 
  50.      * platform.
  51.      */ 
  52.     public String encoding = null;
  53.  
  54.     /**
  55.      * Generate author specific information for all the classes if @author 
  56.      * tag is used in the doc comment and if -author option is used.
  57.      * <code>showauthor</code> is set to true if -author option is used.
  58.      * Default is don't show author information. 
  59.      */
  60.     public boolean showauthor = false;
  61.  
  62.     /**
  63.      * Generate version specific information for the all the classes 
  64.      * if @version tag is used in the doc comment and if -version option is 
  65.      * used. <code>showversion</code> is set to true if -version option is 
  66.      * used.Default is don't show version information. 
  67.      */
  68.     public boolean showversion = false;
  69.  
  70.     /**
  71.      * Don't generate the date in the generated documentation, if -nodate 
  72.      * option is used. <code>nodate</code> is set to true if -nodate 
  73.      * option is used. Default is don't show date. 
  74.      */
  75.     public boolean nodate = false;
  76.  
  77.     /**
  78.      * Sourcepath from where to read the source files. Default is classpath.
  79.      * 
  80.      */
  81.     public String sourcepath = "";
  82.  
  83.     /**
  84.      * Don't generate deprecated API information at all, if -nodeprecated 
  85.      * option is used. <code>nodepracted</code> is set to true if 
  86.      * -nodeprecated option is used. Default is generate deprected API 
  87.      * information.
  88.      */
  89.     public boolean nodeprecated = false;
  90.  
  91.     /**
  92.      * All the packages to be documented.
  93.      */
  94.     public PackageDoc[] packages;
  95.  
  96.     /**
  97.      * Message Retriever for the doclet, to retrieve message from the resource
  98.      * file for this Configuration, which is common for 1.1 and standard 
  99.      * doclets.
  100.      */
  101.     public static MessageRetriever message = null;
  102.  
  103.     /**
  104.      * This method should be defined in all those doclets(configurations), 
  105.      * which want to derive themselves from this Configuration. This method
  106.      * can be used to set its own command line options.
  107.      * 
  108.      * @param root Root of the Program Structure generated by Javadoc.
  109.      */
  110.     public abstract void setSpecificDocletOptions(RootDoc root) 
  111.                                            throws DocletAbortException;
  112.  
  113.     /**
  114.      * This method should be defined in all those doclets 
  115.      * which want to inherit from this Configuration. This method 
  116.      * should return the number of arguments to the command line option. 
  117.      * This method is called by the method {@link #optionLength(String)}.
  118.      * 
  119.      * @param option Command line option under consideration.
  120.      * @return number of arguments to option. Zero return means
  121.      * option not known.  Negative value means error occurred.
  122.      * @see #optionLength(String)  
  123.      */
  124.     public abstract int specificDocletOptionLength(String option);
  125.  
  126.     /**
  127.      * This method should be defined in all those doclets 
  128.      * which want to inherit from this Configuration. This method
  129.      * can be used to check the validity of its own command line options. 
  130.      * This method is called by {@link #validOptions(String[][], 
  131.      * DocErrorReporter)}.
  132.      * 
  133.      * @param option   Options-array from the Javadoc.
  134.      * @param reporter Error reporter.
  135.      * @return True if all the options are valid else false.
  136.      */
  137.     public abstract boolean specificDocletValidOptions(String option[][],
  138.                                                    DocErrorReporter reporter);
  139.  
  140.     /**
  141.      * Constructor. Constructs the message retriever with resource file.
  142.      */
  143.     public Configuration() {
  144.         if (message == null) {
  145.             message =
  146.                 new MessageRetriever("com.sun.tools.javadoc.resources.doclets");
  147.         }
  148.     }
  149.  
  150.     /**
  151.      * Set the command line options supported by this configuration.
  152.      *
  153.      * @param root Root of the Program Structure generated by this Javadoc run.
  154.      */
  155.     public void setOptions(RootDoc root) throws DocletAbortException {
  156.         String[][] options = root.options();
  157.         Configuration.root = root;
  158.         packages = root.specifiedPackages();
  159.         Arrays.sort(packages);
  160.         for (int oi = 0; oi < options.length; ++oi) {
  161.             String[] os = options[oi];
  162.             String opt = os[0].toLowerCase();
  163.             if (opt.equals("-d")) {
  164.                 destdirname = addTrailingFileSep(os[1]);
  165.             } else  if (opt.equals("-docencoding")) {
  166.                 docencoding = os[1];
  167.             } else  if (opt.equals("-encoding")) {
  168.                 encoding = os[1];
  169.             } else  if (opt.equals("-author")) {
  170.                 showauthor = true;
  171.             } else  if (opt.equals("-version")) {
  172.                 showversion = true;
  173.             } else  if (opt.equals("-nodeprecated")) {
  174.                 nodeprecated = true;
  175.             } else  if (opt.equals("-xnodate")) {
  176.                 nodate = true;
  177.             } else  if (opt.equals("-sourcepath")) {
  178.                 sourcepath = os[1];
  179.             } else if (opt.equals("-classpath") && 
  180.                        sourcepath.length() == 0) {
  181.                 sourcepath = os[1];
  182.             }
  183.         }
  184.         if (sourcepath.length() == 0) {
  185.             sourcepath = System.getProperty("env.class.path");
  186.         }
  187.         if (docencoding == null) {
  188.             docencoding = encoding;
  189.         }
  190.  
  191.         setSpecificDocletOptions(root);
  192.         HtmlDocWriter.configuration = this;
  193.     }
  194.  
  195.     /**
  196.      * Add a traliling file separator, if not found or strip off extra trailing
  197.      * file separators if any.
  198.      *
  199.      * @param path Path under consideration.
  200.      * @return String Properly constructed path string.
  201.      */
  202.     String addTrailingFileSep(String path) {
  203.     String fs = System.getProperty("file.separator");
  204.         String dblfs = fs + fs;
  205.         int indexDblfs;
  206.         while ((indexDblfs = path.indexOf(dblfs)) >= 0) {
  207.             path = path.substring(0, indexDblfs) + 
  208.                         path.substring(indexDblfs + fs.length());
  209.         }
  210.     if (!path.endsWith(fs))
  211.         path += fs;
  212.     return path;
  213.     }
  214.  
  215.    /**
  216.     * Returns the "length" of a given option. If an option takes no
  217.     * arguments, its length is one. If it takes one argument, it's
  218.     * length is two, and so on. This method is called by JavaDoc to
  219.     * parse the options it does not recognize. It then calls
  220.     * {@link #validOptions(String[][], DocErrorReporter)} to validate them.
  221.     * <b>Note:</b><br>
  222.     * The options arrive as case-sensitive strings. For options that
  223.     * are not case-sensitive, use toLowerCase() on the option string
  224.     * before comparing it.
  225.     * </blockquote>
  226.     *
  227.     * @return number of arguments + 1 for a option. Zero return means
  228.     * option not known.  Negative value means error occurred.
  229.     */
  230.     public int optionLength(String option) {
  231.         option = option.toLowerCase();
  232.         if (option.equals("-version") ||
  233.             option.equals("-nodeprecated") ||
  234.             option.equals("-author") ||
  235.             option.equals("-xnodate")) {
  236.             return 1;
  237.         } else if (option.equals("-docencoding") ||
  238.                    option.equals("-encoding") ||
  239.                    option.equals("-sourcepath") ||
  240.                    option.equals("-d")) {
  241.             return 2;
  242.         } else {
  243.             return specificDocletOptionLength(option);
  244.         }
  245.     }
  246.  
  247.     /**
  248.      * After parsing the available options using {@link #optionLength(String)},
  249.      * JavaDoc invokes this method with an array of options-arrays, where
  250.      * the first item in any array is the option, and subsequent items in
  251.      * that array are its arguments. So, if -print is an option that takes
  252.      * no arguments, and -copies is an option that takes 1 argument, then
  253.      * <pre>
  254.      *     -print -copies 3
  255.      * </pre>
  256.      * produces an array of arrays that looks like:
  257.      * <pre>
  258.      *      option[0][0] = -print
  259.      *      option[1][0] = -copies
  260.      *      option[1][1] = 3
  261.      * </pre>
  262.      * (By convention, command line switches start with a "-", but
  263.      * they don't have to.)
  264.      * This method is not required to be written by sub-classes and will
  265.      * default gracefully (to true) if absent.
  266.      * <P>
  267.      * Printing option related error messages (using the provided
  268.      * DocErrorReporter) is the responsibility of this method.
  269.      *
  270.      * @param options  Options used on the command line.
  271.      * @param reporter Error reporter to be used.
  272.      * @return true if all the options are valid.
  273.      */
  274.     public boolean validOptions(String options[][], 
  275.                                 DocErrorReporter reporter) {
  276.         boolean docencodingfound = false;
  277.         String encoding = "";
  278.         for (int oi = 0; oi < options.length; oi++) {
  279.             String[] os = options[oi];
  280.             String opt = os[0].toLowerCase();
  281.             if (opt.equals("-d")) {
  282.                 String dd = os[1];
  283.                 File destDir = new File(dd);
  284.                 if (!destDir.exists()) {
  285.                     reporter.printError(message.getText(
  286.                         "doclet.destination_directory_not_found_0", 
  287.                                                         destDir.getPath()));
  288.                     return false;
  289.                 } else if (!destDir.isDirectory()) {
  290.                     reporter.printError(message.getText(
  291.                         "doclet.destination_directory_not_directory_0", 
  292.                                                         destDir.getPath()));
  293.                     return false;
  294.                 } else if (!destDir.canWrite()) {
  295.                     reporter.printError(message.getText(
  296.                         "doclet.destination_directory_not_writable_0", 
  297.                                                         destDir.getPath()));
  298.                     return false;
  299.                 }
  300.             } else if (opt.equals("-docencoding")) {
  301.                 docencodingfound = true;
  302.                 if (!checkOutputFileEncoding(os[1], reporter)) {
  303.                     return false;
  304.                 }
  305.             } else if (opt.equals("-encoding")) {
  306.                 encoding = os[1];
  307.             }
  308.         }
  309.         if (!docencodingfound && encoding.length() > 0) {
  310.           if (!checkOutputFileEncoding(encoding, reporter)) {
  311.                     return false;
  312.             }
  313.         }
  314.         return specificDocletValidOptions(options, reporter);
  315.     }
  316.  
  317.     /**
  318.      * Check the validity of the given Source or Output File encoding on this 
  319.      * platform. 
  320.      *
  321.      * @param docencoding Output file encoding.
  322.      * @param reporter    Error reporter object.
  323.      */
  324.     protected boolean checkOutputFileEncoding(String docencoding,
  325.                                               DocErrorReporter reporter) {
  326.         OutputStream ost= new ByteArrayOutputStream();
  327.         OutputStreamWriter osw = null;
  328.        try {
  329.             osw = new OutputStreamWriter(ost, docencoding);
  330.         } catch (UnsupportedEncodingException exc) {
  331.             reporter.printError(message.getText(
  332.                                 "doclet.Encoding_not_supported", docencoding));
  333.             return false;                  
  334.         } finally {
  335.             try {
  336.                 if (osw != null) {
  337.                     osw.close();
  338.                 }
  339.             } catch (IOException exc) {
  340.             }
  341.         } 
  342.         return true;
  343.     }       
  344.  
  345. }
  346.  
  347.  
  348.