JSTL Core

A JSP page that wants to show a list, hide a block for guests or format a price needs logic, and the first generation of JSP put that logic in Java scriptlets. The Standard Tag Library (JSTL, "Jakarta Tags" since Jakarta EE 9) is the answer the platform standardised: a few dozen tags and functions with fixed names, attributes and behaviour, available in every container, so that the template stays markup and the logic is expressed with the expression language. The specification states the goal as helping page authors who are not fluent in a programming language, and lists what it offers: general-purpose actions that complement the expression language (display a value, set and remove scoped attributes, catch exceptions), control-flow actions (conditionals and iterators), tag library validators that can forbid scripting, and standard actions and EL functions for URLs, text formatting, internationalisation, SQL, XML and string handling.

It is a specification with several implementations of the same tag handlers, not a Tomcat feature. The API artifact holds the few Java types an application may touch (Config, ConditionalTagSupport, LoopTagSupport, LoopTag, LoopTagStatus, Result, LocalizationContext and the validators); the implementation artifact holds the tag handlers and the TLD files that map a URI to them. Neither is in the JSP container: Tomcat 11.0.26 has no JSTL jar in its lib directory, so the web application packages both, which is the setup the getting started page of this section builds. Eclipse GlassFish and the other full Jakarta EE servers ship their own.

Source: Jakarta Standard Tag Library 3.0 — 1 Introduction

Source: Jakarta Standard Tag Library 3.0 — specification page

Source: Jakarta Standard Tag Library 3.0 — 1.3 Container Requirement

A page that uses the tags without the jars fails when it is translated, not when it runs. Removing both jars from the WAR of this page gives, for the first request:

The specification text still says that the library requires a "Jakarta Server Pages 3.0 web container" and "Jakarta Expression Language 4.0": those sentences were not updated, and the current implementation runs on Pages 4.0 and EL 6.0.

The specification calls it the standard tag library, but it is exposed as five tag libraries, one per functional area, so that each area has its own namespace. A page opens a library with the taglib directive; the uri identifies the library and the prefix is the page author’s choice (the prefixes in the table are the specification’s, and every example of the section uses them).

Two more URIs live in the same jar, jakarta.tags.scriptfree and jakarta.tags.permittedTaglibs. They are not tag libraries in the usual sense but carriers of two tag library validators (ScriptFreeTLV and PermittedTaglibsTLV, specification chapter 14) that make a page fail translation when it contains scripting elements or imports a library that is not on a list; the Tag Library Descriptors & EL Functions page shows how to configure them.

The diagram shows the two groups of core tags that this page documents (shaded); the status of the five libraries differs. The Jakarta EE Tutorial says that "a subset of Jakarta Tags has been archived in favor of Jakarta XML Binding, Jakarta Faces and Jakarta Persistence", and that the core tag library and the functions "are still available in Facelets" (the Facelets view technology of Jakarta Faces accepts c: and fn: tags in its templates). In practice core, fmt and functions are the libraries a JSP page uses today, while sql and xml are kept for compatibility and prototyping.

curl for /g5jstlcore/libs.jsp:

Source: Jakarta Standard Tag Library 3.0 — 1.2 Multiple Tag Libraries

Source: Jakarta EE Tutorial — Jakarta Tags

The fmt:setLocale line matters for the second output: without a formatting locale (no Accept-Language header, no fmt:setLocale) the same tag printed the bare 1234.5 and ignored the pattern on Tomcat 11.0.26, which the tag documentation does not say. The formatting page of this section explains how the locale is chosen.

The examples need data in scope and a few beans to modify. A ServletContextListener puts the catalogue into application scope, and a filter mapped to *.jsp gives every request a fresh ReaderProfile, an empty map and a StringReader. The pages themselves are plain JSPs in the root of the WAR so that curl can reach them; in the real application of the section they live under WEB-INF/views behind a servlet.

Source: Jakarta Servlet 6.1 — 4.5 Context Attributes

Every plain-text page starts with <%@ page contentType="text/plain;charset=UTF-8" trimDirectiveWhitespaces="true" %>, which leaves out most blank lines but has a side effect worth knowing: trimDirectiveWhitespaces also removes template text that is only white space, so a single space between two ${...} expressions or two tags disappears (${a} ${b} prints ab). The examples therefore separate values with a visible character such as a bar. A name such as nothing that is not defined anywhere evaluates to null.

A tag is not interpreted at request time by looking up its name. The page is translated once, and the translation is where most of the work and most of the errors are:

What each step means in practice, in the order Tomcat applies it:

The tag library specification summarises the error policy in one sentence: syntax errors and constraints on static attributes are reported at translation time, constraints on dynamic attributes at request time. The tags also try to avoid exceptions where a page author could not reasonably handle them: a null where a collection is expected means "do nothing", and a null where a fixed set of values is expected means "use the default". When an exception is raised it is a JspException or a subclass (usually JspTagException), with the original error as its root cause if the tag caught one in its body.

Source: Jakarta Standard Tag Library 3.0 — 2.7 Errors and Exceptions

