com.sun.tools.doclets.internal.toolkit
Class Configuration

java.lang.Object
  com.sun.tools.doclets.internal.toolkit.Configuration

Direct Known Subclasses:

ConfigurationImpl

public abstract class Configuration
extends java.lang.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. This code is not part of an API. It is implementation that is subject to change. Do not use it as an API

Field Summary

protected BuilderFactory	builderFactory The factory for builders.
java.lang.String	builderXMLPath The path to the builder XML input file.
java.lang.String	charset The META charset tag used for cross-platform viewing.
ClassDocCatalog	classDocCatalog The catalog of classes specified on the command-line
boolean	copydocfilesubdirs True if we should recursively copy the doc-file subdirectories
private static java.lang.String	DEFAULT_BUILDER_XML The default path to the builder XML.
java.lang.String	destDirName Destination directory name, in which doclet will generate the entire documentation.
java.lang.String	docencoding Encoding for this document.
java.lang.String	docFileDestDirName Destination directory name, in which doclet will copy the doc-files to.
java.lang.String	encoding Encoding for this document.
protected java.util.Set<java.lang.String>	excludedDocFileDirs The list of doc-file subdirectories to exclude
protected java.util.Set<java.lang.String>	excludedQualifiers The list of qualifiers to exclude
Extern	extern The tracker of external package links.
Group	group The package grouping instance.
boolean	keywords True if user wants to add member names as meta keywords.
boolean	linksource True if we should generate browsable sources.
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.
MetaKeywords	metakeywords The meta tag keywords instance.
boolean	nocomment True if user wants to suppress descriptions and tags.
boolean	nodeprecated Don't generate deprecated API information at all, if -nodeprecated option is used.
boolean	nosince True if command line option "-nosince" is used.
boolean	notimestamp True if user wants to suppress time stamp in output.
PackageDoc[]	packages An array of the packages specified on the command-line merged with the array of packages that contain the classes specified on the command-line.
RootDoc	root The Root of the generated Program Structure from the Doclet API.
boolean	serialwarn This is true if option "-serialwarn" is used.
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.
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.
java.lang.String	sourcepath Sourcepath from where to read the source files.
int	sourcetab The specified amount of space between tab stops.
TagletManager	tagletManager The taglet manager.
java.lang.String	tagletpath The path to Taglets

Constructor Summary

Configuration()
Constructor.

Method Summary

private void	addToSet(java.util.Set<java.lang.String> s, java.lang.String str)
(package private) java.lang.String	addTrailingFileSep(java.lang.String path) Add a traliling file separator, if not found or strip off extra trailing file separators if any.
private boolean	checkOutputFileEncoding(java.lang.String docencoding, DocErrorReporter reporter) Check the validity of the given Source or Output File encoding on this platform.
boolean	generalValidOptions(java.lang.String[][] options, DocErrorReporter reporter) This checks for the validity of the options used by the user.
BuilderFactory	getBuilderFactory() Return the builder factory for this doclet.
java.io.InputStream	getBuilderXML() Return the input stream to the builder XML.
java.lang.String	getClassName(ClassDoc cd) Return the qualified name of the ClassDoc if it's qualifier is not excluded.
abstract java.lang.String	getDocletSpecificBuildDate() Return the build date for the doclet.
abstract MessageRetriever	getDocletSpecificMsg() Return the doclet specific MessageRetriever
abstract java.util.Locale	getLocale() Return the Locale for this document.
abstract java.util.Comparator<ProgramElementDoc>	getMemberComparator() Return the comparator that will be used to sort member documentation.
java.lang.String	getText(java.lang.String key)
java.lang.String	getText(java.lang.String key, java.lang.String a1)
java.lang.String	getText(java.lang.String key, java.lang.String a1, java.lang.String a2)
java.lang.String	getText(java.lang.String key, java.lang.String a1, java.lang.String a2, java.lang.String a3)
abstract WriterFactory	getWriterFactory() Return the doclet specific instance of a writer factory.
private void	initPackageArray()
private void	initTagletManager(java.util.Set<java.lang.String[]> customTagStrs) Initialize the taglet manager.
boolean	isGeneratedDoc(Doc doc) Return true if the doc element is getting documented, depending upon -nodeprecated option and @deprecated tag used.
int	optionLength(java.lang.String option) This method should be defined in all those doclets which want to inherit from this Configuration.
void	setOptions() Set the command line options supported by this configuration.
void	setOptions(java.lang.String[][] options) Set the command line options supported by this configuration.
abstract void	setSpecificDocletOptions(java.lang.String[][] options) This method should be defined in all those doclets(configurations), which want to derive themselves from this Configuration.
boolean	shouldExcludeDocFileDir(java.lang.String docfilesubdir) Return true if the given doc-file subdirectory should be excluded and false otherwise.
boolean	shouldExcludeQualifier(java.lang.String qualifier) Return true if the given qualifier should be excluded and false otherwise.
abstract boolean	validOptions(java.lang.String[][] options, DocErrorReporter reporter) Perform error checking on the given options.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

