Custom Tags: SimpleTag

The specification introduces simple tags with an argument about complexity. The protocol of classic handlers is complicated because scriptlets in a tag body can depend on variables the page created with other scriptlets, so the container has to call the handler before and after the body, buffer it, loop it and keep the handler’s state in step with the page. Once pages are written with the expression language and the standard tag library, a body no longer needs scriptlets, and the protocol can be one call. JSP 2.0 therefore added the Simple Tag Extension, which can be written in two ways: in Java, by implementing the SimpleTag interface (or, in practice, by extending the convenience class SimpleTagSupport), or in JSP, as a tag file. Both are the same thing to the page author, and a tag file is translated by the container into a SimpleTag handler.

Source: Jakarta Pages 4.0 — 7.1.5 Simple Tag Handlers

The simple protocol has four properties that follow from the specification and that the rest of the page uses.

SimpleTag has five methods. SimpleTagSupport implements all of them, keeps the values the container passes in and adds three protected or static helpers; a handler normally extends it and overrides doTag() only. The Javadoc requires every simple handler to have a public no-argument constructor, because the generated page calls it.

Source: Jakarta Pages 4.0 API — SimpleTag

Source: Jakarta Pages 4.0 API — SimpleTagSupport.findAncestorWithClass

JspFragment is the type of the body. It has exactly two methods, and everything a tag does with its body goes through them.

Source: Jakarta Pages 4.0 API — JspFragment.invoke

JspContext is what the handler uses to talk to the page. Its methods are the same scoped-attribute methods as on PageContext (the implicit objects and scopes page describes the four scopes and their lookup order): setAttribute(name, value, scope), getAttribute(name, scope), findAttribute(name), removeAttribute(name, scope), getOut() for the JspWriter, getELContext(), and pushBody(Writer) and popBody() for redirecting output. The scope arguments are the integer constants PageContext.PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE and APPLICATION_SCOPE; there are no scope constants on JspContext itself.

Source: Jakarta Pages 4.0 API — JspContext.setAttribute

The Javadoc of SimpleTag gives a short, non-normative description of the lifecycle, and the Javadoc of doTag() adds that the container resynchronises AT_BEGIN and AT_END variables after the method returns. The diagram shows one invocation.

The order is easy to verify. The TraceTag below records every call the container makes on it, and a page nests one trace tag inside another so that setParent happens as well.

Source: Jakarta Pages 4.0 API — SimpleTag lifecycle

Source: Jakarta Pages 4.0 — 7.1.5 Simple Tag Handlers

Four things are visible in it. The order is constructor, setJspContext, then setParent (only for the inner tag), then the attribute setters, then setJspBody (only for the outer tag, whose element has a body, and not for the empty inner one), then doTag. A new instance is created for every invocation, even for the same tag in the same page on the next request: the instance numbers keep increasing from 1 to 4. The outer handler’s doTag() runs before the inner one’s, because the inner tag lives in the body and the body only runs when invoke is called. And the container calls nothing after doTag() that the handler can see: there is no release() and no doEndTag().

A tag exists for the container only through a tag library descriptor. The one for the Bookshelf is a single file, WEB-INF/bookshelf.tld, which is found without any further configuration: the container scans WEB-INF (and the META-INF of every JAR in WEB-INF/lib) for .tld files and maps the uri element of each to the descriptor, so a page only needs a taglib directive with that URI. The URI is an identifier, not a link; it does not have to resolve to anything. The element order inside tag follows the schema web-jsptaglibrary_4_0.xsd: name, tag-class, body-content, variable, attribute, dynamic-attributes.

Source: Jakarta Pages 4.0 — 7.3.10 Tag and Tag Library Extension Elements

Source: Jakarta EE — web-jsptaglibrary_4_0.xsd

Source: Jakarta Pages 4.0 — 7.3.10 Tag and Tag Library Extension Elements

The first tag prints a star rating. It has a required integer attribute value, an optional max (default 5), and the pair var and scope that the standard tag library also uses: with var the tag stores the result in a scoped variable instead of printing it. Every attribute is a JavaBean property of the handler, so the container calls setValue(int), setMax(int), setVar(String) and setScope(String). The TLD says which attributes accept an expression (rtexprvalue true) and of which type; the container converts the value to the setter’s type with the same rules as for every other action (a string literal is converted at translation time, an EL result at request time).

Source: Jakarta Pages 4.0 API — SimpleTagSupport.getJspContext

Source: Jakarta Pages 4.0 — 1.14.1 Request Time Attribute Values

The handler validates its attributes in doTag() and signals a mistake with a JspTagException (a JspException that the page’s error handling shows like any other exception, see the error handling page); it writes with getJspContext().getOut(), the page’s own JspWriter, so that its output is in order with the template text around it and obeys the page buffer.

Source: Jakarta Pages 4.0 — 7.1.7 Simple Examples of Simple Tag Handlers

The fourth line shows something that is true of every tag on this page and is easy to miss: the tag escaped nothing because it printed nothing from the request, but the page’s own ${b.title} did not escape the title either. A tag does not change the escaping rules of the template text next to it.

