Implements the core functionality used by all X-Application tags.
Maybe the most important class in this packages is XTag. An X-Application tags is
a tag derived from XTag - every X-Application tags is derived from XTag.
The primary purpose of XTag is to provide derived classes access to the X tag context.
We use the term X tag context to refer to the state a tag operates on. The tag context is
implemented by three classes: RequestContext, SessionContext and
ApplicationContext. These classes resemble the lifetime of various parts of the
context: the RequestContext changes for every request; the SessionContext
persists multiple request -- as long as they belong to the same session. And finally, the
ApplicationContext the is shared for all sessions as long as they belong the the same
application.
JspTag is derived from XTag. X-Application tags to not derive XTag
directly; instead, they derive JspTag. At first glance, this is an awkward
architectur ... the main purpose is to allow for unit testing. The design section below explains
some of the underlying considerations.
The remaining classes implement exception handling and tracing.
If you want to implement your own tag, you first have to decide if you want to implement an X-Application tag or not. Technically, you implement an X-Application tag by deriving it from XTag (and JspTag). By doing so, your tag has seamless access to X-Application data (e.g. do modify the current document). But there is a price to pay: some technical data (most notably the pageContext) is not available. This section applies if you decide to implement an X-Application tag. Otherwise, the normal rules for implementing Jsp tags apply. In both cases, you should read one book or another about Jsp pages.
As a rule of thumb, you should implement an X-Application tag, if your tags interacts with existing X-Application tags and needs access to X-Application data (e.g. the current document). In contrast, you should implement a normal tag (by implement Jsp's Tag/BodyTag interfaces or derive from TagSupport/BodyTagSupport classes), if your tag implements an isolated feature, e.g. a hit counter for web pages.
Here are the basic steps to derive from JspTag:
sessionContext
and requestContext. They to provide access to the current state of your
application. Caution: JspTags have no access to the current pageContext.sessionContext.unlock().
Otherwise, the current session blocks, new request will not be handled.do.. methods. They are implemented in the JspTag
class, your tag does not implement them. Instead, you implement the corresponding
do..Core method. Except for the name, these method follows the same rules as
defined in the Jsp specification.Base class for X-Application tags is JspTag, and XTag in
turn is derived from XTag. This is to meet two requirements: common processing
for all tags and unit-testability. This section explains the underlying design
considerations -- and answers questions like "why do X-Application tags do not have
access to pageContext.
We have pre- and post-processing that is common in all X-Application tags. Most notably, this is exception handling. Exception handling code must *not* be duplicated in every tag since exception handling is extremely fragile: one unhandled exception causes a locked SessionContext which makes the current session unusable. If we had to repeat the exception handling code in every tag we would most likely forget it in one place or another.
XTag and JspTag implement a common pre- and post-processing.
JspTag implements the various do... methods required by Jsp. This
implementation invokes the corresponding do..core method declared in
XTag. X-Application tags implement the do..core methods only, they
never re-implement do.. methods (and cannot do so since all do..
methods are final.
To explain unit testability, we first have to details the term tag context and explain the distrinction we have draw between a Jsp tag context and a X tag context. All of these terms are X-Application creations, e.g. the Jsp specification does not use the term tag context.
Tag context. Tags are executed in a tag context. The tag context is the set of variables
available to a tag if it is executed. Executing a tag means invoking do..core.
Tags have access to individual variable either via protected fields or via getter methods.
Example: bodyContent is a variable in the tag context.
Jsp tag context. Jsp containers execute tags in a container-specific Jsp tag context.
Variables in this context are, for example, pageContext or
servletRequest. This Jsp tag context is problemantic for unit testing since we had
to provide mock implementations for a number of these classes (e.g. PageContext, ServletRequest,
etc) and for every object that might be accessed via there objects. As a consequence, we came
up with a simplified context: X tag context.
X tag context. X-Application tags are executed in the X tag context. The X tag context
is a subset of the Jsp tag context that is a) sufficiently small for mock objects and b)
sufficiently large for the information requirements in X-Application tags. Currently, the
X tag context is comprised of the following variables: xParent, out,
bodyContent, sessionContext and requstContext.
The distinction between XTag and JspTag resembles this
distinction between X tag context and Jsp tag context: XTag provides the
X tag context and JspTag maps the Jsp tag context to the X tag context.
The base class JspTag contains a method especially for exception handling.
Received exceptions (1) will be passed to a speciall ExceptionFormatter (2).
Exceptions can be either checked or unchecked.
Possible unchecked Exceptions:
AssertionFailed,PreconditionViolation andIOExceptionChecked Exceptions are of type ContainerException. ContainerException exceptions
could be empty or they contain the "catched" exceptions as nested content.
Every ContainerException gets a certain identifier: The exceptions can be configured
in a seperate file 'exceptions.xml'
.
The ExceptionFormatter interprets the received exceptions and categorises them to their appropriate display
exception type.