xdoclet
Class XDocletTagSupport

java.lang.Object
  |
  +--xdoclet.template.TemplateTagHandler
        |
        +--xdoclet.XDocletTagSupport

Direct Known Subclasses:

AbstractProgramElementTagsHandler, CommentTagsHandler, ConfigTagsHandler, DocumentationTagsHandler, EjbTagsHandler, IdTagsHandler, InfoTagsHandler, MergeTagsHandler, TagDefTagsHandler, TranslatorTagsHandler, TypeTagsHandler, WebWorkTagsHandler, XmlTagsHandler

public abstract class XDocletTagSupport

extends TemplateTagHandler

Derives from TemplateTagHandler and adds handy support methods for working with Javadoc Doclet classes.

Version:

$Revision: 1.24 $

Author:

Dmitri Colebatch (dim@bigpond.net.au)

Field Summary

static int	FOR_CLASS
static int	FOR_CONSTRUCTOR
static int	FOR_FIELD
static int	FOR_METHOD
protected static java.lang.String	PARAMETER_DELIMITER Default delimiter used inside a xdoclet tag attribute.

Constructor Summary

XDocletTagSupport()

Method Summary

static java.lang.String	getClassTagValue(com.sun.javadoc.ClassDoc clazz, java.lang.String tag_name, java.lang.String param_name, int param_num, java.lang.String valid_values, java.lang.String default_value, boolean superclasses, boolean is_mandatory) For classes.
java.lang.String	getClassTagValue(java.lang.String tag_name, java.lang.String param_name, int param_num, java.lang.String valid_values, java.lang.String default_value, boolean superclasses, boolean is_mandatory) For classes.
protected static java.lang.String	getConstructorTagValue(com.sun.javadoc.ConstructorDoc constructor, java.lang.String tag_name, java.lang.String param_name, int param_num, java.lang.String valid_values, java.lang.String default_value, boolean is_mandatory) For constructors.
static com.sun.javadoc.ClassDoc	getCurrentClass() Provides the current class in the XDoclet build, or null if there is no current class.
static com.sun.javadoc.ConstructorDoc	getCurrentConstructor() Provides the current constructor in the XDoclet build, or null if there is no current constructor.
static com.sun.javadoc.FieldDoc	getCurrentField() Provides the current field in the XDoclet build, or null if there is no current field.
static com.sun.javadoc.MethodDoc	getCurrentMethod() Provides the current method in the XDoclet build, or null if there is no current method.
static com.sun.javadoc.PackageDoc	getCurrentPackage() Provides the current package in the XDoclet build, or null if there is no current package.
static com.sun.javadoc.Tag	getCurrentTag()
protected static DocletContext	getDocletContext()
protected static java.lang.String	getFieldTagValue(com.sun.javadoc.FieldDoc field, java.lang.String tag_name, java.lang.String param_name, int param_num, java.lang.String valid_values, java.lang.String default_value, boolean is_mandatory) For fields.
protected java.lang.String	getFieldTagValue(java.lang.String tag_name, java.lang.String param_name, int param_num, java.lang.String valid_values, java.lang.String default_value, boolean is_mandatory) For fields.
protected static java.lang.String	getMethodTagValue(com.sun.javadoc.MethodDoc method, java.lang.String tag_name, java.lang.String param_name, int param_num, java.lang.String valid_values, java.lang.String default_value, boolean is_mandatory) For methods.
protected java.lang.String	getMethodTagValue(java.lang.String tag_name, java.lang.String param_name, int param_num, java.lang.String valid_values, java.lang.String default_value, boolean is_mandatory) For methods.
static java.lang.String	getParameterValue(com.sun.javadoc.ClassDoc clazz, java.lang.String value, java.lang.String param_name, int param_num) Given the raw javadoc tag content as the value parameter parses it and searches for the specified parameter and if found returns its value, null otherwise.
protected java.lang.String	getParameterValue(java.lang.String value, java.lang.String param_name, int param_num) Parses and searches the value string for the parameter named param_name and returns its value.
protected static java.lang.String	getTagValue(com.sun.javadoc.ProgramElementDoc prg_elem_doc, java.lang.String tag_name, java.lang.String param_name, int param_num, java.lang.String valid_values, java.lang.String default_value, java.lang.String tn, java.lang.String delimiter, java.lang.String return_delimiters, boolean superclasses, int for_type, boolean is_mandatory)
protected java.lang.String	getTagValue(java.util.Properties attributes, int for_type) Return the Value of a tag specified in a Properties object.
protected java.lang.String	getTagValue(java.lang.String tag_name, java.lang.String param_name, int param_num, java.lang.String valid_values, java.lang.String default_value, java.lang.String tn, java.lang.String delimiter, java.lang.String return_delimiters, boolean superclasses, int for_type, boolean is_mandatory)
protected static void	invalidParamValueFound(com.sun.javadoc.ProgramElementDoc prg_elem_doc, java.lang.String param_name, java.lang.String tag_name, java.lang.String value, java.lang.String valid_values) Throws an XDocletException exception to stop the build process.
protected static void	mandatoryParamNotFound(com.sun.javadoc.ProgramElementDoc prg_elem_doc, java.lang.String param_name, java.lang.String tag_name) Throws an XDocletException exception to stop the build process.
protected void	mandatoryTemplateTagParamNotFound(java.lang.String template_tag_name, java.lang.String param_name)
static void	parsePropertyString(java.lang.String value, java.util.Vector fragments, java.util.Vector propertyRefs) Parses a string containing ${xxx} style property references into two lists.
static com.sun.javadoc.ClassDoc	popCurrentClass() Pop the current class off the top of the class stack.
static com.sun.javadoc.ClassDoc	pushCurrentClass(com.sun.javadoc.ClassDoc clazz) Push the specified class to the top of the current class stack making it effectively the current class.
static java.lang.String	replaceProperties(java.lang.String value, java.util.Map keys) Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types.
static void	setCurrentClass(com.sun.javadoc.ClassDoc clazz) Sets current class to clazz by clearing currentClassStack stack and pushing clazz into top of it.
static void	setCurrentConstructor(com.sun.javadoc.ConstructorDoc constructor) Set the current constructor.
static void	setCurrentField(com.sun.javadoc.FieldDoc field) Set the current field.
static void	setCurrentMethod(com.sun.javadoc.MethodDoc method) Set the current method.
static void	setCurrentPackage(com.sun.javadoc.PackageDoc pakkage) Set the current package
static void	setCurrentTag(com.sun.javadoc.Tag currentTag)
protected static java.lang.String	tokenizeValue(java.lang.String value, java.lang.String tn, java.lang.String delimiter, java.lang.String return_delimiters) Uses tokenNumber and delimiter to tokenize value and returns desired token

