Custom Tags: Classic Handlers

A custom action is an element such as <bs:shelf items="${books}">...</bs:shelf> whose prefix is bound by a taglib directive to a tag library, a set of actions described by a tag library descriptor (TLD) and implemented by Java classes. Chapter 7 of the Pages specification defines two ways to implement the Java side: classic tag handlers (section 7.1.3) and simple tag handlers (section 7.1.5); and, since JSP 2.0, a third way that needs no Java at all, the tag file. A classic handler is "a Java class that implements the Tag, IterationTag, or BodyTag interface, and is the run-time representation of a custom action", as the specification puts it. The page implementation class "instantiates a tag handler object, or reuses an existing tag handler object, for each action in the JSP page"; the second half of that sentence is the pooling of the second half of this page.

Source: Jakarta Server Pages 4.0 — 7.1.3 Classic Tag Handlers

Source: Jakarta Server Pages 4.0 — 7.1.5 Simple Tag Handlers

What only classic handlers have is a short list: the return-code protocol itself, which lets one handler skip its body, repeat it or end the page; a BodyContent buffer that the handler can read and rewrite; TryCatchFinally hooks (the simple model has the doTag method and an ordinary try block instead); and compatibility with code that expects a Tag, such as the JSTL base classes. Everything else is easier with a SimpleTag: there is no return-code protocol, no pooling hazard (a simple handler is created for every use), no BodyContent, and the body is a JspFragment that can be invoked any number of times. The practical rule is therefore: read and fix classic handlers, extend the JSTL base classes when you need a conditional or loop tag compatible with c:forEach and c:choose, and write everything else as a tag file or a simple handler.

All the examples below are classes of one WAR, deployed under the context path /g6classic on Tomcat 11.0.26 as g6classic.war. The classes are in the package org.example.bookshelf.tags; imports and the package line are left out of the listings. A ServletContextListener puts the four books of the catalogue into the application attribute books (a record Book(long id, String title, String author, int year): Dune 1965, Neuromancer 1984, The Dispossessed 1974, Cosmos 1980), and the tag library bs is declared in WEB-INF/bs.tld with the URI https://example.org/bookshelf/classic. The Maven dependencies are the same as for the rest of this section: the Jakarta Servlet, Pages and Expression Language APIs with scope provided, jakarta.annotation-api 3.0.0 with scope provided (for the injection example), and the JSTL API 3.0.2 and implementation 3.0.1 (the latter two inside the WAR, because Tomcat does not ship JSTL).

Three interfaces build on each other, and two classes implement them so that a handler overrides only what it needs. The specification states the division of labour: Tag has the setters that initialise the handler and the doStartTag and doEndTag methods; IterationTag adds doAfterBody, which is called to decide whether to evaluate the body again; and BodyTag adds setBodyContent and doInitBody for a handler that wants the body in a buffer. TryCatchFinally is a "mix-in" that can be added to any of the three.

Source: Jakarta Pages 4.0 API — Tag

Source: Jakarta Pages 4.0 API — BodyTagSupport.getPreviousOut

For every use of a custom action the generated code does the same things in the same order: get a handler instance, call setPageContext and setParent, call one setter for every attribute that the page supplied, then call doStartTag. What that returns decides whether and how the body runs. After the body, doEndTag runs, and what that returns decides whether the rest of the page runs. A handler that implements TryCatchFinally is protected by a try block around all of this. When the use ends, the handler goes back to a pool (or is discarded); release() is not called between two uses.

Four sets of constants steer the protocol, and each is legal only from certain methods.

Source: Jakarta Pages 4.0 API — Tag.SKIP_BODY and the other return codes

Source: Jakarta Pages 4.0 API — IterationTag.EVAL_BODY_AGAIN

Source: Jakarta Pages 4.0 API — BodyTag.EVAL_BODY_BUFFERED

