org.makumba.analyser
Class AnalysableTag

java.lang.Object
  javax.servlet.jsp.tagext.TagSupport
      org.makumba.analyser.AnalysableElement
          org.makumba.analyser.AnalysableTag

All Implemented Interfaces:

Serializable, IterationTag, JspTag, Tag

Direct Known Subclasses:

GenericMakumbaTag

public abstract class AnalysableTag
extends AnalysableElement

Extend this class in order to get analysis support for your tag.
Do make sure that:

• you make setters and getters for all the tag attributes
• if attributes should have default values, these should be set in the initialiseState(), not directly in the class
• you implement the setTagKey method so as to be able to retrieve TagData from the cache if you need it
• you use the doAnalyzedStartTag() and doAnalyzedEndTag() instead of doStartTag() and doEndTag() methods
• you cleanup all resources by overriding doAnalyzedCleanup(), without forgetting to call the super() method
• you correctly describe the behavior of the tag by overriding the canHaveBody() and allowsIdenticalKey()
• you check for the validity of attributes by overriding the registerPossibleAttributeValues() method, and registering possile attribute values using the registerAttributeValues(String attributeName, String... values) method.

Version:

$Id: AnalysableTag.java 5151 2010-05-18 19:07:27Z rosso_nero $

Author:

Cristian Bogdan, Manuel Gay

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.makumba.analyser.AnalysableElement

AnalysableElement.FilePositionElementComparator

Field Summary

static String[]	ATTRIBUTE_VALUES_TRUE_FALSE Commonly used Attribute values.
TagData	tagData The TagData object holding the composite data collected by the analysis.
MultipleKey	tagKey A tag key, used to find cached resources.
static String	TYPES Cache names, for PageCache of analysis

Fields inherited from class org.makumba.analyser.AnalysableElement

ANALYSIS_STATE

Fields inherited from class javax.servlet.jsp.tagext.TagSupport

id, pageContext

Fields inherited from interface javax.servlet.jsp.tagext.IterationTag

EVAL_BODY_AGAIN

Fields inherited from interface javax.servlet.jsp.tagext.Tag

EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE

Constructor Summary

AnalysableTag()

Method Summary

void	addTagText(StringBuffer sb) Dumps the tag line during analysis
boolean	allowsIdenticalKey() Determines whether the tag can have the same key as others in the page
boolean	canHaveBody() Determines whether this tag can have a body or not.
void	checkAttributeValues() Checks if the provided attribute values are correct.
protected void	doAnalyzedCleanup() Called by doEndTag in its finally block.
int	doAnalyzedEndTag(PageCache pageCache) makumba-specific endTag
int	doAnalyzedStartTag(PageCache pageCache) makumba-specific startTag.
void	doEndAnalyze(PageCache pageCache) End the analysis of the tag, after all tags in the page were visited.
int	doEndTag() Handles exceptions and calls doMakumbaEndTag()
void	doStartAnalyze(PageCache pageCache) Starts the analysis of the tag, without knowing what tags follow it in the page.
int	doStartTag() Handles exceptions, initialises state and calls doAnalyzedStartTag FIXME some of the exception handling should not be here
ElementData	getElementData()
PageContext	getPageContext()
String	getPageTextInfo() Prints the page data collected during analysis in readable format
MultipleKey	getTagKey() Gets the key that identifies this makumba tag
String	getTagText() Returns the declaration text of the tag parsed at analysis time
protected boolean	needPageCache() Checks if the tag needs the page cache
protected void	notEmpty(String attributeName, String value) Checks whether the given value is not blank, i.e. not null, and not an empty string or just contains whitespace, and throws a descriptive programmer error otherwise
protected void	onlyInt(String attributeName, String value) Checks whether the given value is of type integer, and throws a descriptive programmer error otherwise
protected void	registerAttributeValues(String attributeName, String... values) Registers one attribute and several possible values
protected void	registerPossibleAttributeValues() Override this in order to register possible attribute values using registerAttributeValues(String, String...).
void	setTagDataAtAnalysis(TagData tagData)
void	setTagKey(PageCache pageCache) Sets tagKey to uniquely identify this tag.

Methods inherited from class org.makumba.analyser.AnalysableElement

checkTagFound, discardJSPParsingData, getAnalyzedElementData, getCurrentBodyTagData, getElementAfter, getElementBefore, getPageCache, getPageCache, getRunningElementData, getTagByAttribute, getTagById, getThreadElementStack, initializeThread, keepAnalysisState, setAnalyzedElementData, setRunningElementData

Methods inherited from class javax.servlet.jsp.tagext.TagSupport

doAfterBody, findAncestorWithClass, getId, getParent, getValue, getValues, release, removeValue, setId, setPageContext, setParent, setValue

Methods inherited from class java.lang.Object

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

Field Detail

ATTRIBUTE_VALUES_TRUE_FALSE

