JSP.5.1 Introduction

A tag library abstracts some functionality by defining a specialized (sub)language that enables a more natural use of that functionality within JSP pages. The actions introduced by the tag library can be used by the JSP page author in JSP pages explicitly, when authoring the page manually, or implicitly, when using an authoring tool. Tag libraries are particularly useful to authoring tools because they make intent explicit and the parameters expressed in the action instance provide information to the tool.

Actions that are delivered as tag libraries are imported into a JSP page using the taglib directive, and can then be used in the page using the prefix given by the directive. An action can create new objects that can then be passed to other actions or can be manipulated programmatically through a scripting element in the JSP page.

Tag libraries are portable: They can be used in any legal JSP page regardless of the scripting language used in that page.

The tag extension mechanism includes information to:

• Execute a JSP page that uses the tag library.

• Author and modify a JSP page.

• Present the JSP page to the end user .

The JSP 1.1 specification mostly includes the first kind of information, plus basic information of the other two kinds. Later releases of the JSP specification may provide additional information; in the meanwhile, vendors may use vendor-specific information to address their needs.

A tag library is described via a tag library descriptor, an XML document that is described further below.

No custom directives can be described using the JSP 1.1 specification.

JSP.5.1.1 Goals

The tag extension mechanism described in this chapter addresses the following goals:

Portable: An action described in a tag library must be usable in any JSP container.

Simple: Unsophisticated users must be able to understand and use this mechanism. We would like to make it very easy for vendors of functionality to expose it through actions.

Expressive: We want to enable a wide range of actions to be described in this mechanism, including:

- Nested actions

- Scripting elements inside the body

- Creation, use, and updating of scripting variables

Usable from different scripting languages: Although the JSP specification currently only defines the semantics for scripting based on the Java programming language, we want to leave open other scripting languages.

Building upon existing concepts and machinery: We do not want to reinvent machinery that exists elsewhere. Also, we want to avoid future conflicts whenever we can predict them.

JSP.5.1.2 Overview

The basic mechanism for defining the semantics of an action is that of a tag handler . A tag handler is a Java class that implements the Tag or BodyTag interfaces and that is the runtime representation of a custom action.

The JSP page implementation class instantiates (or reuses) a tag handler object for each action in the JSP page. This handler object is a Java object that implements the javax.servlet.jsp. tagext .Tag interface. The handler object is responsible for the interaction between the JSP page and additional server-side objects.

There are two main interfaces: Tag and BodyTag .

• Tag defines the basic methods that are needed in all tag handlers. These methods include setter methods to initialize a tag handler with context data and with the attribute values of the corresponding action and the two methods doStartTag() and doEndTag() .

• BodyTag provides two additional methods for when the tag handler wants to manipulate its body. The two new methods are doInitBody() and doAfterBody() .

The use of interfaces simplifies taking an existing Java object and making it a tag handler. There are also two support classes that can be used as base classes: TagSupport and BodyTagSupport .

JSP.5.1.2.1 Simple Actions

In many cases, the tag handler needs only to use the tag handler's method doStartTag() which is invoked when the start tag is encountered . This method needs to access the attributes of the tag and may also want to access information on the state of the JSP page; this information is passed to the Tag object before the call to doStartTag() through several setter method calls.

The doEndTag() is similar to doStartTag() , except that it is invoked when the end tag of the action is encountered. The result of the doEndTag invocation indicates whether the remainder of the page is to be evaluated or not.

A particularly simple and frequent action is one that has an empty body (no text between the start and the end tag). The tag library descriptor can be used to indicate that the tag is always intended to be empty; this leads to better error checking at translation time and to better code quality in the JSP page implementation class.

JSP.5.1.2.2 Actions with Body

Recall that, in general, the body of an action may contain other custom and core actions and scripting elements, as well as uninterpreted template text.

In some cases, an action is interested only in "passing through" the content of the body. This can be done using the simple Tag interface by using a special return value in doStartTag() .

If an action element can have a non-empty body and is interested in the content of that body, the methods doInitBody() and doAfterBody() , defined in the BodyTag interface, are involved.

The control of the evaluation is actually done based on the result of method invocations as follows . The doStartTag() method is always invoked first and returns an int value that indicates if the body of the action should be evaluated or not. If so ( EVAL_BODY_TAG return), a nested stream of type BodyContent is created and is passed to the BodyTag object through setBodyContent . Then doInitBody is invoked. Next the body is evaluated, with the result going into the newly created BodyContent object. Finally, the doAfterBody() method of the tag handler object is invoked.

If the invocation to doStartTag() returned SKIP_BODY , the body is not evaluated at all.

The doBody() method may use the BodyContent object as it sees fit. For example, it may convert it into a string and use it as an argument, or it may do some filter action to it before passing it through to the out stream, or it may something else.

