com.devsphere.xml.taglib.support.tag
Class CommonSupport

java.lang.Object
  |
  +--javax.servlet.jsp.tagext.TagSupport
        |
        +--javax.servlet.jsp.tagext.BodyTagSupport
              |
              +--com.devsphere.xml.taglib.support.tag.CommonSupport

All Implemented Interfaces:

javax.servlet.jsp.tagext.BodyTag, javax.servlet.jsp.tagext.IterationTag, java.io.Serializable, javax.servlet.jsp.tagext.Tag, javax.servlet.jsp.tagext.TryCatchFinally

Direct Known Subclasses:

OutputSupport, ProcessSupport

public abstract class CommonSupport

extends javax.servlet.jsp.tagext.BodyTagSupport

implements javax.servlet.jsp.tagext.TryCatchFinally

This class provides support for custom tag handlers and is the base class for all tag classes. It provides methods to validate tags, evaluate expressions export and restore variables, logging and debugging.

See Also:

Serialized Form

Field Summary

protected java.lang.Boolean	cachedDebug the cached value of the debug flag
protected AbstractLogger	cachedLogger the cached reference to the logger object
static java.lang.String	DEBUG_ATTR
protected static boolean	DEFAULT_DEBUG
protected static boolean	DEFAULT_RESTORE_VALUE
protected static int	DEFAULT_SCOPE
static java.lang.String	LOGGER_ATTR
protected java.util.Map[]	originalValues the original values of the variables that were exported

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

bodyContent

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

id, pageContext

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

EVAL_BODY_BUFFERED, EVAL_BODY_TAG

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

CommonSupport()
Calls init()

Method Summary

protected java.lang.String	checkVarName(java.lang.String varName) Verifies the name of a variable.
protected int	checkVarScope(java.lang.String scope) Verifies the scope of a variable.
void	doCatch(java.lang.Throwable t) Catches an exception that was thrown during the handling of the tag or during the processing of its body.
void	doFinally() This method is invoked by the Servlet container after tag handling.
protected java.lang.Object	eval(java.lang.String attributeName, java.lang.String expression, java.lang.Class expectedType) Evaluates an expression that follows the syntax defined by JSTL.
protected boolean	evalBoolean(java.lang.String attributeName, java.lang.String expression) Evaluates a JSTL expression to a boolean.
protected double	evalDouble(java.lang.String attributeName, java.lang.String expression) Evaluates a JSTL expression to a double.
protected int	evalInt(java.lang.String attributeName, java.lang.String expression) Evaluates a JSTL expression to a int.
protected java.lang.String	evalString(java.lang.String attributeName, java.lang.String expression) Evaluates a JSTL expression to a String.
protected void	export(java.lang.String name, java.lang.Object value, int scope) Exports a JSP variable with the given name, value and scope.
protected void	export(java.lang.String name, java.lang.Object value, int scope, boolean restoreValue) Exports a JSP variable with the given name, value and scope.
protected abstract java.util.List	getAllowedAncestors() Subclasses must implement this method to return the list of names of the tags that may contain the tag that is handled by this class.
protected boolean	getDebug() Returns true if there is a page/request/session/application variable called com.devsphere.xml.taglib.debug and its value is true.
protected AbstractLogger	getLogger() Returns the logger used by this tag handler, which must be an instance of a subclass of com.devsphere.logging.AbstractLogger.
abstract java.lang.String	getTagName() Subclasses must implement this method to return the tag name.
protected void	init() Initializes the fields of this tag handler.
protected void	log(java.lang.String message) Logs a message.
void	log(java.lang.String message, java.lang.Throwable throwable) Logs a message and an exception.
void	log(java.lang.Throwable throwable) Logs an exception.
protected void	restore() Restores the values of the variables that were exported with restoreValue == true and had a previous value.
protected void	validate(CommonSupport ancestor) Subclasses may call this method to verify if the handled tag was placed in the right context.

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

doAfterBody, doEndTag, doInitBody, doStartTag, getBodyContent, getPreviousOut, release, setBodyContent

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

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

Methods inherited from class java.lang.Object

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

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

getParent, setPageContext, setParent

Field Detail

DEBUG_ATTR

