FileDocCategorySizeDatePackage
Configuration.javaAPI DocExample12495Wed Apr 19 11:17:16 BST 2000com.sun.tools.doclets

Configuration

public abstract class Configuration extends Object
Configure the output based on the options. Doclets should sub-class Configuration, to configure and add their own options. This class contains all user options which are supported by the 1.1 doclet and the standard doclet.
author
Robert Field.
author
Atul Dambalkar.

Fields Summary
public static RootDoc
root
The Root of the generated Program Structure from the Doclet API.
public String
destdirname
Destination directory name, in which doclet will generate the entire documentation. Default is current directory.
public String
docencoding
Encoding for this document. Default is default encoding for this platform.
public String
encoding
Encoding for this document. Default is default encoding for this platform.
public boolean
showauthor
Generate author specific information for all the classes if @author tag is used in the doc comment and if -author option is used. showauthor is set to true if -author option is used. Default is don't show author information.
public boolean
showversion
Generate version specific information for the all the classes if @version tag is used in the doc comment and if -version option is used. showversion is set to true if -version option is used.Default is don't show version information.
public boolean
nodate
Don't generate the date in the generated documentation, if -nodate option is used. nodate is set to true if -nodate option is used. Default is don't show date.
public String
sourcepath
Sourcepath from where to read the source files. Default is classpath.
public boolean
nodeprecated
Don't generate deprecated API information at all, if -nodeprecated option is used. nodepracted is set to true if -nodeprecated option is used. Default is generate deprected API information.
public PackageDoc[]
packages
All the packages to be documented.
public static MessageRetriever
message
Message Retriever for the doclet, to retrieve message from the resource file for this Configuration, which is common for 1.1 and standard doclets.
Constructors Summary
public Configuration()
Constructor. Constructs the message retriever with resource file.


                                                  
         
                                            

                                                                                
        

                                                                          
        
                                                    

                 
      
        if (message == null) {
            message =
                new MessageRetriever("com.sun.tools.javadoc.resources.doclets");
        }
Methods Summary
java.lang.StringaddTrailingFileSep(java.lang.String path)
Add a traliling file separator, if not found or strip off extra trailing file separators if any.

param
path Path under consideration.
return
String Properly constructed path string.

	String fs = System.getProperty("file.separator");
        String dblfs = fs + fs;
        int indexDblfs;
        while ((indexDblfs = path.indexOf(dblfs)) >= 0) {
            path = path.substring(0, indexDblfs) + 
                        path.substring(indexDblfs + fs.length());
        }
	if (!path.endsWith(fs))
	    path += fs;
	return path;
protected booleancheckOutputFileEncoding(java.lang.String docencoding, com.sun.javadoc.DocErrorReporter reporter)
Check the validity of the given Source or Output File encoding on this platform.

param
docencoding Output file encoding.
param
reporter Error reporter object.

        OutputStream ost= new ByteArrayOutputStream();
        OutputStreamWriter osw = null;
   	try {
            osw = new OutputStreamWriter(ost, docencoding);
        } catch (UnsupportedEncodingException exc) {
            reporter.printError(message.getText(
                                "doclet.Encoding_not_supported", docencoding));
            return false;                  
        } finally {
            try {
                if (osw != null) {
                    osw.close();
                }
            } catch (IOException exc) {
            }
        } 
        return true;
public intoptionLength(java.lang.String option)
Returns the "length" of a given option. If an option takes no arguments, its length is one. If it takes one argument, it's length is two, and so on. This method is called by JavaDoc to parse the options it does not recognize. It then calls {@link #validOptions(String[][], DocErrorReporter)} to validate them. Note:
The options arrive as case-sensitive strings. For options that are not case-sensitive, use toLowerCase() on the option string before comparing it.

return
number of arguments + 1 for a option. Zero return means option not known. Negative value means error occurred.

        option = option.toLowerCase();
        if (option.equals("-version") ||
            option.equals("-nodeprecated") ||
            option.equals("-author") ||
            option.equals("-xnodate")) {
            return 1;
        } else if (option.equals("-docencoding") ||
                   option.equals("-encoding") ||
                   option.equals("-sourcepath") ||
                   option.equals("-d")) {
            return 2;
        } else {
            return specificDocletOptionLength(option);
        }
public voidsetOptions(com.sun.javadoc.RootDoc root)
Set the command line options supported by this configuration.