The protocol is not abstract: it is the Java that Jasper writes into the page’s servlet. The listing is the loop that Tomcat 11.0.26 generated for the iteration tag of this page (bs:shelf, shown in full below), trimmed to the calls that matter, with the generated names shortened; it was read from the work directory of the web application after the first request.

Source: Jakarta Pages 4.0 API — Tag, "Lifecycle"

Three things in the listing explain most classic-tag behaviour. The pool is keyed by the tag and the set of attributes used (the field name carries shelf, items and id), so two uses of the same tag with different attributes never share an instance. The body is a do ... while loop that doAfterBody controls. And the handler is returned to the pool (reuse) only on the normal path; if an exception escapes, releaseTag is called with reused false and the handler is thrown away (after release() and, if the container manages instances, destruction).

For a BodyTag that returns EVAL_BODY_BUFFERED, the generated code additionally brackets the loop with JspRuntimeLibrary.startBufferedBody (which pushes a BodyContent onto the page context) and popBody; the handler sees the buffer through setBodyContent, doInitBody and getBodyContent.

The simplest handler overrides doStartTag only. RecentTag decides, from two attributes, whether its body is evaluated; this is the "conditional" of the specification, done with the return value of doStartTag and nothing else. Attributes arrive through setters whose names follow the JavaBeans rule, one per <attribute> in the TLD, and the handler resets its state in release().

Source: Jakarta Server Pages 4.0 — 7.1.4 Simple Examples of Classic Tag Handlers

The TLD entry is what makes the class a tag. The element names name, tag-class, body-content and attribute (with name, required, rtexprvalue and type) are the ones of the Pages 4.0 TLD schema, web-jsptaglibrary_4_0.xsd; rtexprvalue set to true means that the attribute accepts a ${...} expression and other request-time values. The full schema, the location rules for descriptors and how Tomcat finds them are the subject of the tag library descriptor page of this section.

Source: Jakarta EE — web-jsptaglibrary_4_0.xsd (the Pages 4.0 TLD schema)

Source: Jakarta Server Pages 4.0 — 7.1.3 Classic Tag Handlers

A handler that implements only Tag and returns EVAL_BODY_INCLUDE cannot post-process the body; it can only let the body through or suppress it. That is exactly what c:if does, and it is why the JSTL ships a base class for it (see below).

An IterationTag repeats its body: doStartTag prepares the first item and returns EVAL_BODY_INCLUDE (or SKIP_BODY for an empty collection), and every doAfterBody either prepares the next item and returns EVAL_BODY_AGAIN or returns SKIP_BODY to leave the loop. The item is handed to the body by storing it in a scope of the page context, which is what a classic handler uses for every result: pageContext.setAttribute(name, value). ShelfTag uses the id attribute that TagSupport already provides as the variable name, and removes the variable in doEndTag, so that it does not outlive the tag.

Source: Jakarta Pages 4.0 API — IterationTag.doAfterBody