Source: Jakarta Standard Tag Library 3.0 — 2.3 Static vs Dynamic Attribute Values

Two rows of that table are caught only by the validator, not by the attribute check, and one case is not caught at all at translation time: a c:when or c:otherwise outside a c:choose. That page translates and the first request fails with JspTagException: Illegal use of <when>-style tag without <choose> as its direct parent.

Almost every attribute of a JSTL tag accepts an expression, written with the syntax of the expression language page. Three things from the specification’s chapter 3 decide how the value reaches the tag.

curl for /g5jstlcore/attrs.jsp, and for /g5jstlcore/attrs.jsp?tag=a&tag=b (only line 6 changes):

Source: Jakarta Standard Tag Library 3.0 — 3.1 Expressions and Attribute Values

Source: Jakarta Standard Tag Library 3.0 — 3.5 Automatic Type Conversion

Source: Jakarta Standard Tag Library 3.0 — 3.6 Default Values

Line 2 is the one that surprises: <c:set var="n" value="42"/> stores the String "42", not a number, while value="${42}" stores a Long, and value="${1}${2}" is two expressions in one attribute, so it is text ("12"), not a sum. Line 3 shows why that rarely hurts: the EL converts the String where a number is needed, so ${n + 1} is 43 and ${n == 42} is true. Line 6 is the specification’s own reason for the "null means do nothing" rule: a group of check boxes that nobody ticked sends no parameter at all, ${paramValues.tag} is null, and the loop over it simply prints nothing instead of throwing.

Every JSTL tag that produces a value exposes it the same way: as a scoped variable, a JSP scoped attribute (an attribute of the PageContext, the request, the session or the application, see the implicit objects and scopes page). No tag creates a Java scripting variable, which is what makes the library usable on pages with scripting disabled. The conventions are fixed by chapter 2 of the specification and are the same in every library.

Source: Jakarta Standard Tag Library 3.0 — 2.2 Scoped Variables

Source: Jakarta Standard Tag Library 3.0 — 2.2.1 var and scope

Source: Jakarta Standard Tag Library 3.0 — 2.2.2 Visibility

A name in the EL is resolved by PageContext.findAttribute, which looks in page, request, session and application scope, in that order, so scoped variables of different scopes behave as one namespace in which the innermost wins. The Pages and Tags specifications both ask page authors not to rely on the same name in different scopes, and Tomcat follows the lookup order. The loop below shows nested versus at-end variables on the Bookshelf; the shadow lines of the c:set section show the namespace rule.

(The missing space in loop 1in-1 is the trimDirectiveWhitespaces effect described above.)

Source: Jakarta Standard Tag Library 3.0 — c:forEach

c:out evaluates an expression and writes the result to the current JspWriter. The tag documentation describes it as "like <%= ... %>, but for expressions", and the specification’s overview explains what it adds to a bare ${...}: it escapes the five XML special characters by default and supports a default value for null.

Source: Jakarta Standard Tag Library 3.0 — 4.2 c:out

Source: Jakarta Tags 3.0 tagdocs — c:out

Reading the output line by line:

c:set assigns a value, and has five forms: it can set a scoped variable from an attribute or from the tag body, set a property of a bean or an entry of a map (target and property), or map a deferred expression.

Source: Jakarta Standard Tag Library 3.0 — 4.3 c:set

Source: Jakarta Tags 3.0 tagdocs — c:set

What the output shows:

c:remove is the companion of c:set. Its two attributes (var required, scope optional, both static) name the variable. With a scope only that scope is touched (PageContext.removeAttribute(name, scope)); without it the variable is removed from every scope (removeAttribute(name)). Removing a variable that does not exist is not an error.

Source: Jakarta Standard Tag Library 3.0 — 4.4 c:remove

Source: Jakarta Tags 3.0 tagdocs — c:remove

Line 3 is the surprise of the tag: the one-attribute form clears the name everywhere, including a session attribute that another part of the application may own. Always give the scope of the variable you created. The typical use is a message that must be shown once (see the worked example), and clearing a cached value held in session or application scope.

c:catch evaluates its body and catches any Throwable thrown by it. The exception is stored in the variable named by var (always in page scope); without var it is simply swallowed. If the body completes normally the variable is removed if it existed, so a stale error from an earlier catch does not survive. The specification presents it as a complement of the JSP error page: actions that are central to the page should not be wrapped, so their exceptions reach the error page, and actions of secondary importance should be, so that they never trigger it.

curl for /g5jstlcore/catch.jsp?page=abc:

and for /g5jstlcore/catch.jsp?page=4 (blank lines removed):

Source: Jakarta Standard Tag Library 3.0 — 4.5 c:catch

Source: Jakarta Tags 3.0 tagdocs — c:catch

Observations that are not in the specification’s text but follow from how the tag is built:

c:if evaluates its body only when test is true. There is no else: for two branches use c:choose. It also exposes the result of the test, which is how a condition is computed once and used several times.

test is a dynamic boolean. The constraint "if scope is given, var must be too" is checked at translation time.

curl for /g5jstlcore/if.jsp?admin=true&q=a&id=1 (blank lines removed):