param
root Root of the Program Structure generated by this Javadoc run.

        String[][] options = root.options();
        Configuration.root = root;
        packages = root.specifiedPackages();
        Arrays.sort(packages);
        for (int oi = 0; oi < options.length; ++oi) {
            String[] os = options[oi];
            String opt = os[0].toLowerCase();
            if (opt.equals("-d")) {
                destdirname = addTrailingFileSep(os[1]);
            } else  if (opt.equals("-docencoding")) {
                docencoding = os[1];
            } else  if (opt.equals("-encoding")) {
                encoding = os[1];
            } else  if (opt.equals("-author")) {
                showauthor = true;
            } else  if (opt.equals("-version")) {
                showversion = true;
            } else  if (opt.equals("-nodeprecated")) {
                nodeprecated = true;
            } else  if (opt.equals("-xnodate")) {
                nodate = true;
            } else  if (opt.equals("-sourcepath")) {
                sourcepath = os[1];
            } else if (opt.equals("-classpath") && 
                       sourcepath.length() == 0) {
                sourcepath = os[1];
            }
        }
        if (sourcepath.length() == 0) {
            sourcepath = System.getProperty("env.class.path");
        }
        if (docencoding == null) {
            docencoding = encoding;
        }

        HtmlDocWriter.configuration = this;
        setSpecificDocletOptions(root);
public abstract voidsetSpecificDocletOptions(com.sun.javadoc.RootDoc root)
This method should be defined in all those doclets(configurations), which want to derive themselves from this Configuration. This method can be used to set its own command line options.

param
root Root of the Program Structure generated by Javadoc.

public abstract intspecificDocletOptionLength(java.lang.String option)
This method should be defined in all those doclets
which want to inherit from this Configuration. This method
should return the number of arguments to the command line option.
This method is called by the method {@link #optionLength(String)}.
param
option Command line option under consideration.
return
number of arguments to option. Zero return means
option not known. Negative value means error occurred.
see
#optionLength(String)
public abstract booleanspecificDocletValidOptions(java.lang.String[][] option, com.sun.javadoc.DocErrorReporter reporter)
This method should be defined in all those doclets
which want to inherit from this Configuration. This method
can be used to check the validity of its own command line options.
This method is called by {@link #validOptions(String[][],
DocErrorReporter)}.
param
option Options-array from the Javadoc.
param
reporter Error reporter.
return
True if all the options are valid else false.
public booleanvalidOptions(java.lang.String[][] options, com.sun.javadoc.DocErrorReporter reporter)
After parsing the available options using {@link #optionLength(String)},
JavaDoc invokes this method with an array of options-arrays, where
the first item in any array is the option, and subsequent items in
that array are its arguments. So, if -print is an option that takes
no arguments, and -copies is an option that takes 1 argument, then

-print -copies 3


produces an array of arrays that looks like:

option[0][0] = -print
option[1][0] = -copies
option[1][1] = 3


(By convention, command line switches start with a "-", but
they don't have to.)
This method is not required to be written by sub-classes and will
default gracefully (to true) if absent.


Printing option related error messages (using the provided
DocErrorReporter) is the responsibility of this method.
param
options Options used on the command line.
param
reporter Error reporter to be used.
return
true if all the options are valid.
        boolean docencodingfound = false;
        String encoding = "";
        for (int oi = 0; oi < options.length; oi++) {
            String[] os = options[oi];
            String opt = os[0].toLowerCase();
            if (opt.equals("-d")) {
                destdirname = addTrailingFileSep(os[1]);
                File destDir = new File(destdirname);
                if (!destDir.exists()) {
                    reporter.printError(message.getText(
                        "doclet.destination_directory_not_found_0", 
                                                        destDir.getPath()));
                    return false;
                } else if (!destDir.isDirectory()) {
                    reporter.printError(message.getText(
                        "doclet.destination_directory_not_directory_0", 
                                                        destDir.getPath()));
                    return false;
                } else if (!destDir.canWrite()) {
                    reporter.printError(message.getText(
                        "doclet.destination_directory_not_writable_0", 
                                                        destDir.getPath()));
                    return false;
                }
            } else if (opt.equals("-docencoding")) {
                docencodingfound = true;
                if (!checkOutputFileEncoding(os[1], reporter)) {
                    return false;
                }
            } else if (opt.equals("-encoding")) {
                encoding = os[1];
            }
        }
        if (!docencodingfound && encoding.length() > 0) {
  	    if (!checkOutputFileEncoding(encoding, reporter)) {
                    return false;
            }
        }
        return specificDocletValidOptions(options, reporter);