public static final java.lang.String DEBUG_ATTR

See Also:

Constant Field Values

LOGGER_ATTR

public static final java.lang.String LOGGER_ATTR

See Also:

Constant Field Values

DEFAULT_DEBUG

protected static final boolean DEFAULT_DEBUG

See Also:

Constant Field Values

DEFAULT_SCOPE

protected static final int DEFAULT_SCOPE

See Also:

Constant Field Values

DEFAULT_RESTORE_VALUE

protected static final boolean DEFAULT_RESTORE_VALUE

See Also:

Constant Field Values

cachedDebug

protected java.lang.Boolean cachedDebug

the cached value of the debug flag

cachedLogger

protected AbstractLogger cachedLogger

the cached reference to the logger object

originalValues

protected java.util.Map[] originalValues

the original values of the variables that were exported

Constructor Detail

CommonSupport

public CommonSupport()

Calls init()

Method Detail

init

protected void init()

Initializes the fields of this tag handler. Since instances of this classes may be recycled by Servlet containers (such as Tomcat), it is not enough to initialize everything in constructor. init() is also called in doFinally() to let the object in its initial state after handling a tag.

getTagName

public abstract java.lang.String getTagName()

Subclasses must implement this method to return the tag name.

Returns:

the name of the handled tag

getAllowedAncestors

protected abstract java.util.List getAllowedAncestors()

Subclasses must implement this method to return the list of names of the tags that may contain the tag that is handled by this class. The returned list is used by validate()

Returns:

the list of names of the allowed ancestor tags or null if the tag context doesn't matter.

validate

protected void validate(CommonSupport ancestor)
                 throws javax.servlet.jsp.JspException

Subclasses may call this method to verify if the handled tag was placed in the right context. This methods throws a JspException if

• ancestor is null, but the allowed ancestors list is not empty or
• ancestor is not null, but the allowed ancestors list is empty or
• the name of the given ancestor tag is not found in the allowed ancestors list returned by getAllowedAncestors().

Parameters:

ancestor - the tag handler of an ancestor whose name is searched in the list of allowed ancestors

Throws:

javax.servlet.jsp.JspException - to signal a tag validation error

checkVarName

protected java.lang.String checkVarName(java.lang.String varName)
                                 throws javax.servlet.jsp.JspException

Verifies the name of a variable. Currently, no checks are made.

Throws:

javax.servlet.jsp.JspException - to signal an attribute validation error

checkVarScope

protected int checkVarScope(java.lang.String scope)
                     throws javax.servlet.jsp.JspException

Verifies the scope of a variable. The allowed scopes are

• page
• request
• session
• application

Throws:

javax.servlet.jsp.JspException - to signal an attribute validation error

getDebug

protected boolean getDebug()

Returns true if there is a page/request/session/application variable called com.devsphere.xml.taglib.debug and its value is true. This value is cached. Also a tag may look for this debug flag to an ancestor tag instead of checking the variable.

The com.devsphere.xml.taglib.debug should be set at the beginning of a page with the page or request scope or in the login/welcome page of an application with the session or application scope depending on what you want to debug: a page, a page together with its included pages, a user session or the entire Web application.

Returns:

the value of the com.devsphere.xml.taglib.debug flag or false if this variable is not set.

getLogger

protected AbstractLogger getLogger()

Returns the logger used by this tag handler, which must be an instance of a subclass of com.devsphere.logging.AbstractLogger.

You may set a logger for a page, request, session or application by registering your logger object as the value of a variable called com.devsphere.xml.taglib.logger.

A tag handler derived from this class should look for a logger object at an ancestor tag of its tag library and set cachedLogger. If this field is null, getLogger() tries to get the logger from com.devsphere.xml.taglib.logger and caches it. If such a variable doesn't exist, a default logger will be created.

The com.devsphere.xml.taglib.logger should be set at the beginning of a page within the page or request scope or in the login/welcome page of an application within the session or application scope.

The default logger forwards the logging requests to the ServletContext object, by calling its log() methods. If the debug flag is set, the logged messages and exceptions are also printed to System.err

Returns:

the logger of this tag handler.

log

protected void log(java.lang.String message)

Logs a message.

Parameters:

message - the message that has to be logged.