Methods inherited from class xdoclet.template.TemplateTagHandler

generate, getContext, getEngine, getParser, setContext, setEngine, setParser

Methods inherited from class java.lang.Object

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

Field Detail

FOR_CLASS

public static final int FOR_CLASS

FOR_METHOD

public static final int FOR_METHOD

FOR_FIELD

public static final int FOR_FIELD

FOR_CONSTRUCTOR

public static final int FOR_CONSTRUCTOR

PARAMETER_DELIMITER

protected static final java.lang.String PARAMETER_DELIMITER

Default delimiter used inside a xdoclet tag attribute.

Constructor Detail

XDocletTagSupport

public XDocletTagSupport()

Method Detail

getParameterValue

public static java.lang.String getParameterValue(com.sun.javadoc.ClassDoc clazz,
                                                 java.lang.String value,
                                                 java.lang.String param_name,
                                                 int param_num)
                                          throws XDocletException

Given the raw javadoc tag content as the value parameter parses it and searches for the specified parameter and if found returns its value, null otherwise.

Parameters:

clazz -

value -

param_name -

param_num -

Returns:

The parameter value; null if not found

Throws:

XDocletException -

getCurrentTag

public static com.sun.javadoc.Tag getCurrentTag()

Returns:

The current tag.

getClassTagValue

public static java.lang.String getClassTagValue(com.sun.javadoc.ClassDoc clazz,
                                                java.lang.String tag_name,
                                                java.lang.String param_name,
                                                int param_num,
                                                java.lang.String valid_values,
                                                java.lang.String default_value,
                                                boolean superclasses,
                                                boolean is_mandatory)
                                         throws XDocletException

For classes.

Parameters:

tag_name - Description of Parameter

param_name - Description of Parameter

param_num - Description of Parameter