A doAfterBody() invocation returns an indication of whether further reevaluations of the body text should be done by the JSP page; as in the case of doStartTag() , if EVAL_BODY_TAG is returned, the body is reevaluated, while a return value of SKIP_BODY will stop reevaluations. Note that, since server-side objects (accessible via pageContext or through nested handlers) may have changed, each evaluation may produce very different content to be added to the BodyContent object.

JSP.5.1.2.3 Cooperating Actions

Often the best way to describe some functionality is through several cooperating actions. For example, an action may be used to describe information that leads to the creation of some server-side object, while another action may use that object elsewhere in the page. One way for these actions to cooperate is explicitly, via using scripting variables: One action creates an object and gives it a name, the other refers to it through this name . Scripting variables are discussed briefly below.

Two actions can also cooperate implicitly using different conventions. For example, perhaps the last action applies, or perhaps there is only one action of a given type per JSP page. A more flexible and very convenient mechanism for action cooperation is using the nesting structure to describe scoping. Each tag handler is told of its parent tag handler (if any) using a setter method; the findAncestorWithClass static method in TagSupport can then be used to locate a tag handler with some given properties.

JSP.5.1.2.4 Actions Defining Scripting Variables

A custom action may create some server-side objects and make them available to the scripting elements by creating or updating some scripting variables. The spe-cific variables thus effected may vary with the action instance. The details of this are described through subclasses of javax.servlet.jsp.tagext.TagExtraInfo which are used at JSP page translation time. The TagExtraInfo class provides methods that will indicate the names and types of the scripting variables that will be assigned objects (at request time) by the action. These methods are passed to a TagData instance that describes the attributes of a given action. The responsibility of the tag library author is to faithfully indicate this information in the TagExtraInfo class; the corresponding Tag object must add the objects to the pageContext object. It is the responsibility of the JSP page translator to automatically supply all the required code to do the "synchronization" between the pageObject values and the scripting variables.

JSP.5.1.3 Examples

This section outlines some simple, and common, uses of the tag extension mechanism. See Appendix JSP.A for more details on these examples and for additional examples of custom actions.

JSP.5.1.3.1 Call Functionality, No Body

This is probably the simplest example: just collect attributes and call into some action. The only action involved is foo , and in this case it should have no body. That is, something like:

 <x:foo att1="..." att2="..." att3="..." /> 

In this case we would define a FooTag tag handler that extends TagSupport only redefining doStartTag . The doStartTag method would take the attribute information, perhaps interact with the PageContext data, and invoke into the appropriate functionality.

The entry for this tag in the tag library descriptor should indicate that the action must have no body; no TagExtraInfo class is needed.

JSP.5.1.3.2 Call Functionality, No Body, Define Object

In a simple variation of the previous example the action defines an object.

 <x:bar id="mybar" att1="..." att2="..." att3="..." /> 

After this, an object with name mybar is available to the scripting language.

The semantics of the doStartTag() invocation is as before except that additionally it should insert the appropriate object for the mybar entry into the pageContext .

The tag library descriptor entry for this action needs to mention a TagExtraInfo class that will be used to determine the scripting variables that will be created by the action; in this case " mybar " (note that id must be a translation-time attribute).

JSP.5.1.3.3 Call Functionality, Define Object by Scope

In some cases, the previous example can also be described without using a TagExtraInfo by having the bar action enclose the actions that would use the created object. In this case, the defining action needs not indicate any id attribute but it must have a body:

 <x:bar att1="..." att2="..." att3="...">    BODY  </x:bar> 

The nesting actions will invoke findAncestorWithClass to locate the bar handler object.

JSP.5.1.3.4 Template Mechanisms

There are a number of template mechanisms in server-side frameworks. The simplest of these mechanisms will take a token and replace it by some fixed replacement text (that can be changed easily); more sophisticated mechanisms compute the replacement text, and can pass arguments for that computation. These mechanisms can be subsumed directly into an empty-bodied action invocation, perhaps using attributes to describe the template and/or the arguments for the computation.

JSP.5.1.3.5 An HTML Quoting Action

The final example is an action that takes its body and performs HTML quoting. In this case, the doStartTag() method will save away the value of the out implicit object and request the evaluation of the body. The doAfterBody() method will take the nested stream, perform the quoting, and send it down to the saved out stream.

JSP.5.1.3.6 A useBean as in the JSP 0.92 Specification

The 0.92 public draft of the JSP specification included a version of a useBean action with a variation: if the bean created included a processRequest(ServletRequest) method then the method would be invoked. Observant readers will notice that a processRequest() is a special case of a doStartTag() as the request object is one of the objects available in pageContext .