builderFactory

protected BuilderFactory builderFactory

The factory for builders.

tagletManager

public TagletManager tagletManager

The taglet manager.

builderXMLPath

public java.lang.String builderXMLPath

The path to the builder XML input file.

DEFAULT_BUILDER_XML

private static final java.lang.String DEFAULT_BUILDER_XML

The default path to the builder XML.

See Also:

Constant Field Values

tagletpath

public java.lang.String tagletpath

The path to Taglets

serialwarn

public boolean serialwarn

This is true if option "-serialwarn" is used. Defualt value is false to supress excessive warnings about serial tag.

sourcetab

public int sourcetab

The specified amount of space between tab stops.

linksource

public boolean linksource

True if we should generate browsable sources.

nosince

public boolean nosince

True if command line option "-nosince" is used. Default value is false.

copydocfilesubdirs

public boolean copydocfilesubdirs

True if we should recursively copy the doc-file subdirectories

charset

public java.lang.String charset

The META charset tag used for cross-platform viewing.

keywords

public boolean keywords

True if user wants to add member names as meta keywords. Set to false because meta keywords are ignored in general by most Internet search engines.

metakeywords

public final MetaKeywords metakeywords

The meta tag keywords instance.

excludedDocFileDirs

protected java.util.Set<java.lang.String> excludedDocFileDirs

The list of doc-file subdirectories to exclude

excludedQualifiers

protected java.util.Set<java.lang.String> excludedQualifiers

The list of qualifiers to exclude

root

public RootDoc root

The Root of the generated Program Structure from the Doclet API.

destDirName

public java.lang.String destDirName

Destination directory name, in which doclet will generate the entire documentation. Default is current directory.

docFileDestDirName

public java.lang.String docFileDestDirName

Destination directory name, in which doclet will copy the doc-files to.

docencoding

public java.lang.String docencoding

Encoding for this document. Default is default encoding for this platform.

nocomment

public boolean nocomment

True if user wants to suppress descriptions and tags.

encoding

public java.lang.String encoding

Encoding for this document. Default is default encoding for this platform.

showauthor

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.

showversion

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.

sourcepath

public java.lang.String sourcepath

Sourcepath from where to read the source files. Default is classpath.

nodeprecated

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.

classDocCatalog

public ClassDocCatalog classDocCatalog

The catalog of classes specified on the command-line

message

public 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. TODO: Make this private!!!

notimestamp

public boolean notimestamp

True if user wants to suppress time stamp in output. Default is false.

group

public final Group group

The package grouping instance.

extern

public final Extern extern

The tracker of external package links.

packages

public PackageDoc[] packages

An array of the packages specified on the command-line merged with the array of packages that contain the classes specified on the command-line. The array is sorted.

Constructor Detail

Configuration

public Configuration()

Constructor. Constructs the message retriever with resource file.

Method Detail

getDocletSpecificBuildDate

public abstract java.lang.String getDocletSpecificBuildDate()

Return the build date for the doclet.

setSpecificDocletOptions

public abstract void setSpecificDocletOptions(java.lang.String[][] options)

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.

Parameters:

options - The array of option names and values.

Throws:

DocletAbortException

getDocletSpecificMsg

public abstract MessageRetriever getDocletSpecificMsg()

Return the doclet specific MessageRetriever

Returns:

the doclet specific MessageRetriever.

getBuilderFactory

public BuilderFactory getBuilderFactory()

Return the builder factory for this doclet.

Returns:

the builder factory for this doclet.

optionLength

