JSTL Functions

All the examples below are views of one WAR, deployed as g5jstlfunctions.war under the context path /g5jstlfunctions. A servlet mapped to /demo/* puts the same small object graph in the request and forwards to /WEB-INF/views/<name>.jsp; every listing below is one of those views (the page and taglib directives are shown once and left out afterwards), and every output is what curl printed.

Source: Jakarta Standard Tag Library 3.0 — Chapter 15, Functions: function tag library

The first title has two leading and two trailing spaces on purpose, and the third author has a middle initial: both are used below to show where the functions help and where they surprise.

An EL function is a public static Java method that a tag library descriptor (TLD) publishes under a name, so that an expression can call it as prefix:name(args). The Pages 4.0 specification (section 2.11) defines the mechanism: the function is qualified by the prefix of the tag library that declares it, the mapping is bound into the expression when the page is parsed, and the method is looked up in the function-class named by the TLD. Jakarta Tags 3.0 uses that mechanism to ship one library of general-purpose string and collection helpers.

The fn: library is the only part of JSTL that works outside a tag attribute: because it is an EL function it can be used anywhere an expression is allowed, in template text, in the attributes of standard and custom actions, in tag files and in the EL of JSP documents. It needs the taglib directive (or xmlns in a JSP document) like every other library, and without it the page fails at translation time.

Source: Jakarta Pages 4.0 — The taglib Directive

The diagram shows why two different kinds of mistakes fail in two different places. A function that does not exist in the TLD, or is called with the wrong number of arguments, is rejected when the page is translated, so the first request to that JSP fails and the error names the function. A call whose arguments cannot be coerced to the declared parameter types fails when the request is processed, with an ELException whose message starts with Problems calling function. The sibling Tag Library Descriptors & EL Functions page shows how the same mechanism is used to publish a function of your own.

The specification groups the functions by domain: length, case, substring, trimming, replacement, searching, splitting and joining, and XML escaping. The table lists every function with its declared signature (from fn.tld), the null rule of the specification and the verified behaviour. In every function a null String argument is processed as the empty string, so the library never throws a NullPointerException for a missing value, which is the single biggest difference from calling the same method on a String through EL 6.0.

Source: Jakarta Standard Tag Library 3.0 — String manipulation functions

Source: Jakarta Standard Tag Library 3.0 — fn:length

The view below calls every function on the data of the Bookshelf. It uses text/plain so that the output can be read as printed, and trimDirectiveWhitespaces so that the directive lines leave no blank lines.

Printed by curl http://localhost:18080/g5jstlfunctions/demo/all:

Source: Jakarta Standard Tag Library 3.0 — fn:contains

Source: Jakarta Standard Tag Library 3.0 — fn:escapeXml

Two details of that output matter later. fn:length(stock) counts the entries of a Map, because a map is one of the types c:forEach can iterate; and fn:escapeXml produced " for the double quote and ' for the apostrophe, the numeric references that c:out also produces, not the named " and '.

A feature that JSTL 1.0 lacked and that Tags 3.0 section 15.1.1 explains is the size of a collection: Collection.size() is not a JavaBeans property, so ${books.size} fails, and before EL 3.0 there was no way to call it. fn:length takes anything that c:forEach can loop over and returns its size, and for a String it returns the number of characters (UTF-16 code units, as String.length()). It also accepts an Iterator or an Enumeration, because c:forEach does (the sequence is read to the end).

Printed: array=3 map=2 null=0 empty=0 (a String[] of three tags, a Map of two entries, a null and an empty string).

Source: Jakarta Standard Tag Library 3.0 — The length function

The rule is the one of c:forEach, so a record or a bean is not accepted. The failure shows its origin in the stack trace (Functions.length), not in the page:

Source: Jakarta Standard Tag Library 3.0 — fn:length

fn:trim, fn:toUpperCase and fn:toLowerCase delegate to the String methods of the same name. The Bookshelf’s first title carries two spaces on each side; trimming it before comparing, sorting or building a URL is the most common use of the library, and the specification’s own example trims a value before putting it in c:url. A trimmed value used as the value of a parameter avoids the + signs that the encoder would otherwise produce for the spaces.

Printed output (the session identifier is added by c:url on the first request of a client that has not sent a cookie yet, a rewriting rule that the JSTL URLs, Imports & Redirects page of this section explains):

Source: Jakarta Standard Tag Library 3.0 — String manipulation functions

The searching functions answer yes or no questions. fn:contains and fn:containsIgnoreCase are the functions behind a simple filter; fn:startsWith and fn:endsWith suit prefixes such as an ISBN group or a file extension, and fn:indexOf is the building block for the cutting functions below. All of them treat an empty second argument as matching at the start (or end), and all of them treat null as the empty string, which gives results that differ from a null-safe String call:

Source: Jakarta Standard Tag Library 3.0 — fn:containsIgnoreCase

fn:containsIgnoreCase upper-cases both arguments with the default locale of the JVM, so on a JVM whose default locale is Turkish or Azerbaijani the letters i and I do not match each other (the same dotted and dotless i rule as String.toUpperCase()); set the default locale of the container explicitly if the pages compare locale-sensitive text.

fn:substring(string, begin, end) follows String.substring with one major difference: it never throws. The specification says that a begin below 0 becomes 0, an end below 0 or beyond the length becomes the length, and an end before begin or a begin beyond the last character gives the empty string. The specification suggests -1 as the end for "to the end of the string", and Tomcat behaves exactly so:

Source: Jakarta Standard Tag Library 3.0 — fn:substring

The function has exactly three parameters. Calling it with two, as the introductory example of chapter 15 does (see Pitfalls and Error Messages), is a translation error, not a shortcut for "to the end".

fn:substringBefore and fn:substringAfter cut around the first occurrence of a delimiter and return the empty string when the delimiter is absent, so they cannot tell "nothing after the delimiter" from "no delimiter". With an empty delimiter substringBefore returns "" and substringAfter returns the whole input, consistently with fn:indexOf returning 0 for an empty substring.

Source: Jakarta Standard Tag Library 3.0 — fn:substringAfter

The specification’s example of extracting the text between brackets combines fn:substring with fn:indexOf. On the Bookshelf it extracts the year from a display string:

Printed: 1984.

Source: Jakarta Standard Tag Library 3.0 — String manipulation functions

fn:replace replaces every occurrence of a literal substring. It is not a regular expression, so a dot is a dot; the replaced text is not scanned again, so replace('aaa','aa','a') gives aa, not a; an empty before returns the input unchanged; and a null after removes the matches.

Source: Jakarta Standard Tag Library 3.0 — fn:replace

fn:split returns a String[] and breaks the string with java.util.StringTokenizer. Two consequences are easy to get wrong. The second argument is a set of delimiter characters, not a delimiter string, so fn:split('a, b;c', ',; ') gives three tokens. And consecutive delimiters do not produce empty tokens, so fn:split('a,,b', ',') has two elements where String.split(",") has three. An empty input or an empty delimiter set returns an array with a single element, the input.

Source: Jakarta Standard Tag Library 3.0 — fn:split

The array that fn:split returns is an ordinary value, so it plugs into c:forEach and fn:join. A c:forEach over the words of a title, with the varStatus properties of the iteration page, and a join that re-assembles a split string:

Source: Jakarta Standard Tag Library 3.0 — fn:join

fn:join is declared for String[], and that is what it needs. A String[] (the tags attribute) works, with a null array giving the empty string and a null separator giving no separator at all (sci-ficlassicaward). A List<String> does not: EL does not coerce a list to an array, so the call fails when the request is processed, in the way described in Pitfalls and Error Messages. Joining a list is one of the cases where an EL 6.0 method call is the better tool (see EL 6.0 Method Calls and the Role of the Functions Today).

fn:escapeXml(string) returns the string with the five markup characters replaced, with exactly the conversions of c:out when its escapeXml attribute is true. The specification introduces it as the concise alternative to c:out when the escaped value is needed as an expression and not as output, for example as the value of an attribute of a custom action, and it uses it to avoid cross-site scripting when echoing a request parameter. The two forms produce the same text; combining them escapes twice:

Source: Jakarta Standard Tag Library 3.0 — fn:escapeXml

Source: Jakarta Standard Tag Library 3.0 — c:out

The last two lines are the security point of the page. Plain EL, ${param.q}, writes the request parameter into the page as it is, and <script>"x in a quoted attribute closes the attribute and opens a tag; fn:escapeXml makes the same value inert. Remember what the function is: an HTML (and XML) text and quoted-attribute encoder. It does not protect a value placed in a <script> block, in an event handler such as onclick, in a style attribute, in a URL, or in an unquoted attribute. In a JavaScript string it leaves the backslash alone (a Windows path C:\temp\new is printed as C:\temp\new, which JavaScript reads with a tab and a newline in it), and the HTML references it produces (') are not decoded inside a script element. For those contexts use c:url and c:param for URLs, send data for JavaScript as JSON and let the script read it, or use a context-aware encoder library such as the OWASP Java Encoder (org.owasp.encoder:encoder-jakarta-jsp 1.5.0), which provides separate functions for HTML content, attributes, JavaScript, CSS and URLs.

Source: Jakarta Standard Tag Library 3.0 — fn:escapeXml

Whether to use fn:escapeXml or c:out is mostly a matter of where the result goes. For output, c:out is clearer, has a default attribute and is the form that auditors search for. For an attribute of another action, fn:escapeXml avoids the c:set and jsp:attribute detours that the specification shows. Neither is applied automatically: Jakarta Pages 4.0 has no setting that escapes EL output, so every value that comes from a request or a database has to pass through one of them. The page on syntax, comments and escaping shows the other places where text reaches the page, and the EL configuration page lists the EL settings that do exist.

The view below is a realistic use of the functions: a catalogue that shows the number of books, filters by a trimmed query parameter, builds a CSS-friendly slug and a short excerpt, and lists the tags. It is the only example of the page that uses HTML output, and it escapes every value that comes from data.

curl http://localhost:18080/g5jstlfunctions/demo/list printed:

With ?q=dune only the first item remains (the filter trims the query and ignores case), and a query that is only markup, such as ?q=%3Cscript%3E, matches nothing and prints nothing because the query is only compared, never output.

Source: Jakarta Standard Tag Library 3.0 — fn:containsIgnoreCase

The view also shows a limit of the library. The third author is "Ursula K. Le Guin", and fn:substringAfter(author, ' ') cuts at the first space, so the "surname" is K. Le Guin. There is no substringAfterLast, lastIndexOf, startsWith with an offset or regular expression anywhere in the library: such rules belong in Java code (the servlet or a view model) and not in the page.

The functions were designed when EL could not call methods. Since EL 2.2 (Pages 2.2) and in EL 6.0 any public method of an object can be called from an expression, and the Java String methods are available on every string, so many of the functions have a direct equivalent. The equivalents are not identical: a method call on a null value yields an empty result, as ${none.contains('x')} printing nothing, but a null as an argument is passed to the Java method and fails.

Source: Jakarta Expression Language 6.0 — Resolution of model objects and their properties or methods

The practical rule is therefore: use fn: where the value may be null or of an unknown type (a request parameter, an optional bean property, a collection of unknown kind), for fn:escapeXml, for fn:length and for code that must keep working in a page that is also compiled by a tool that does not support EL method calls. Use method calls where the types are known and a richer operation is needed (String.join, strip, collections, streams, the topic of the EL lambdas, collections and streams page). A page that mixes both styles is common and works; the one inconsistency to keep in mind is the null handling.

Source: Jakarta Standard Tag Library 3.0 — String manipulation functions

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

Source: Jakarta Standard Tag Library 3.1 (under development)

Moving a page from Java EE to Jakarta EE therefore changes only the taglib URI (and only if the old one is to be left behind): http://java.sun.com/jsp/jstl/functions still works, but it is a taglib identifier only, not a reachable web page, and new code uses jakarta.tags.functions. The javax.servlet.jsp.jstl.* Java API, if used in custom code, has to change to jakarta.servlet.jsp.jstl.*.

The specification’s own examples need attention, and the discrepancies were found by running them.