JSTL Iteration

All the examples are views of one WAR, deployed as g5jstliteration.war under the context path /g5jstliteration. Its Maven dependencies are the ones of the section’s example application: jakarta.servlet-api 6.1.0, jakarta.servlet.jsp-api 4.0.0 and jakarta.el-api 6.0.1 as provided, and the JSTL API 3.0.2 with the GlassFish implementation 3.0.1 as ordinary compile-scope dependencies, because Tomcat does not ship JSTL. A servlet mapped to /view/* puts the catalogue and a few other collections in the request and forwards to /WEB-INF/views/<name>.jsp. A record is a bean for EL 6.0, so the loop variable reads the Book components as ${b.title}.

Source: Jakarta Expression Language 6.0 — RecordELResolver

Source: Jakarta Servlet 6.1 — 9 Dispatching Requests

Every JSP listing below omits the page directive and the taglib directive that start each file (<%@ taglib prefix="c" uri="jakarta.tags.core" %>). Most views use contentType="text/plain" so that the output can be shown exactly; the views that produce HTML say so. Because the output is plain text, those listings do not escape anything; in a real HTML page every value that can contain user text goes through c:out, as the worked example shows.

Iteration lives in the core library, jakarta.tags.core, conventionally with the prefix c. The library has two iteration tags, and a third one in the XML library that belongs to the legacy part of JSTL.

Source: Jakarta Standard Tag Library 3.0 — 6 Iterator Actions: core tag library

Both core tags share their range attributes (begin, end, step), their var and varStatus attributes and their status object. The specification describes c:forEach as the base iteration action and says other iteration actions, c:forTokens and x:forEach among them, exist for "specific, specialized functionality". The flow below is what the tag does on every request; the sections that follow take its steps one at a time.

Source: Jakarta Standard Tag Library 3.0 — c:forEach

c:forEach has two syntaxes, one that walks a collection and one that counts. They share every attribute except items.

Source: Jakarta Standard Tag Library 3.0 — c:forEach

Source: Jakarta Tags 3.0 tag reference — c:forEach

The tag reference lists begin, end and step as int and items as a jakarta.el.ValueExpression; the specification adds the constraints, which the container enforces at request time (see the pitfalls table for the exact exceptions). Three consequences are worth keeping in mind. First, var and varStatus are names, not expressions: writing var="${name}" is a translation error (observed: "attribute [var] does not accept any expressions"). Second, both are optional, so a loop that only needs to repeat its body (c:forEach begin="1" end="3" printing a star) can omit them. Third, an attribute that is an expression is coerced to int by the Expression Language rules, so a request parameter such as ${param.page} works without parsing, as long as it holds a number.

The specification lists the types items must support. The container does not make the page author care which one it is: the body sees "the item", whatever the collection holds.

Source: Jakarta Standard Tag Library 3.0 — 6.1.1 Collections of Objects to Iterate Over

Source: Jakarta Standard Tag Library 3.0 — c:forEach

The output of /g5jstliteration/view/collections is below. The int[] loop shows the primitive wrapping, because n + 1 is arithmetic on an Integer, and the last two lines show the null rule: an empty list and an attribute that does not exist both iterate zero times, without an error.

Leave out items and c:forEach becomes a counted loop: begin and end are both required and the current value is an Integer. The range is inclusive at both ends, which is the opposite of a Java for (int i = 1; i < 5; i++).

Source: Jakarta Standard Tag Library 3.0 — 6.1.4 Range Attributes

A counted loop is the right tool for page numbers (begin="1" end="${pages}"), for a fixed number of empty form rows and for the stars of a rating. It is the wrong tool for walking a list by index (books[i]), because the collection can do that itself.

With items, the range attributes select a slice of the collection without copying it. begin and end are indexes into the collection, counted from 0, and end is included; step keeps every step-th item of the slice, starting with the first one. The six books have the ids 1 to 6 and the indexes 0 to 5, so the item with index i prints as the id i + 1 in the table below.

Source: Jakarta Standard Tag Library 3.0 — c:forEach, Constraints and Description

The last row is the one that surprises: an end that is empty, for example end="${param.last}" for a request without that parameter, is not the same as leaving out end: it is 0. If a limit is optional, test for it in the page or the servlet and leave the attribute out, or give the expression a default.

varStatus names a page-scope variable that holds, for the round that is running, a jakarta.servlet.jsp.jstl.core.LoopTagStatus. The interface is small, and the page reads it with the JavaBean properties below.

Source: Jakarta Standard Tag Library 3.0 — LoopTagStatus

Source: Jakarta Standard Tag Library 3.0 — 6.1.3 Iteration Status

The output shows the four things that trip people. The two rounds are the indexes 2 and 4, so index and count differ (index is for "which item of the list", count is for "which row of the output"). last is true on the index 4 round even though end is 5, because the next step would be index 6. begin, end and step are null when the attributes were not given, and null prints as an empty string, so a page that needs a default writes ${empty s.end ? 'none' : s.end}. Finally, the object is an instance of an internal class of the implementation: depend on the interface and its properties, not on that class.

The status variable is a convenience, not a requirement: the loop does not pay for it unless varStatus is present, and nothing in LoopTagStatus can be changed from the page. The interface is the same one that custom loop tags expose, as the section on tag collaboration explains.

Most pages use c:forEach for exactly one job, a table. The catalogue below shows the pieces together: an empty-state branch with c:choose, a table whose row classes come from varStatus (zebra stripes through count, and the first and last rows marked for the style sheet), values escaped with c:out, and a second loop that builds a comma-separated list with last deciding where the separators go.

Source: Jakarta Standard Tag Library 3.0 — c:choose

The rendered HTML for the six books (the rows 3 to 5, which are the same as the others with their own values, are left out). The <tr> classes alternate odd and even, and the first and last rows carry the extra class.

Source: Jakarta Standard Tag Library 3.0 — c:out

With the books replaced by the empty list the same page prints the other branch, <p>The shelf is empty.</p>. A few details of the page are worth naming. The stripes use count, not index, so they stay correct when the loop starts at a begin other than 0. The first and last classes are the clean way to put a border on the edges of a list; no loop counter has to be compared with the size. The row number is the count too. And the second loop is the standard separator idiom, with the comma printed for every round except the last one. A zebra pattern with CSS (tr:nth-child(even)) needs no JSP at all and is the better choice for a plain table, but a class on the row is what a page needs when the stripes depend on something other than the position, such as a group boundary.

A catalogue of six books fits on a page; a catalogue of six thousand does not. The two designs below differ in where the slice is taken, and the difference decides whether the application scales.

c:forTokens splits a string and repeats its body once per token. It has the same begin, end, step, var and varStatus attributes as c:forEach, with two more that matter: items is the string, and delims is the set of delimiter characters.

Source: Jakarta Standard Tag Library 3.0 — c:forTokens

The tokens come from a java.util.StringTokenizer built with items and delims, as the specification states. Two properties follow from that. delims is a set of characters, not a separator string, so delims=", " splits at a comma and at a space and not at the two characters together. And a token is "a maximal sequence of consecutive characters that are not delimiters": two delimiters in a row do not produce an empty token between them. The empty field in scifi, classic;cyberpunk,,romance disappears, and so does the space after the first comma, because the space is a delimiter too.

Source: Jakarta Tags 3.0 tag reference — c:forTokens

The range and step lines show that begin, end and step count tokens, and the null delims line shows the single token. Leaving delims out is not a null, it is a mistake the translator reports: According to the TLD or the tag file, attribute [delims] is mandatory for tag [forTokens] (observed). In the Bookshelf the tag fits the places where one column holds a small list: a tags or keywords column, a space separated CSS class list, a path split at /. For anything where an empty field is meaningful, such as a CSV row with a blank column, c:forTokens is the wrong tool: the fn:split function also drops the empty field (fn:split('a,b,,c', ',') gave [a][b][c] in the same run), and real CSV needs a parser in Java, not a tag. The JSTL Functions page of this section covers split and join.

A loop inside a loop is the normal way to show grouped data. The servlet builds a Map<String, List<Book>>; the outer loop walks the entries and the inner loop walks each entry’s list. Each loop has its own varStatus, which is how a heading can say "1. fiction" and the rows below it "1.1", "1.2" and so on.

Source: Jakarta Standard Tag Library 3.0 — c:forEach

(The view uses trimDirectiveWhitespaces, which is why the output has no blank lines.)

The variables var and varStatus are exposed in page scope with "nested visibility": they are there while the body runs and gone after the end tag. The specification adds a warning that matters for names. The nested variable always goes in page scope, and a variable with the same name in another scope may or may not be affected, depending on the container, which is why page authors should avoid the same name in different scopes. On Tomcat 11.0.26 with the 3.0.1 implementation the behaviour is the following, all observed.

Source: Jakarta Standard Tag Library 3.0 — c:forEach, note on nested visibility

The loop used the name b while a page-scope b already existed, and when the loop ended the page-scope variable was gone: it was not restored to "outer value". The request-scope b was untouched. The same thing happens when two loops nest and reuse a name, which is an easy mistake in a copy-pasted template:

Source: Jakarta Standard Tag Library 3.0 — c:forEach, note on nested visibility

The inner loop overwrote x and, when it finished, removed it, so the outer x is empty after the inner loop although the outer loop is still running. Choose distinct names for every loop in a view, including the varStatus names, and a var name that no other attribute uses.

The specification has a section for items written as a deferred expression, #{customer.children}. The reason is Jakarta Faces: a component such as h:inputText inside the loop needs the iteration variable as a deferred value with the right index, and the tag can only provide that when it sees the original expression. The specification also notes that the number of items must be the same when Faces builds the component tree and when the loop runs. In a plain JSP page there is no such component, and an immediate ${books} is what to write. For the record, items="#{books}" is accepted by the 3.0.1 implementation on Tomcat 11.0.26 and prints the same six books (observed: 123456 for ${b.id}), so a deferred items does not fail in a JSP page, but it gains nothing there.

Source: Jakarta Standard Tag Library 3.0 — 6.1.6 Deferred Values

c:forEach implements jakarta.servlet.jsp.jstl.core.LoopTag, and its status object is the LoopTagStatus described above. This is what the specification calls tag collaboration: a custom tag in the body of the loop can find the loop with TagSupport.findAncestorWithClass(this, LoopTag.class) and ask it for the current item (getCurrent()) or the status (getLoopStatus()) without the page author passing anything. The specification’s example is a pair of tags, acme:odd and acme:even, that print their body only on odd or even rounds, replacing a c:choose on ${status.count % 2 == 0}. The same interface lets a developer write a new iteration tag that collaborates in the same way: the base class LoopTagSupport does the bookkeeping of begin, end, step, var and varStatus, and the subclass only supplies the items (prepare(), hasNext() and next()). The LoopTag Javadoc warns not to confuse the interface with the Pages interface jakarta.servlet.jsp.tagext.IterationTag; they are different things. How to write a tag that uses either one is the subject of the classic and SimpleTag custom tag pages of this section.

Source: Jakarta Standard Tag Library 3.0 — 6.1.5 Tag Collaboration

A loop tag is not the only way to turn a collection into markup, and sometimes it is not the best one.

The EL route deserves a worked example, because it removes the need for a helper in the servlet when a view wants a derived list. A stream is not a supported items type (see unsupported types), but an EL pipeline that ends in toList() is a List, and c:forEach accepts it.

Source: Jakarta Expression Language 6.0 — 2.3.1 Streams and Pipelines

The comparator returns an int, so a - of two prices would be coerced to an integer and lose the fraction; the conditional returns -1 or 1 instead. Stream pipelines in a view are best kept this short; anything longer is business logic that belongs in the servlet, which is argued, with every operation, on the EL lambdas, collections and streams page.

For comparison, this is the same loop as a scriptlet, the form that c:forEach replaced. It is shown only as a "before" snippet: the scriptlet needs the page directive’s import, an unchecked cast, a loop that is open across three scriptlet blocks and output through <%= %>, and it cannot be styled or maintained by a front-end developer.

Source: Jakarta Pages 4.0 — 1.12.2 Scriptlets

The scriptlet works, which is why so many old pages still have one, but the tag form is shorter, type-safe in the sense that no cast is written, and can be switched to by setting scripting-invalid in the jsp-config of the application. The scripting page of this JSP section covers the migration.

Two things go wrong with loops in views, and both have the same cause: letting the request decide how much work the page does.

Source: Jakarta Standard Tag Library 3.0 — Appendix B Changes

The old URI http://java.sun.com/jsp/jstl/core still resolved on this stack: the 3.0.1 JAR ships the TLDs of earlier releases (c-1_2.tld for http://java.sun.com/jsp/jstl/core and the JSTL 1.0 files c-1_0.tld and c-1_0-rt.tld), as well as the current c.tld with the URI jakarta.tags.core. That is an implementation courtesy, not something the 3.0 specification promises. The http://xmlns.jcp.org/jsp/jstl/core URI, the JSF-era namespace that Facelets (JSF 2.2 and later) used and never a JSP taglib URI, does not resolve: JSP pages of Java EE 7 and 8 still used http://java.sun.com/jsp/jstl/core. Use jakarta.tags.core in new pages.

The books this section draws on are about JSTL 1.0, 1.1 and 1.2 on Servlet 2.3 to 3.x containers. Their description of the loop tags is still correct as behaviour; what has moved is everything around it.

Source: Jakarta Standard Tag Library 3.0 — B.2 Changed between 2.0 and JSR-52

Publisher pages of the two books that cover the loops are listed in the references for readers who want the original explanations; their code needs the changes in the table before it will run on Tomcat 11.