log

public void log(java.lang.Throwable throwable)

Logs an exception.

Parameters:

throwable - the exception that has to be logged.

log

public void log(java.lang.String message,
                java.lang.Throwable throwable)

Logs a message and an exception.

Parameters:

message - the message that has to be logged.

throwable - the exception that has to be logged.

eval

protected java.lang.Object eval(java.lang.String attributeName,
                                java.lang.String expression,
                                java.lang.Class expectedType)
                         throws javax.servlet.jsp.JspException

Evaluates an expression that follows the syntax defined by JSTL.

The current implementation uses the expression evaluator of JSTL 1.0 implemented by Apache.

Parameters:

attributeName - the name of the tag attribute whose value is the expression that must be evaluated.

expression - the expression that is evaluated

expectedType - the type of the object returned by this method

Returns:

the value of the evaluated expression

javax.servlet.jsp.JspException

evalString

protected java.lang.String evalString(java.lang.String attributeName,
                                      java.lang.String expression)
                               throws javax.servlet.jsp.JspException

Evaluates a JSTL expression to a String.

Parameters:

attributeName - the name of the tag attribute whose value is the expression that must be evaluated.

expression - the expression that is evaluated

Returns:

the value of the evaluated expression

javax.servlet.jsp.JspException

evalBoolean

protected boolean evalBoolean(java.lang.String attributeName,
                              java.lang.String expression)
                       throws javax.servlet.jsp.JspException

Evaluates a JSTL expression to a boolean.

Parameters:

attributeName - the name of the tag attribute whose value is the expression that must be evaluated.

expression - the expression that is evaluated

Returns:

the value of the evaluated expression

javax.servlet.jsp.JspException

evalInt

protected int evalInt(java.lang.String attributeName,
                      java.lang.String expression)
               throws javax.servlet.jsp.JspException

Evaluates a JSTL expression to a int.

Parameters:

attributeName - the name of the tag attribute whose value is the expression that must be evaluated.

expression - the expression that is evaluated

Returns:

the value of the evaluated expression

javax.servlet.jsp.JspException

evalDouble

protected double evalDouble(java.lang.String attributeName,
                            java.lang.String expression)
                     throws javax.servlet.jsp.JspException

Evaluates a JSTL expression to a double.

Parameters:

attributeName - the name of the tag attribute whose value is the expression that must be evaluated.

expression - the expression that is evaluated

Returns:

the value of the evaluated expression

javax.servlet.jsp.JspException

export

protected void export(java.lang.String name,
                      java.lang.Object value,
                      int scope)

Exports a JSP variable with the given name, value and scope. This method calls pageContext.setAttribute() if the value is not null. Otherwise it calls pageContext.removeAttribute().

Parameters:

name - the name of the variable

value - the value of the variable

scope - the scope of the variable

export

protected void export(java.lang.String name,
                      java.lang.Object value,
                      int scope,
                      boolean restoreValue)

Exports a JSP variable with the given name, value and scope. This method calls pageContext.setAttribute() if the value is not null. Otherwise it calls pageContext.removeAttribute().

If restoreValue is true and there is already a variable with the given name within the given scope, the existent value is saved before setting the new value. In this case, doFinally() will restore the old value.

Parameters:

name - the name of the variable

value - the value of the variable

scope - the scope of the variable

restoreValue - indicates if the old value should be restored. If there is no old value, the new value will remain available after doFinally()

restore

protected void restore()

Restores the values of the variables that were exported with restoreValue == true and had a previous value. This method is called by doFinally().

doCatch

public void doCatch(java.lang.Throwable t)
             throws java.lang.Throwable

Catches an exception that was thrown during the handling of the tag or during the processing of its body. If the debug flag is true, this method throws the exception further. Otherwise it logs the exception.

Specified by:

doCatch in interface javax.servlet.jsp.tagext.TryCatchFinally

Parameters:

t - the exception that occurred during tag handling or body processing

Throws:

java.lang.Throwable - the same exception if the debug flag is true

doFinally

public void doFinally()

This method is invoked by the Servlet container after tag handling. It calls restore() and init().

Specified by:

doFinally in interface javax.servlet.jsp.tagext.TryCatchFinally