The var and scope form exports a value instead of printing it. A scoped variable written by a handler is read back by the EL like any other, and it follows the normal scope rules.

Source: Jakarta Pages 4.0 API — JspContext.setAttribute

${stars} found the request attribute because the EL resolves a bare name through the scopes in the order page, request, session, application. The default scope of the handler is page, which is why ${pageScope.s2} works for the third tag.

The mistakes a page author can make with attributes are caught at three different times, and the message tells which.

Source: Jakarta Pages 4.0 — 1.14.2 Type Conversions

The last row is the reason why bs:rating declares no variable element for its optional var: a name-from-attribute variable makes the attribute mandatory in practice, because the translator cannot compute the name without it. The EL does not need the declaration, since it reads scoped variables at run time; the declaration matters only for a scripting variable that a scriptlet could read, which a modern page does not use. A tag whose var is required, like bs:pagination below, can and should declare it.

The body of the tag is what the page author writes between the start and the end tag. The TLD’s body-content decides what is allowed there, and the handler decides what happens to it. Three patterns cover almost every tag.

Some tags mimic an HTML element and cannot know which attributes the page author needs: class, title, data-id, aria-current. Since JSP 2.0 a handler can declare that it accepts attributes with dynamic names. It implements DynamicAttributes, whose single method setDynamicAttribute(String uri, String localName, Object value) is called by the container for every attribute that the TLD does not name, and the tag’s TLD entry carries <dynamic-attributes>true</dynamic-attributes>. Without that element, an unknown attribute is a translation error (as for colour above). The handler must remember the values itself, and a JspException thrown from the method means "I do not accept this one": the container then does not call doTag().

bs:link is an anchor with one declared attribute, href, and any number of dynamic attributes. It is written to be safe: the names are limited to a conservative pattern, style and every on... event attribute are refused, the javascript: scheme is refused, and every value and the href are escaped.

Source: Jakarta Pages 4.0 API — DynamicAttributes.setDynamicAttribute

Source: Jakarta Pages 4.0 — 7.1.8 Attributes With Dynamic Names

The title attribute of the fourth book is escaped by the tag, as it should be; the link text is the body, the raw ${b.title} of the page, and is not (the third pitfall in the table at the end of the page). The attribute checks, with the three kinds of dangerous input:

Source: OWASP — Cross Site Scripting Prevention Cheat Sheet

The uri argument is the namespace of the attribute, null for the default namespace; it matters only for XML-syntax pages that write prefix:name attributes. An EL expression that evaluates to null reaches setDynamicAttribute as a null value, which is why the handler above skips it: aria-current="${active ? 'page' : null}" writes the attribute on the current page link and nothing on the others. If the dynamic attribute is written with jsp:attribute, its body is evaluated and passed as a String.

Tags nested in other tags can talk to each other through the tree the container builds. setParent gives each handler its enclosing tag, and SimpleTagSupport.findAncestorWithClass(from, klass) walks up the chain and returns the closest ancestor of a class. bs:numbered is an ordered list that numbers its bs:item children, and the item finds its parent by class.

Source: Jakarta Pages 4.0 — 7.1.7.6 Cooperating Actions

Source: Jakarta Pages 4.0 API — SimpleTagSupport.findAncestorWithClass

Without the last line the page prints <ol> with the items <li value="1">Dune</li> and <li value="2">Neuromancer</li>. With it, the container reports JspTagException: bs:item must be nested in bs:numbered and the whole response is an error page: the output of the list is in the response buffer and is discarded with it (see Error Handling for the buffer rules).

SimpleTag does not extend Tag, so the two families have a seam. A classic handler nested in a simple tag cannot have a SimpleTag as its parent, because Tag.setParent accepts only a Tag; the container wraps the simple parent in a TagAdapter and gives that to the classic child. TagSupport.findAncestorWithClass compares classes literally and therefore does not see through the adapter, while SimpleTagSupport.findAncestorWithClass unwraps it:

Source: Jakarta Pages 4.0 API — TagAdapter

Source: Jakarta Pages 4.0 — 7.1.7.6 Cooperating Actions

The rule from the specification is to use SimpleTagSupport.findAncestorWithClass in every case in which the wanted ancestor may be a simple tag, and getAdaptee() on the adapter to reach the simple tag from classic code.

A classic handler stops the rest of the page by returning SKIP_PAGE from doEndTag(). A simple handler throws SkipPageException from doTag() (or a fragment does, which a handler propagates). The Javadoc is explicit about the effect: the calling page must cease evaluation. It is the mechanism behind a guard tag such as "stop unless the request has an id", and it is also thrown by the container itself when a tag file invokes a classic handler that returned SKIP_PAGE.

Source: Jakarta Pages 4.0 API — SkipPageException

Source: Jakarta Pages 4.0 — 7.1.7.1 Plain Actions