and for /g5jstlcore/if.jsp?id=2&admin=1:

Source: Jakarta Standard Tag Library 3.0 — 5.3 c:if

Source: Jakarta Tags 3.0 tagdocs — c:if

How a test becomes a boolean is the EL’s coercion to boolean: a Boolean is itself, null is false, and a String is Boolean.valueOf of its text, true only for "true" in any case. That explains the output: ${param.admin} is true for ?admin=true but false for ?admin=1 (line 2 vanished in the second request), the String "TRUE" is true and "yes" is false, and a missing parameter or an undefined name is false. Prefer an explicit comparison (${param.admin eq 'true'}, or better a boolean the controller computed) to relying on the conversion of a request string. Line 10 shows var on a tag with a body: the Boolean is stored whether or not the body ran, and line 11 reuses it (for the second request, stock['2'] is 0, so the test is false and inStock is false).

The var form is the right tool when a test is needed twice: compute it once, then <c:if test="${canLoan}"> wherever it is needed, as the worked example does.

c:choose is the if / else if / else and switch of the library. It has no attributes of its own; its body holds one or more c:when (each with a test) and at most one c:otherwise, in that order, with only white space between them. The first c:when whose test is true is processed, all others are skipped, and c:otherwise runs only when no c:when did.

The semantic difference from several c:if tags is the point of the tag: a c:if always processes its body when its test is true, so two true c:if tags both print, whereas two true c:when tags print only the first one’s body. c:when and c:otherwise are only valid as direct children of c:choose, which is also why a custom conditional tag of an application should expose its result as a variable that a c:when can test (ConditionalTagSupport is the base class the API offers for that).

curl for /g5jstlcore/choose.jsp?id=1 prints:

and the first line is last copy for ?id=3, loaned out for ?id=2, unknown book 9 for ?id=9 and unknown book (no id) without a parameter; the other three lines never change.

Source: Jakarta Standard Tag Library 3.0 — 5.4 c:choose

Source: Jakarta Standard Tag Library 3.0 — 5.5 c:when

Source: Jakarta Standard Tag Library 3.0 — 5.6 c:otherwise

Source: Jakarta Standard Tag Library 3.0 — 5.2 Custom Logic Actions

Source: Jakarta Tags 3.0 tagdocs — c:choose

Source: Jakarta Tags 3.0 API — ConditionalTagSupport

The page below uses every tag of this page. It reads the book id, accepts it only if it is a number and exists, shows the stock level, offers a "borrow" form only when there is a copy, shows the "edit" link only to administrators, and displays a message left by the previous request exactly once. The data it needs is the listener of the setup section and the servlet that handles the form.

Responses of the deployed page, with blank lines removed. curl "$B/book.jsp?id=3&reader=Ana", a book with one copy:

id=2 (no copy, so no form) and the failure cases:

for ?id=abc, ?id=9 and no parameter. A reader name is escaped by c:out (?reader=<b>Ana</b> prints <h1>Bookshelf for &lt;b&gt;Ana&lt;/b&gt;</h1>). Posting the form and following the redirect, with a cookie jar so that the session survives, shows the message once:

The first request answers 302 (sendRedirect; a 303 is the strict Post/Redirect/Get answer, see the servlet fundamentals page of this section) and a post with id=x answers 400. The second request prints the <p class="flash">Loan requested for book 3</p> paragraph above the book, the third request does not, because c:remove cleared the session attribute.

Source: Jakarta Standard Tag Library 3.0 — c:out and c:choose

Notes on the page:

Source: Jakarta Standard Tag Library 3.0 — 4.2 c:out

Source: Apache Tomcat 11 — Security Reports

Source: OWASP — Cross Site Scripting Prevention Cheat Sheet

Source: Jakarta Standard Tag Library 3.0 — Appendix B: Changes

Source: Jakarta Standard Tag Library 3.0 — Appendix A: Compatibility & Migration

Source: Jakarta Standard Tag Library 3.1 (under development)

Source: The Java EE 5 Tutorial — Core Tag Library

Three leftovers in the official material are worth knowing. The Tags 3.0 specification text still refers to the "Jakarta Server Pages 3.0 web container" and "Expression Language 4.0" and to type-conversion "Section 1.23" of the EL specification (it is section 1.25 of EL 6.0). The tag documentation (tagdocs) lists the c:out attributes with the type java.lang.String while the specification says Object, boolean and Object, and its description of c:if still speaks of a "scripting variable", which the library never creates. The Jakarta EE Tutorial calls the SQL, XML and internationalisation parts "archived", but the specification of 3.0 and the 3.0.1 jar still contain them, with the same tags as before.

The section bibliography lists JSTL in Action (Manning, 2002), a JSTL 1.0 book for page authors on JSP 1.2, and Web Development with JavaServer Pages (Manning, 2001), which mentions JSTL only as an announcement. The core-tag concepts that JSTL in Action teaches are still right: c:out with escapeXml and default, c:set and c:remove, c:if, c:choose with c:when and c:otherwise, c:catch, scoped variables and the var/scope conventions. What changed is the environment around them.

Source: Manning — JSTL in Action

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