valid_values - Description of Parameter

default_value - Description of Parameter

superclasses - Description of Parameter

is_mandatory - Description of Parameter

clazz - Description of Parameter

Returns:

The ClassTagValue value

Throws:

XDocletException - Description of Exception

getCurrentMethod

public static com.sun.javadoc.MethodDoc getCurrentMethod()

Provides the current method in the XDoclet build, or null if there is no current method.

Returns:

The CurrentMethod value

See Also:

setCurrentMethod(com.sun.javadoc.MethodDoc)

getCurrentField

public static com.sun.javadoc.FieldDoc getCurrentField()

Provides the current field in the XDoclet build, or null if there is no current field.

Returns:

The CurrentField value

See Also:

setCurrentField(com.sun.javadoc.FieldDoc)

getCurrentConstructor

public static com.sun.javadoc.ConstructorDoc getCurrentConstructor()

Provides the current constructor in the XDoclet build, or null if there is no current constructor.

Returns:

The CurrentConstructor value

See Also:

setCurrentConstructor(com.sun.javadoc.ConstructorDoc)

getCurrentClass

public static com.sun.javadoc.ClassDoc getCurrentClass()

Provides the current class in the XDoclet build, or null if there is no current class.

Returns:

The CurrentClass value

See Also:

pushCurrentClass(com.sun.javadoc.ClassDoc), popCurrentClass()

getCurrentPackage

public static com.sun.javadoc.PackageDoc getCurrentPackage()

Provides the current package in the XDoclet build, or null if there is no current package.

Returns:

The CurrentPackage value

setCurrentMethod

public static void setCurrentMethod(com.sun.javadoc.MethodDoc method)

Set the current method.

Parameters:

method - The method to make the current method

See Also:

getCurrentMethod()

setCurrentConstructor

public static void setCurrentConstructor(com.sun.javadoc.ConstructorDoc constructor)

Set the current constructor.

Parameters:

constructor - The constructor to make the current constructor

See Also:

getCurrentConstructor()

setCurrentClass

public static void setCurrentClass(com.sun.javadoc.ClassDoc clazz)

Sets current class to clazz by clearing currentClassStack stack and pushing clazz into top of it.

Parameters:

clazz - The new CurrentClass value

See Also:

getCurrentClass()

setCurrentPackage

public static void setCurrentPackage(com.sun.javadoc.PackageDoc pakkage)

Set the current package

Parameters:

pakkage - The new CurrentPackage value

See Also:

getCurrentPackage()

setCurrentTag

public static void setCurrentTag(com.sun.javadoc.Tag currentTag)

setCurrentField

public static void setCurrentField(com.sun.javadoc.FieldDoc field)

Set the current field.

Parameters:

field - The field to make the current field

See Also:

getCurrentMethod()

replaceProperties

public static java.lang.String replaceProperties(java.lang.String value,
                                                 java.util.Map keys)

Replaces ${xxx} style constructions in the given value with the string value of the corresponding data types. NOTE: This method was taken directly from Ant's source code (org.apache.tools.ant.ProjectHelper) and modified slightly to use a Map instead of a Hashtable.

Parameters:

value - The string to be scanned for property references. May be null, in which case this method returns immediately with no effect.

keys - Mapping (String to String) of property names to their values. Must not be null.

Returns:

the original string with the properties replaced, or null if the original string is null.

parsePropertyString

public static void parsePropertyString(java.lang.String value,
                                       java.util.Vector fragments,
                                       java.util.Vector propertyRefs)

Parses a string containing ${xxx} style property references into two lists. The first list is a collection of text fragments, while the other is a set of string property names. null entries in the first list indicate a property reference from the second list. NOTE: This method was taken directly from Ant's source code (org.apache.tools.ant.ProjectHelper) with the BuildException throwing removed.

Parameters:

value - Text to parse. Must not be null.

fragments - List to add text fragments to. Must not be null .

propertyRefs - List to add property names to. Must not be null .

pushCurrentClass

public static com.sun.javadoc.ClassDoc pushCurrentClass(com.sun.javadoc.ClassDoc clazz)

Push the specified class to the top of the current class stack making it effectively the current class.

Parameters:

clazz - The class to push onto the top of the class stack.

Returns:

The class on the top of the stack.

See Also:

getCurrentClass(), popCurrentClass()

popCurrentClass

public static com.sun.javadoc.ClassDoc popCurrentClass()

Pop the current class off the top of the class stack.

Returns:

The class popped off the top of the stack.

See Also:

getCurrentClass(), pushCurrentClass(com.sun.javadoc.ClassDoc)

getDocletContext

protected static DocletContext getDocletContext()

Returns:

the context object casted to DocletContext

getTagValue

protected static java.lang.String getTagValue(com.sun.javadoc.ProgramElementDoc prg_elem_doc,
                                              java.lang.String tag_name,
                                              java.lang.String param_name,
                                              int param_num,
                                              java.lang.String valid_values,
                                              java.lang.String default_value,
                                              java.lang.String tn,
                                              java.lang.String delimiter,
                                              java.lang.String return_delimiters,
                                              boolean superclasses,
                                              int for_type,
                                              boolean is_mandatory)
                                       throws XDocletException

getMethodTagValue

protected static java.lang.String getMethodTagValue(com.sun.javadoc.MethodDoc method,
                                                    java.lang.String tag_name,
                                                    java.lang.String param_name,
                                                    int param_num,
                                                    java.lang.String valid_values,
                                                    java.lang.String default_value,
                                                    boolean is_mandatory)
                                             throws XDocletException

For methods.

Parameters:

tag_name - Description of Parameter

param_name - Description of Parameter

param_num - Description of Parameter

valid_values - Description of Parameter

default_value - Description of Parameter

is_mandatory - Description of Parameter

method - Description of Parameter

Returns:

The MethodTagValue value

Throws:

XDocletException - Description of Exception

getFieldTagValue

protected static java.lang.String getFieldTagValue(com.sun.javadoc.FieldDoc field,
                                                   java.lang.String tag_name,
                                                   java.lang.String param_name,
                                                   int param_num,
                                                   java.lang.String valid_values,
                                                   java.lang.String default_value,
                                                   boolean is_mandatory)
                                            throws XDocletException

For fields.

Parameters:

tag_name - Description of Parameter

param_name - Description of Parameter

param_num - Description of Parameter

valid_values - Description of Parameter

default_value - Description of Parameter

is_mandatory - Description of Parameter

field - Description of Parameter

Returns:

The MethodTagValue value

Throws:

XDocletException - Description of Exception

getConstructorTagValue

protected static java.lang.String getConstructorTagValue(com.sun.javadoc.ConstructorDoc constructor,
                                                         java.lang.String tag_name,
                                                         java.lang.String param_name,
                                                         int param_num,
                                                         java.lang.String valid_values,
                                                         java.lang.String default_value,
                                                         boolean is_mandatory)
                                                  throws XDocletException

For constructors.

Parameters:

tag_name - Description of Parameter

param_name - Description of Parameter

param_num - Description of Parameter

valid_values - Description of Parameter

default_value - Description of Parameter

is_mandatory - Description of Parameter

constructor - Description of Parameter

Returns:

The ConstructorTagValue value

Throws:

XDocletException - Description of Exception

tokenizeValue

protected static java.lang.String tokenizeValue(java.lang.String value,
                                                java.lang.String tn,
                                                java.lang.String delimiter,
                                                java.lang.String return_delimiters)

Uses tokenNumber and delimiter to tokenize value and returns desired token

Parameters:

value - Description of Parameter

tn - Description of Parameter

delimiter - Description of Parameter

return_delimiters - Description of Parameter

Returns:

Description of the Returned Value

mandatoryParamNotFound

protected static void mandatoryParamNotFound(com.sun.javadoc.ProgramElementDoc prg_elem_doc,
                                             java.lang.String param_name,
                                             java.lang.String tag_name)
                                      throws XDocletException

Throws an XDocletException exception to stop the build process. The exception has an informative message to help user find out the cause of the error (not specifying a mandatory parameter for a tag).

Parameters:

param_name - Description of Parameter

tag_name - Description of Parameter

prg_elem_doc - Description of Parameter

Throws:

XDocletException - Description of Exception

invalidParamValueFound

protected static void invalidParamValueFound(com.sun.javadoc.ProgramElementDoc prg_elem_doc,
                                             java.lang.String param_name,
                                             java.lang.String tag_name,
                                             java.lang.String value,
                                             java.lang.String valid_values)
                                      throws XDocletException