Because the item is a scoped attribute, the body can read it with EL (${book.title}) without any further declaration. A scripting variable is something more: a Java local variable that the translator declares in the page so that a scriptlet or an expression can use it as book. The page must be told about it at translation time, and there are two ways, which the specification describes as "directly in the TLD for simple cases, or through subclasses of TagExtraInfo`". Whichever way declares it, the handler still stores the object with `pageContext.setAttribute; the translator generates the code that copies the attribute into the local variable ("synchronisation") at the right moments. The moments are the scope of the variable.

Source: Jakarta Pages 4.0 API — VariableInfo

ShelfTagExtraInfo declares the variable named by the id attribute, of type org.example.bookshelf.Book, with declaration (true, a new Java variable) and NESTED scope. It is wired in with <tei-class> in the TLD entry of bs:shelf. The TagData argument carries the attribute values known at translation time; getId() is the id attribute, which is why id is declared with rtexprvalue false.

Source: Jakarta Pages 4.0 API — TagExtraInfo.getVariableInfo

A TagExtraInfo can do more than declare variables: its isValid and validate methods are called at translation time to check the attributes of every use of the tag, which is how a library reports "attribute a and b are mutually exclusive" as a translation error instead of a request-time failure (specification section 7.1.2, "Validation"). The variable element of the TLD is the alternative for the simple cases, shown below with bs:count.

Source: Jakarta Server Pages 4.0 — 7.1.4.7 Actions Defining Scripting Variables

The scriptlet <%= book.author() %> compiles because the translator declared book as a Book; that is the only place on this page where a scriptlet appears, because it is the only way to see a scripting variable. In a body that the TLD declares scriptless, or on a page whose property group sets scripting-invalid, scriptlets are not allowed and the container "need not synchronize" the variables; the EL reads the page-context attribute directly and always works.

For a variable whose name is a literal or comes from an attribute, no TagExtraInfo class is needed: the TLD variable element declares it with name-given or name-from-attribute, variable-class, declare and scope. CountTag exports the size of a list under the name given in var, with AT_END scope, so the variable exists after the tag.

Source: Jakarta Server Pages 4.0 — 7.1.4.7 Actions Defining Scripting Variables

Two actions can cooperate "explicitly, via scoped variables" (one creates an object under a name and the other reads it by that name) or "implicitly", through their nesting. For the second form the container gives every handler its parent through setParent, and TagSupport.findAncestorWithClass(from, class) walks up the chain and returns the nearest ancestor that is an instance of the class or implements the interface. PositionTag finds the enclosing ShelfTag and prints its position; used outside a shelf it reports the mistake with a JspTagException, which is the standard way to say "this tag is in the wrong place" (a translation-time check in a TagExtraInfo or a validator is better when it is possible, because the author sees the error before any request).

Source: Jakarta Pages 4.0 API — TagSupport.findAncestorWithClass

Source: Jakarta Server Pages 4.0 — 7.1.4.6 Cooperating Actions

The parent of a handler is the nearest enclosing custom action, whichever library it comes from, so a tag nested in c:if inside bs:shelf still finds the shelf even though the c:if handler is in between. A page of <bs:shelf ...><c:if test="${book.year gt 1970}">[<bs:position/> ${book.title}]</c:if></bs:shelf> printed [2 Neuromancer][3 The Dispossessed][4 Cosmos] on Tomcat 11.0.26: the position is that of the shelf, not of the c:if.

A handler that wants to see, change or discard its body returns EVAL_BODY_BUFFERED from doStartTag (that is the default of BodyTagSupport). The container then calls setBodyContent with a new BodyContent, a JspWriter that collects everything the body writes, calls doInitBody (the place to prepare the first pass), evaluates the body into the buffer, and calls doAfterBody. In doAfterBody the handler reads the text with getBodyContent().getString() (or getReader()), and writes the result to the writer that was current before the buffer was pushed. That writer is getPreviousOut() and it is the single most common source of errors for beginners: writing to pageContext.getOut() inside a buffered doAfterBody writes into the very buffer that is about to be discarded, so the output is lost.

Source: Jakarta Pages 4.0 API — BodyTagSupport.getPreviousOut

Source: Jakarta Pages 4.0 API — BodyContent.getString

What the body is depends on the body-content element of the TLD, which also decides what the translator accepts. The same ShoutTag class is declared three times in the example TLD (bs:shout with JSP, bs:rawshout with tagdependent, bs:plainshout with scriptless) to show the difference.

Source: Jakarta EE — web-jsptaglibrary_4_0.xsd, body-content

Source: Jakarta Server Pages 4.0 — 7.1.4.5 Actions that Process their Body

The tagdependent line is the reason that value exists: a tag that embeds another language in its body (a code sample, a SQL fragment, a JavaScript template) must not have its text interpreted as EL. Note also what the example shows about security: the handler transformed markup that was already part of the page, so nothing it does makes the text safe or unsafe; a body tag that echoes request data must escape it (see Security Notes below).

A handler that opens something in doStartTag (a lock, a transaction, a counter, a temporary file) cannot rely on doEndTag to close it, because an exception thrown by the body or by a nested tag skips doEndTag. The specification added TryCatchFinally in JSP 1.2 for exactly this, and defines the call pattern: doCatch(t) is called if an exception is thrown from doStartTag, from the body, from doAfterBody or from doEndTag (not from the setters), and doFinally() is always called afterwards, on both paths. If doCatch returns normally the exception is swallowed; if it throws, that is what propagates. release() and doFinally() are not the same thing: doFinally runs after every use and is where per-use state is cleaned up.

Source: Jakarta Pages 4.0 API — TryCatchFinally.doFinally

BoomTag throws JspTagException("the shelf collapsed") from doStartTag. The page wraps the guard in c:catch, which is itself a TryCatchFinally handler, so the exception is caught by the page and the request completes; the counter shows that the guard closed.

Source: Jakarta Pages 4.0 API — TryCatchFinally

The text inside was written before the nested tag failed, which shows that an exception does not undo output that reached the buffer; doCatch logged the exception and rethrew it (the ServletContext log line is guard saw JspTagException), and open guards: 0 shows that doFinally ran. Without TryCatchFinally the counter would stay at one for ever, and every failed request would leak a guard.

The Standard Tag Library’s own conditional and loop tags are classic handlers, and it publishes the base classes they are built on in jakarta.servlet.jsp.jstl.core, so that a library author gets the same behaviour and the same attributes without re-implementing them.

Source: Jakarta Tags 3.0 API — ConditionalTagSupport

Source: Jakarta Tags 3.0 API — LoopTagSupport

OldBooksTag is a conditional tag that stores its result for a c:if or a c:when to use, and EachTag is a loop that iterates over a list of books with the full c:forEach attribute set. The base class does the arithmetic of begin, end and step and the bookkeeping of varStatus; the subclass supplies the three iteration methods and the setters for the three numeric attributes (the base class declares the fields, not the setters, because only the subclass knows which attributes its TLD offers).

Source: Jakarta Tags 3.0 API — LoopTagSupport.validateBegin

Source: Jakarta Tags 3.0 API — LoopTagStatus.getIndex

The loop output shows the two numbers that confuse every first-time user of varStatus: index is the position in the underlying collection (1 and 3 with begin="1" step="2") and count is the number of the pass (1 and 2). The iteration page of this section covers the same two properties for c:forEach. A tag that must run inside any loop and ask "which pass is this?" implements nothing; it calls findAncestorWithClass(this, LoopTag.class) and reads getLoopStatus(), and then works with c:forEach, c:forTokens and bs:each alike.

Creating a handler object for every use of every tag, many times per request, is wasteful, and the specification therefore allows the page to reuse handlers rather than create new ones. Jasper, the JSP engine of Tomcat, does the latter: every page servlet owns a TagHandlerPool for each distinct combination of tag and attribute names it uses (visible in the generated source as a field whose name Jasper mangles from _jspx_tagPool_bs_shelf_items_id); get takes a handler from the pool or creates one, and reuse puts it back after a normal doEndTag. When the page is unloaded, _jspDestroy releases the pools, and that is when release() is called on every pooled handler. The Tomcat Jasper how-to lists the feature as "JSP Custom Tag Pooling", describes the switch as enablePooling ("Determines whether tag handler pooling is enabled. This is a compilation option. It will not alter the behaviour of JSPs that have already been compiled", true or false, default true), and the poolTagsWithExtends option for pages that use their own base class (both are listed with the other options on Jasper Configuration & Precompilation). The consequence is the one rule of classic handlers that everything else follows from.

A pooled handler is used again by the same page, by later requests and by other threads (never two at once), without release() in between. The Tag Javadoc says it in its lifecycle notes: setters "may be called again before a tag handler is reused", attribute setters "are called if the values differ or are expressed as request-time attribute values", and release() is for "releasing long-term data". Anything a handler stores in a field and does not reset is therefore seen by the next use. The two handlers below differ only in that respect; both print how many times they have been called since their state was last reset, and both are used four times in a loop.

(print stands for pageContext.getOut().print(...) wrapped in a try block that turns an IOException into a JspTagException.)

Source: Apache Tomcat 11.0 — Jasper 2 JSP Engine How To, Configuration (enablePooling)

StaleTag is a bug that depends on a performance feature: the code is "correct" with pooling off and fails with it on, and the failure depends on how handlers are recycled, which is a property of the container and of load. With pooling off the same page prints four times 1, which is what an author who tested on a single request would have seen. The rule that follows is simple and absolute: everything that is set per use must be set in doStartTag or by a setter, and everything that accumulates per use must be reset in doEndTag or in doFinally`; `release() is a place for long-term state only. An optional attribute that a page does not give is not set by the container at all: its setter is not called. Jasper keeps one pool per tag and set of attribute names, so on Tomcat a use without since never receives a handler that had since set; the specification does not promise that, and another container may reuse the instance, so a handler keeps its defaults in field initialisers and puts them back after every use, in doEndTag or doFinally.

The pool is how to disable the problem, and the switch is a servlet initialisation parameter of Jasper’s own servlet. It applies when pages are compiled, so existing compiled pages are not affected until they are recompiled.

Source: Apache Tomcat 11.0 — Jasper 2 JSP Engine How To, Configuration

Turning pooling off is a diagnostic, not a fix: it hides handlers that keep state and it costs allocation on every use, and it is not available to code that must run on other containers. Jasper also disables pooling by itself for some tags. A page that declares its own base class with the extends attribute of the page directive is not pooled unless poolTagsWithExtends is true (the how-to explains that Jasper cannot guarantee that the base class has done the initialisation that the pools need), and, as the next section shows, a handler that implements JspIdConsumer is created anew for every use.

Chapter 7 of the specification gives classic handlers three services beyond the protocol. First, resource injection (section 7.1.11): handlers that implement Tag or SimpleTag "may be annotated for injection", which happens "immediately after an instance of the tag handler is constructed, and before any of the tag properties are initialized". The supported annotations are @EJB, @PersistenceContext, @PersistenceUnit, @PostConstruct, @PreDestroy, @Resource and @WebServiceRef (and their plural forms), and a container that is not part of a Jakarta EE implementation is "encouraged, but not required" to support them; resource injection is not supported for JSP pages or tag files. Second, a handler that implements JspIdConsumer receives, through setJspId, an identification of its use in the page that is unique within the translation (section 7.1.10). Third, tag libraries can declare event listeners in the TLD, which the container registers before the application starts (section 7.1.9); that is the subject of the descriptor page of this section.

AuditTag counts the construction and destruction callbacks of its instances, and IdTag implements JspIdConsumer. Each is used in a loop; the page was requested twice, and the counters are static, so they accumulate over the lifetime of the web application.

Source: Jakarta Server Pages 4.0 — 7.1.11 Resource Injection

Source: Jakarta Server Pages 4.0 — 7.1.10 JspId Attribute

The first line is the proof that pooling works and that injection callbacks run once per instance and not once per use: three uses in a loop, and two requests, produced one @PostConstruct call and no @PreDestroy. The generated source for bs:id is different: Jasper writes new IdTag(), then _jsp_getInstanceManager().newInstance(...) and setJspId("jsp_652656546_0"), for every use and never puts the handler in a pool. That behaviour is not stated in the specification or the Jasper how-to; it is what Tomcat 11.0.26 does, and it is a reason not to depend on JspIdConsumer in a hot path.

A classic handler writes to the response, so the rules of any output code apply to it unchanged.

Source: Jakarta Server Pages 4.0 — Historical Note

The books in the section bibliography that teach custom tags were written for JSP 1.1 and 1.2 and for JSTL 1.0. What they say about the classic API is still correct as far as it goes; what has changed around it is listed below.