net.sf.fikin.doclets
Class AbstractDoclet

java.lang.Object
  com.sun.javadoc.Doclet
      net.sf.fikin.doclets.AbstractDoclet

Direct Known Subclasses:

VelocityDoclet

public abstract class AbstractDoclet
extends com.sun.javadoc.Doclet

Base class for all specific purpose Doclets

It was designed in order to help develop on top of original Sun's design

It does following thinks:

• Provides with skeleton implementation for all Doclet static methods. They are doing commandline validation and decide to call startCustom(RootDoc) or printUsage(DocErrorReporter) respectively
• Makes a transition from Doclet static methods calls to singleton based. This way subclasses can overwrite instance methods and still get properly executed. Overloading can be done for startCustom(RootDoc) and validateOptionsCustom()
• Provides with Commons Logging logging facility, usefull in testing situations
• Commandline parameter parsing is based on Commons CLI library. Subclasses can add new supported options in class constructor

Eamples: A minimalistic custom doclet

      public class TestDoclet extends AbstractDoclet {
      
          // set the singleton to this one
          static {
              setSingleton( new TestDoclet() );
          }
      
          public TestDoclet() {
              // add here your own Doclet options
              docletOptions.addOption( "file",true,"destination file to be generated");
              ...
          }
          
          // following you have to do because static methods does not have inheritance
          public static int optionLength(String option) {
              return AbstractDoclet.optionLength( option );
          }
          
          // implement commandline options validation
          // to ensure mandatory options have been specified
          protected boolean validateOptionsCustom() {
              if ( ! parsedDocletOptions.hasOption( "template" ) ) {
                  return false;
              }
          }
          
          // implement your actual doclet logic
          protected boolean startCustom(RootDoc root) {
              ...
          }
            
      }
 

created on Aug 9, 2006

Since:

Version:

$Revision: 1.7 $

Author:

fiykov

Field Summary

protected org.apache.commons.cli.Options	docletOptions supported doclet options, subclasses are supposed to add their specific options (if any)
protected org.apache.commons.cli.CommandLine	parsedDocletOptions parsed doclet options passed to the doclet
protected static AbstractDoclet	singleton singleton instance of this doclet, all static calls are delegated to this one object subclasses are responsible to assign a valid instance during construction time

Constructor Summary

AbstractDoclet()
define Doclet's common options

Method Summary

static int	optionLength(java.lang.String option) determine supported options length by delegating it to prototypedOptionLength(String) Expects the singleton to be assigned already.
protected boolean	parseOptions(java.lang.String[][] options) parse dolet's parameters parsing is based on Apache's Commons CLI BasicParser and uses the options defined in docletOptions.
protected void	printUsage(com.sun.javadoc.DocErrorReporter reporter) print javadoc usage, in this case it is predefined -d and -f options
int	prototypedOptionLength(java.lang.String option) prototype method test the given option's length against options defined by docletOptions
boolean	prototypedStart(com.sun.javadoc.RootDoc root) prototype method parses the options via parseOptions(String[][]) and if that part is ok then validates them via validateOptionsCustom() and if that also part is ok then executes startCustom(RootDoc)
boolean	prototypedValidOptions(java.lang.String[][] options, com.sun.javadoc.DocErrorReporter reporter) prototype method.
protected static void	setSingleton(AbstractDoclet doclet) assign the singleton refernce to given doclet object this is method is to be called by the subclass "static" constructor
static boolean	start(com.sun.javadoc.RootDoc root) Generate output file by delegating it to prototypedStart(RootDoc) Expects the singleton to be assigned already.
protected abstract boolean	startCustom(com.sun.javadoc.RootDoc root) subclass specific method provides actual doclet's business logic once actual start(RootDoc) logic only instance dependant to be implented by the subclass
protected abstract boolean	validateOptionsCustom() subclass specific method provides with subclass secific validation for command line options (common ones have been taken care by AbstractDoclet already) check that parsedDocletOptions are valid i.e.
static boolean	validOptions(java.lang.String[][] options, com.sun.javadoc.DocErrorReporter reporter) validate options by delegating it to prototypedValidOptions(String[][],DocErrorReporter) Expects the singleton to be assigned already.

Methods inherited from class com.sun.javadoc.Doclet

languageVersion

Methods inherited from class java.lang.Object

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

Field Detail

docletOptions

protected org.apache.commons.cli.Options docletOptions

supported doclet options, subclasses are supposed to add their specific options (if any)

parsedDocletOptions

protected org.apache.commons.cli.CommandLine parsedDocletOptions

parsed doclet options passed to the doclet

singleton

protected static AbstractDoclet singleton

singleton instance of this doclet, all static calls are delegated to this one object subclasses are responsible to assign a valid instance during construction time

Constructor Detail

AbstractDoclet

public AbstractDoclet()

define Doclet's common options

Method Detail

start

public static boolean start(com.sun.javadoc.RootDoc root)

Generate output file by delegating it to prototypedStart(RootDoc) Expects the singleton to be assigned already.

Returns:

true on success.

validOptions

public static boolean validOptions(java.lang.String[][] options,
                                   com.sun.javadoc.DocErrorReporter reporter)

validate options by delegating it to prototypedValidOptions(String[][],DocErrorReporter) Expects the singleton to be assigned already.

optionLength

public static int optionLength(java.lang.String option)

determine supported options length by delegating it to prototypedOptionLength(String) Expects the singleton to be assigned already.

prototypedStart

public boolean prototypedStart(com.sun.javadoc.RootDoc root)

prototype method parses the options via parseOptions(String[][]) and if that part is ok then validates them via validateOptionsCustom() and if that also part is ok then executes startCustom(RootDoc)

Returns:

true if all thse checks when fine, otherwise false

prototypedOptionLength

public int prototypedOptionLength(java.lang.String option)

prototype method test the given option's length against options defined by docletOptions

Parameters:

option - to check

Returns:

option's length if exists, or 0 if option does not exists

prototypedValidOptions

public boolean prototypedValidOptions(java.lang.String[][] options,
                                      com.sun.javadoc.DocErrorReporter reporter)

prototype method. parses the options via parseOptions(String[][]) and if that part is ok then validates them via validateOptionsCustom(). prints usage via printUsage(DocErrorReporter) if some of the checks failed.

Returns:

true if the two checks when fine, otherwise false

setSingleton

protected static void setSingleton(AbstractDoclet doclet)

assign the singleton refernce to given doclet object this is method is to be called by the subclass "static" constructor

Parameters:

doclet - is an instance of the concrete subclass

parseOptions

protected boolean parseOptions(java.lang.String[][] options)

parse dolet's parameters parsing is based on Apache's Commons CLI BasicParser and uses the options defined in docletOptions.

Parameters:

options -

Returns:

true if given option is recognied, false in case options are empty or not recognized

printUsage

protected void printUsage(com.sun.javadoc.DocErrorReporter reporter)

print javadoc usage, in this case it is predefined -d and -f options

startCustom

protected abstract boolean startCustom(com.sun.javadoc.RootDoc root)

subclass specific method provides actual doclet's business logic once actual start(RootDoc) logic only instance dependant to be implented by the subclass

Parameters:

root -

Returns:

true if parsing was successfull, otherwise false

validateOptionsCustom

protected abstract boolean validateOptionsCustom()

subclass specific method provides with subclass secific validation for command line options (common ones have been taken care by AbstractDoclet already) check that parsedDocletOptions are valid i.e. mandatory options are present and etc.

Returns:

true if they are ok, otherwise false