Throws an XDocletException exception to stop the build process. The exception has an informative message to help user find out the cause of the error (specifying an incorrect value for a parameter of a tag).

Parameters:

param_name - Description of Parameter

tag_name - Description of Parameter

value - Description of Parameter

valid_values - Description of Parameter

prg_elem_doc - Description of Parameter

Throws:

XDocletException - Description of Exception

getClassTagValue

public java.lang.String getClassTagValue(java.lang.String tag_name,
                                         java.lang.String param_name,
                                         int param_num,
                                         java.lang.String valid_values,
                                         java.lang.String default_value,
                                         boolean superclasses,
                                         boolean is_mandatory)
                                  throws XDocletException

For classes.

Parameters:

tag_name - Description of Parameter

param_name - Description of Parameter

param_num - Description of Parameter

valid_values - Description of Parameter

default_value - Description of Parameter

superclasses - Description of Parameter

is_mandatory - Description of Parameter

Returns:

The ClassTagValue value

Throws:

XDocletException - Description of Exception

getParameterValue

protected java.lang.String getParameterValue(java.lang.String value,
                                             java.lang.String param_name,
                                             int param_num)
                                      throws XDocletException

Parses and searches the value string for the parameter named param_name and returns its value. Parameters are in name="value" format or if param_num specified then can also be in space=separated format, which are used in cases where the tag has only a single parameter.

Parameters:

value - Description of Parameter

param_name - Description of Parameter

param_num - Description of Parameter

Returns:

The ParameterValue value

Throws:

XDocletException - Description of Exception

getTagValue

protected java.lang.String getTagValue(java.util.Properties attributes,
                                       int for_type)
                                throws XDocletException

Return the Value of a tag specified in a Properties object. This method work on the currentTag object variable, matchs it against the Tag specified in the attributes Properties and returns the value of the specified tag. This method is used by various tag implementations, specially classTagValue and methodTagValue.

Parameters:

attributes - The attributes of the template tag

for_type - if FOR_CLASS, then a fifth property superclasses is searched, if this is set to true, then the tag is also searched in all superclasses of current class. If for_type is set to FOR_METHOD or FOR_CONSTRUCTOR or FOR_FIELD, current method or field is searched for the tag.

Returns:

The TagValue value

Throws:

XDocletException - Description of Exception

getMethodTagValue

protected java.lang.String getMethodTagValue(java.lang.String tag_name,
                                             java.lang.String param_name,
                                             int param_num,
                                             java.lang.String valid_values,
                                             java.lang.String default_value,
                                             boolean is_mandatory)
                                      throws XDocletException

For methods.

Parameters:

tag_name - Description of Parameter

param_name - Description of Parameter

param_num - Description of Parameter

valid_values - Description of Parameter

default_value - Description of Parameter

is_mandatory - Description of Parameter

Returns:

The MethodTagValue value

Throws:

XDocletException - Description of Exception

getFieldTagValue

protected java.lang.String getFieldTagValue(java.lang.String tag_name,
                                            java.lang.String param_name,
                                            int param_num,
                                            java.lang.String valid_values,
                                            java.lang.String default_value,
                                            boolean is_mandatory)
                                     throws XDocletException

For fields.

Parameters:

tag_name - Description of Parameter

param_name - Description of Parameter

param_num - Description of Parameter

valid_values - Description of Parameter

default_value - Description of Parameter

is_mandatory - Description of Parameter

Returns:

The MethodTagValue value

Throws:

XDocletException - Description of Exception

getTagValue

protected java.lang.String getTagValue(java.lang.String tag_name,
                                       java.lang.String param_name,
                                       int param_num,
                                       java.lang.String valid_values,
                                       java.lang.String default_value,
                                       java.lang.String tn,
                                       java.lang.String delimiter,
                                       java.lang.String return_delimiters,
                                       boolean superclasses,
                                       int for_type,
                                       boolean is_mandatory)
                                throws XDocletException

mandatoryTemplateTagParamNotFound

protected void mandatoryTemplateTagParamNotFound(java.lang.String template_tag_name,
                                                 java.lang.String param_name)
                                          throws XDocletException

Parameters:

template_tag_name -

param_name -

Throws:

XDocletException -