public static final String[] ATTRIBUTE_VALUES_TRUE_FALSE

Commonly used Attribute values.

TYPES

public static final String TYPES

Cache names, for PageCache of analysis

See Also:

Constant Field Values

tagData

public TagData tagData

The TagData object holding the composite data collected by the analysis. It is set by the tag parser at analysis time. It is set at runtime after the key is computed

tagKey

public MultipleKey tagKey

A tag key, used to find cached resources. Computed by some tags, both at analysis and at runtime

Constructor Detail

AnalysableTag

public AnalysableTag()

Method Detail

getElementData

public ElementData getElementData()

Specified by:

getElementData in class AnalysableElement

setTagDataAtAnalysis

public void setTagDataAtAnalysis(TagData tagData)

addTagText

public void addTagText(StringBuffer sb)

Dumps the tag line during analysis

Parameters:

sb - StringBuffer holding the tag text

getTagText

public String getTagText()

Returns the declaration text of the tag parsed at analysis time

Returns:

A string containing the declaration of the tag

getPageContext

public PageContext getPageContext()

setTagKey

public void setTagKey(PageCache pageCache)

Sets tagKey to uniquely identify this tag. Called at analysis time before doStartAnalyze() and at runtime before doMakumbaStartTag()

Parameters:

pageCache - The page cache for the current page

See Also:

doAnalyzedStartTag(org.makumba.analyser.PageCache), doStartAnalyze(org.makumba.analyser.PageCache)

doStartAnalyze

public void doStartAnalyze(PageCache pageCache)

Starts the analysis of the tag, without knowing what tags follow it in the page. Typically this method will allocate initial data structures, that are then completed at doEndAnalyze()

Parameters:

pageCache - The page cache for the current page

doEndAnalyze

public void doEndAnalyze(PageCache pageCache)

End the analysis of the tag, after all tags in the page were visited.

Parameters:

pageCache - The page cache for the current page

getPageTextInfo

public String getPageTextInfo()

Prints the page data collected during analysis in readable format

Returns:

A String containing information about the page

doAnalyzedStartTag

public int doAnalyzedStartTag(PageCache pageCache)
                       throws LogicException,
                              JspException

makumba-specific startTag.

Parameters:

pageCache - The page cache for the current page

Throws:

LogicException

JspException

See Also:

doStartTag()

doAnalyzedEndTag

public int doAnalyzedEndTag(PageCache pageCache)
                     throws LogicException,
                            JspException

makumba-specific endTag

Parameters:

pageCache - The page cache for the current page

Throws:

LogicException

JspException

See Also:

doEndTag()

needPageCache

protected boolean needPageCache()

Checks if the tag needs the page cache

Returns:

true if page cache is needed, false otherwise

doStartTag

public int doStartTag()
               throws JspException

Handles exceptions, initialises state and calls doAnalyzedStartTag FIXME some of the exception handling should not be here

Specified by:

doStartTag in interface Tag

Overrides:

doStartTag in class TagSupport

Throws:

JspException

doEndTag

public int doEndTag()
             throws JspException

Handles exceptions and calls doMakumbaEndTag()

Specified by:

doEndTag in interface Tag

Overrides:

doEndTag in class TagSupport

Throws:

JspException

doAnalyzedCleanup

protected void doAnalyzedCleanup()

Called by doEndTag in its finally block. Use it to clean references that will not be used next time the servlet container uses the tag object.

getTagKey

public MultipleKey getTagKey()

Gets the key that identifies this makumba tag

Returns:

The MultipleKey used to identify the Makumba tag

allowsIdenticalKey

public boolean allowsIdenticalKey()

Determines whether the tag can have the same key as others in the page

Returns:

true if the tag is allowed to have the same key as others in the page, false otherwise

canHaveBody

public boolean canHaveBody()

Determines whether this tag can have a body or not.

Returns:

true if the tag is allowed to have a body, false otherwise

onlyInt

protected void onlyInt(String attributeName,
                       String value)

Checks whether the given value is of type integer, and throws a descriptive programmer error otherwise

notEmpty

protected void notEmpty(String attributeName,
                        String value)

Checks whether the given value is not blank, i.e. not null, and not an empty string or just contains whitespace, and throws a descriptive programmer error otherwise

registerPossibleAttributeValues

protected void registerPossibleAttributeValues()

Override this in order to register possible attribute values using registerAttributeValues(String, String...). The registered attributes are checked before doStartAnalyze(PageCache) and throw a ProgrammerError is thrown if the provided value is not allowed.

registerAttributeValues

protected final void registerAttributeValues(String attributeName,
                                             String... values)

Registers one attribute and several possible values

Parameters:

attributeName - the name of the attribute

values - a number of possible values the attribute can take

checkAttributeValues

public void checkAttributeValues()

Checks if the provided attribute values are correct. Called before doStartAnalyze(PageCache)