public int optionLength(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 (including the option name). For example, -notimestamp is a single-argument option, so this method would return 1.

Parameters:

option - Command line option under consideration.

Returns:

number of arguments to option (including the option name). Zero return means option not known. Negative value means error occurred.

validOptions

public abstract boolean validOptions(java.lang.String[][] options,
                                     DocErrorReporter reporter)

Perform error checking on the given options.

Parameters:

options - the given options to check.

reporter - the reporter used to report errors.

initPackageArray

private void initPackageArray()

setOptions

public void setOptions(java.lang.String[][] options)

Set the command line options supported by this configuration.

Parameters:

options - the two dimensional array of options.

setOptions

public void setOptions()

Set the command line options supported by this configuration.

Throws:

DocletAbortException

initTagletManager

private void initTagletManager(java.util.Set<java.lang.String[]> customTagStrs)

Initialize the taglet manager. The strings to initialize the simple custom tags should be in the following format: "[tag name]:[location str]:[heading]".

Parameters:

customTagStrs - the set two dimentional arrays of strings. These arrays contain either -tag or -taglet arguments.

addToSet

private void addToSet(java.util.Set<java.lang.String> s,
                      java.lang.String str)

addTrailingFileSep

java.lang.String addTrailingFileSep(java.lang.String path)

Add a traliling file separator, if not found or strip off extra trailing file separators if any.

Parameters:

path - Path under consideration.

Returns:

String Properly constructed path string.

generalValidOptions

public boolean generalValidOptions(java.lang.String[][] options,
                                   DocErrorReporter reporter)

This checks for the validity of the options used by the user. This works exactly like Doclet.validOptions(String[][], DocErrorReporter). This will validate the options which are shared by our doclets. For example, this method will flag an error using the DocErrorReporter if user has used "-nohelp" and "-helpfile" option together.

Parameters:

options - options used on the command line.

reporter - used to report errors.

Returns:

true if all the options are valid.

checkOutputFileEncoding

private boolean checkOutputFileEncoding(java.lang.String docencoding,
                                        DocErrorReporter reporter)

Check the validity of the given Source or Output File encoding on this platform.

Parameters:

docencoding - output file encoding.

reporter - used to report errors.

shouldExcludeDocFileDir

public boolean shouldExcludeDocFileDir(java.lang.String docfilesubdir)

Return true if the given doc-file subdirectory should be excluded and false otherwise.

Parameters:

docfilesubdir - the doc-files subdirectory to check.

shouldExcludeQualifier

public boolean shouldExcludeQualifier(java.lang.String qualifier)

Return true if the given qualifier should be excluded and false otherwise.

Parameters:

qualifier - the qualifier to check.

getClassName

public java.lang.String getClassName(ClassDoc cd)

Return the qualified name of the ClassDoc if it's qualifier is not excluded. Otherwise, return the unqualified ClassDoc name.

Parameters:

cd - the ClassDoc to check.

getText

public java.lang.String getText(java.lang.String key)

getText

public java.lang.String getText(java.lang.String key,
                                java.lang.String a1)

getText

public java.lang.String getText(java.lang.String key,
                                java.lang.String a1,
                                java.lang.String a2)

getText

public java.lang.String getText(java.lang.String key,
                                java.lang.String a1,
                                java.lang.String a2,
                                java.lang.String a3)

isGeneratedDoc

public boolean isGeneratedDoc(Doc doc)

Return true if the doc element is getting documented, depending upon -nodeprecated option and @deprecated tag used. Return true if -nodeprecated is not used or @deprecated tag is not used.

getWriterFactory

public abstract WriterFactory getWriterFactory()

Return the doclet specific instance of a writer factory.

Returns:

the WriterFactory for the doclet.

getBuilderXML

public java.io.InputStream getBuilderXML()
                                  throws java.io.FileNotFoundException

Return the input stream to the builder XML.

Returns:

the input steam to the builder XML.

Throws:

java.io.FileNotFoundException - when the given XML file cannot be found.

getLocale

public abstract java.util.Locale getLocale()

Return the Locale for this document.

getMemberComparator

public abstract java.util.Comparator<ProgramElementDoc> getMemberComparator()

Return the comparator that will be used to sort member documentation. To no do any sorting, return null.

Returns:

the Comparator used to sort members.