net.sf.fikin.doclets
Class VelocityDoclet

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

public class VelocityDoclet
extends AbstractDoclet

Doclet interface backed by a Velocity engine

This is a generic class to support javadoc-like documents generated based on Velocity templates

It recognizes following Doclet options:

• -template which reflects template's file name or classpath resource name
• -file which reflects the output file name
• -velocitylog indicates that velocity log file is to be generated
is resolved to directory/template name

Velocity's resource loading is configured to search first for file, then for resource in the classpath and finally a file in jar-based url i.e.
resource.loader = file, class, jar

File resource loader is configured with current directory by default i.e. templates are searched in the sub-path of current only.
One can customize that though by setting the System property RESOURCE_PATH_PROP.

Jar resource loader is configured with empty list by default.
One can customize that though by setting the System property RESOURCE_JARS_PATH.

created on Sep 14, 2006

Since:

Version:

$Revision: 1.9 $

Author:

fiykov

Field Summary

protected java.io.File	outFile output file name, correspond to -d or -file options
static java.lang.String	RESOURCE_JARS_PATH system property which if set by the user specifies the actual jar files where Velocity templates are to be searched by JAR-template loader
static java.lang.String	RESOURCE_PATH_PROP system property which if set by the user specifies the actual file system paths where Velocity templates are to be searched by FILE-template loader
protected com.sun.javadoc.RootDoc	root the RootDoc object received by javadoc
protected java.lang.String	templateName template's name as defined by -template option
protected boolean	velocityLog do you want velocity.log or not?, correspond to -velocitylog option

Fields inherited from class net.sf.fikin.doclets.AbstractDoclet

docletOptions, parsedDocletOptions, singleton

Constructor Summary

VelocityDoclet()

Method Summary

protected boolean	checkIntegrity() check integrity of the internal properties
protected void	executeTemplate(org.apache.velocity.VelocityContext context, java.io.FileWriter out) instantiate the velocity template and "merge" it to output
protected void	initVelocity() initialize Velocity before creating the context
protected java.io.FileWriter	newOutput() create new output file
protected org.apache.velocity.VelocityContext	newVelocityContext() create new VelocityContext with proper initialization
static int	optionLength(java.lang.String option) maindatory in order to get this class static initialization happen
protected void	putTemplateObject(org.apache.velocity.VelocityContext context) set in the context all objects which will be visible in the template this implementation provides rooDoc is the RootDoc received from the Doclet systemProperties is a java.util.Hashtable obtained from java.lang.System.getProperties() tools is a TemplateTools object providing some usefull methods to deal with RootDoc operations
protected boolean	startCustom(com.sun.javadoc.RootDoc root) subclass specific method executes a velocity context with given template and produces the result to the given output file
protected boolean	validateOptionsCustom() subclass specific method seek for following options: "-d" option resulting in output file of the format "-d directory/-template file name" "-f" option used as output file "-template" used as input (velocity template) file

Methods inherited from class net.sf.fikin.doclets.AbstractDoclet

parseOptions, printUsage, prototypedOptionLength, prototypedStart, prototypedValidOptions, setSingleton, start, validOptions

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

RESOURCE_PATH_PROP

public static final java.lang.String RESOURCE_PATH_PROP

system property which if set by the user specifies the actual file system paths where Velocity templates are to be searched by FILE-template loader

See Also:

Constant Field Values

RESOURCE_JARS_PATH

public static final java.lang.String RESOURCE_JARS_PATH

system property which if set by the user specifies the actual jar files where Velocity templates are to be searched by JAR-template loader

See Also:

Constant Field Values

templateName

protected java.lang.String templateName

template's name as defined by -template option

outFile

protected java.io.File outFile

output file name, correspond to -d or -file options

velocityLog

protected boolean velocityLog

do you want velocity.log or not?, correspond to -velocitylog option

root

protected com.sun.javadoc.RootDoc root

the RootDoc object received by javadoc

Constructor Detail

VelocityDoclet

public VelocityDoclet()

Method Detail

optionLength

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

maindatory in order to get this class static initialization happen

startCustom

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

subclass specific method executes a velocity context with given template and produces the result to the given output file

Specified by:

startCustom in class AbstractDoclet

Parameters:

root -

Returns:

true if template execution was successfull, otherwise false

validateOptionsCustom

protected boolean validateOptionsCustom()

subclass specific method seek for following options:

• "-d" option resulting in output file of the format "-d directory/-template file name"
• "-f" option used as output file
• "-template" used as input (velocity template) file

Specified by:

validateOptionsCustom in class AbstractDoclet

Returns:

true if they are ok, otherwise false

newVelocityContext

protected org.apache.velocity.VelocityContext newVelocityContext()

create new VelocityContext with proper initialization

Returns:

new VelocityContext

initVelocity

protected void initVelocity()
                     throws java.lang.Exception

initialize Velocity before creating the context

Throws:

exception - during initialization

java.lang.Exception

putTemplateObject

protected void putTemplateObject(org.apache.velocity.VelocityContext context)

set in the context all objects which will be visible in the template this implementation provides

• rooDoc is the RootDoc received from the Doclet
• systemProperties is a java.util.Hashtable obtained from java.lang.System.getProperties()
• tools is a TemplateTools object providing some usefull methods to deal with RootDoc operations

Parameters:

context - to be used

executeTemplate

protected void executeTemplate(org.apache.velocity.VelocityContext context,
                               java.io.FileWriter out)
                        throws org.apache.velocity.exception.ResourceNotFoundException,
                               org.apache.velocity.exception.ParseErrorException,
                               org.apache.velocity.exception.MethodInvocationException,
                               java.lang.Exception

instantiate the velocity template and "merge" it to output

Parameters:

context - to be used

out - to be writen to

Throws:

org.apache.velocity.exception.ResourceNotFoundException

org.apache.velocity.exception.ParseErrorException

org.apache.velocity.exception.MethodInvocationException

java.lang.Exception

newOutput

protected java.io.FileWriter newOutput()
                                throws java.io.IOException

create new output file

Returns:

new output file

Throws:

java.io.IOException

checkIntegrity

protected boolean checkIntegrity()

check integrity of the internal properties

Returns:

true if everyhting is ok and template processing can continue, otherwise it is false