The text before the tag was sent, the text after it was not, and the status is 200, because stopping the page is not an error. The third row shows the scope of the stop: the page that included stop.jsp carried on, since a jsp:include is a separate request dispatch (see the includes and forwards page); only the page that contains the tag stops. Compare a JspTagException, which discards the buffer and produces an error response. Use SkipPageException only for "the rest of this page makes no sense", for example after a redirect the tag has already sent; the Javadoc adds that it "should not be thrown manually in a JSP page or tag file", meaning in a scriptlet.

JspContext, PageContext and tag files. A simple handler receives a JspContext. On Tomcat the object is the page’s PageContextImpl, so a cast to PageContext for the request, the response or the session works in an ordinary page, and this is common in practice. It is not portable to every context: the same handler called from inside a tag file got a JspContextWrapper (the page context of the tag file) in the test, and on Tomcat that class is also a PageContext:

The specification only promises a JspContext, and a handler meant for reuse should use the JspContext methods and test with instanceof PageContext before it needs the servlet API.

Resource injection. Handlers that implement Tag or SimpleTag may be annotated for injection (@Resource, @EJB, @PersistenceContext, @PostConstruct, @PreDestroy and the others the Servlet specification lists in section 15.5); the container injects them right after the instance is constructed and before any attribute is set. Injection is not supported for JSP pages or tag files, and a container that is not a full Jakarta EE server is encouraged but not required to support it, so a tag that relies on it is not portable to a plain servlet container.

JspIdConsumer. A handler that implements JspIdConsumer receives a jspId through setJspId, a string that is unique for every tag in a page and the same for a given tag on every request. It is the way to generate stable HTML ids; the Javadoc notes that such handlers cannot be reused, which is no restriction for simple tags.

Event listeners. A tag library may list listener classes in its TLD; the container registers them before the application starts. The mechanism is the same for classic and simple libraries and is described on the tag library descriptors page.

Scripting variables. A variable declaration can create a scripting variable for scriptlets, but a tag body of a simple tag is a fragment and cannot contain scriptlets: a translation error occurs if it does. The variables of this page are scoped variables read through the EL.

Pooling. The container does not pool simple handlers (the trace above shows a new instance for every use), so the Jasper option enablePooling, which controls the reuse of classic handlers, has no effect on them; the classic handlers page of this section covers the option and the 2024 Tomcat vulnerability in tag recycling.

Source: Jakarta Pages 4.0 — 7.1.11 Resource Injection

Source: Jakarta Pages 4.0 — 7.1.10 JspId Attribute

Source: Jakarta Pages 4.0 — 7.1.9 Event Listeners

Source: Apache Tomcat 11 — Jasper 2 How-To, Configuration

The pieces come together in one page: a catalogue of two books per page with a link, a rating, a "classic" badge, an excerpt of the blurb, and a pager. The application scope holds the four books (the ShelfListener of the scratch project sets them), and the page chooses the books to show with c:forEach begin and end from the p request parameter.

Source: Jakarta Pages 4.0 — 7.1.5 Simple Tag Handlers

Source: Jakarta Pages 4.0 — 5.7 jsp:attribute

And the second page (worked.jsp?p=2) shows the third and fourth books, the last one with the hostile title, which c:out (inside the bs:link body) and the tag’s own escaping render harmlessly, and moves aria-current to the second link:

Source: Jakarta Pages 4.0 — 7.1.7 Simple Examples of Simple Tag Handlers

The page has no scriptlet and no Java, the tags do the presentation, and each of them is testable on its own. The decisions that make it work: c:out for the title, because the body of bs:link is not escaped; the tag escapes the attribute values and the excerpt, because they cross from data to markup inside the tag; the page uses fn:length for the total instead of asking the tag to count; and the pager’s separator is a fragment so that the page author, not the tag, decides what goes between the numbers.

Source: Jakarta Pages 4.0 — C.1 Changes between JSP 4.0 and JSP 3.1

Source: Jakarta Pages 4.0 — C.2 Changes between JSP 3.1 and JSP 3.0

Source: Jakarta Pages 4.0 — C.3 Changes between JSP 3.0 and JSR 245

Two leftovers in the official material are worth knowing. The Javadoc of SimpleTag.doTag() mentions the resynchronisation of AT_BEGIN and AT_END variables only, while the variable synchronisation table of the specification (section 8.9, written for tag files) lists NESTED as well; as the test above shows, a Java handler cannot rely on the container for the NESTED rule. And the Javadoc of SimpleTagSupport.findAncestorWithClass still contains the typo "TagAdpater" in its text.

The section bibliography lists Web Development with JavaServer Pages (Manning, 2001, JSP 1.2), whose chapters on custom tags describe the tag extension mechanism of its time, and JSTL in Action (Manning, 2002), whose last chapter builds custom tags that cooperate with JSTL. The ideas that these chapters teach are still sound: a tag library as a vocabulary, a TLD that describes it, attributes as bean properties, scoped variables as the way a tag gives data to its body, tags that cooperate through their parent, and the discipline of separating tags from business logic. What changed is the API and the amount of code needed.

Source: Manning — Web Development with JavaServer Pages, Second Edition

Source: Manning — JSTL in Action