Syntax, Comments & Escaping

The specification defines a page as a sequence of elements and template data (usually called template text). An element is an instance of an element type that the container knows; template text is everything else, "anything that the JSP translator does not know about". The translator copies template text to the response, in order, and replaces each element with whatever that element produces. Nothing in template text is escaped, interpreted or validated. It can be HTML, XML, CSV, JSON or a plain-text mail, which is why the same technology serves all of them.

There are three element types, and each has its own syntax.

Source: Jakarta Pages 4.0 — 1.3.2 Element Syntax

The first example is the smallest useful Bookshelf page. It contains one directive (page), one directive (taglib), one standard-library action (c:forEach), EL expressions in template text, one scripting expression and a lot of plain HTML template text.

Source: Jakarta Pages 4.0 — 1.3.1 Elements and Template Data

A request for /g3syntax/elements.jsp returned HTTP 200 with the body below.

Three things are visible in that output. The two directives produced no text of their own, but the line breaks after them are template text and were copied (the first two empty lines). The c:forEach body ran three times, and every iteration copied the line break before and after <li> as well, which explains the blank lines between items. Finally ${b.title} and <%= 1 + 1 %> were replaced by their values. The whitespace section below shows how to control those blank lines.

The translator decides what it is looking at by the first characters of each construct and applies the first rule that matches (the specification calls this the greedy algorithm and gives the full EBNF in section 1.3.10). The rules, in the order of the grammar, are summarised in the figure.

The figure shows the decision the translator makes for every position in the file, and the last row is the important one: an HTML comment, an unknown tag such as <br>, a <script> block or a JSON document is simply template text. Two consequences follow. The container never validates your HTML, so a page can be malformed HTML or even not XML at all (<br> without a closing slash works), and a tag whose prefix was never declared is not reported either. With a taglib directive for c, a misspelled <c:foreach> is an error, but <cc:forEach var="b" items="${books}"> with an undeclared prefix is template text that goes to the browser, and the ${books} inside its attribute is still evaluated (the request for prefix.jsp returned the whole list printed inside the attribute). The pitfalls table repeats the point.

Source: Jakarta Pages 4.0 — 1.3.9 JSP Documents

The response was <p>Not well-formed XML<br>but fine as a JSP page   Emma, with the entity and the unclosed paragraph untouched. A JSP document, covered below, is the opposite case: the file is parsed as XML first and must be well-formed.

An EL expression in template text, such as ${shopName}, names a scoped variable: an attribute stored in one of the four scopes of a page, page, request, session and application. A bare name is looked up in that order, and the first scope that holds it wins; a prefixed name (${requestScope.label}, ${applicationScope.shopName}) reads one scope only. The page below stores a variable called label in all four scopes with c:set, prints the bare name, prints the four prefixed forms, removes the page-scope copy with c:remove and prints the bare name again. The full rules for scopes, the session attribute of the page directive and the lifetime of each scope are on Implicit Objects & Scopes.

Source: Jakarta Pages 4.0 — 1.8.3 Implicit Objects

The bare name found the page-scope copy first, and found the request-scope copy once the page-scope copy was gone (observed on Tomcat 11.0.26). The last line shows the shop name stored by the context listener in application scope, found by the bare name because no narrower scope holds shopName. Because a bare name can be shadowed by a narrower scope, a variable that matters (a user, a permission, a flag) is better read with its scope prefix.

The rest of section 1.3 is a short list of rules inherited from XML. They explain most of the translation errors a beginner meets.

Source: Jakarta Pages 4.0 — 1.3.3 Start and End Tags

Source: Jakarta Pages 4.0 — 1.3.7 Valid Names for Actions and Attributes

The jsp:attribute and jsp:body actions deserve a short example, because they are the one place where a page passes markup as an attribute value. Both pages below were written to fail, so that the message is recorded. The first sets value twice, the second spells the tag name with a capital letter.

Source: Jakarta Pages 4.0 — 1.3.6 The jsp:attribute, jsp:body and jsp:element Elements

Tomcat answered HTTP 500 with a JasperException. The message of the first was /err-attrdup.jsp (line: [3], column: [0]) The attribute [value] specified in the standard or custom action also appears as the value of the name attribute in the enclosed jsp:attribute; the message of the second was /err-case.jsp (line: [3], column: [0]) No tag [Out] defined in tag library imported with prefix [c]. The line and column point at the start tag of the element, and the message is produced at translation time, so no output of the page is sent when it appears.

A scripting element must be closed in the file that opened it. The page below includes a fragment that opens a scriptlet and never closes it, hoping that the including page supplies the %>.

Source: Jakarta Pages 4.0 — 1.3.3 Start and End Tags

The message was /err-split-file.jsp (line: [2], column: [0]) /WEB-INF/fragments/open.jspf (line: [1], column: [3]) Unterminated [<%] tag: Jasper names the including page and the fragment, with the position inside the fragment. The same message, with the page itself in place of the fragment, appears for a file that ends in the middle of a scriptlet (err-unclosed.jsp).

Every element of the table above has a second spelling in XML syntax. The XML spellings exist so that a page can be well-formed XML (a JSP document, normally in a .jspx file) and can therefore be processed by XML tools. They are also legal inside an ordinary .jsp file in standard syntax, so a page can mix the two, although mixing is rarely a good idea.

Source: Jakarta Pages 4.0 — 6.2.2 Overview of Syntax of JSP Documents

The next page uses only the XML spellings in a .jsp file. It declares a counter, increments it, prints it and then writes template text with jsp:text, where the entity < is the XML way to write a less-than sign.

Source: Jakarta Pages 4.0 — 5.12 jsp:text

The response was three empty lines (the line breaks after the directive, the declaration and the scriptlet) followed by Hits: 1 and A < B and Dune. The entity was not decoded in the output: jsp:text passes its body through as template data, and in a .jsp file in standard syntax the body is not run through an XML parser. The same jsp:text line in a JSP document (text.jspx, the same three directive and text lines inside a root element) returned A < B and Dune, because the XML parser decodes the entity first. This is one of the differences between the two worlds, and the JSP Documents (XML Syntax) treats the XML side fully. The next example is a JSP document, catalogue.jspx, which produces XML.

Source: Jakarta Pages 4.0 — 6.4 Examples of JSP Documents

The response was the following. The xmlns:jsp and xmlns:c declarations are consumed by the container and removed; the whitespace-only text nodes between the elements are dropped, so the output has no blank lines; the XML comment is gone; and the CDATA content is emitted verbatim, which means that <raw & text> is not well-formed XML in the response. The last line shows both ways to produce a literal EL delimiter.

The XML spelling of a request-time attribute value, value="%= hits %", applies to custom actions. Tomcat 11.0.26 also rewrites it on a template element such as <a href="%= 1 %">, producing href=" 1 ", although section 6.2.2 of the specification says that on such an element it "does not represent a request-time attribute value" and should stay as written. Do not rely on either behaviour; write ${...} in attribute values of template elements, which means the same in both syntaxes.

A JSP document must be well-formed, so the standard-syntax scriptlet markers are a parse error there. The page err-doc-scriptlet.jspx is a document with a jsp:directive.page line followed by <% int x = 1; %>; Tomcat reported /err-doc-scriptlet.jspx (line: [4], column: [4]) The content of elements must consist of well-formed character data or markup. The XML parser, not the JSP translator, raises that error.

There are two purposes for comments in a JSP page: documenting the page itself, so that the text must not reach the browser, and producing a comment in the generated document, so that it must. The specification gives each its own syntax, and the scripting language adds a third. Choosing the wrong one is the commonest comment bug, and the wrong choice usually leaks something.

Source: Jakarta Pages 4.0 — 1.5 Comments

Source: Jakarta Pages 4.0 — 10.1.3 JSP Comments (XML view)

All three comment forms of a JSP page appear in the page below, together with a block that is commented out. The shop name in application scope is Bookshelf "Corner" & Co. on purpose, to show what happens to markup characters.

Source: Jakarta Pages 4.0 — 1.5.1.1 Generating Comments in Output to Client

Source: Jakarta Pages 4.0 — 1.5.1.2 JSP Comments

Only the HTML comment survives, and it contains evaluated data: the EL expression and the scripting expression were executed and the result is in the comment. Every visitor who selects "view source" sees it. The shop name is also unescaped, because EL in template text is never HTML-escaped (the escaping section below returns to this). Two rules of thumb follow.

A JSP comment cannot be nested. The first closing marker ends the comment, and the rest is template text:

Source: Jakarta Pages 4.0 — 1.5.1.2 JSP Comments

The response was A B --%>C: the comment ended at the first --%>, so the text B --%> (with its leading space) and the C that follows were copied as template text. For the same reason, a block that already contains a JSP comment cannot be commented out with another JSP comment: remove the inner comment first, or delete the block and let version control keep it. A comment that is not closed at all is a translation error, Unterminated [<%--] tag, reported at the opening marker (err-nested.jsp).

JSP has no single escape character. Section 1.6 lists a separate set of rules for each context in which the same characters mean something special, and the rules are small but easy to confuse. The table collects them. "EL enabled" means that the page evaluates EL, which is the default for a web application whose descriptor is Servlet 2.4 or later.

Source: Jakarta Pages 4.0 — 1.6 Quoting and Escape Conventions

The page below exercises the template-text and scripting rules, one numbered line each.

Source: Jakarta Pages 4.0 — 1.6 Quoting and Escape Conventions

Reading the output line by line: line 1 is evaluated; line 2 shows that \$ produces a literal ${...} that is not evaluated; line 4 does the same for the deferred syntax; line 5 is the EL string-literal trick and produces the text ${books[0].title}, as the specification’s example ${'${'} predicts; line 6 shows ${'}'}; line 7 shows that <\% is the only way to write <% in template text; line 8 shows that %\> becomes %> inside a scriptlet string (without the backslash the string would end the scriptlet); line 9 is an ordinary Java string escape, because inside a scripting element the text is Java; line 10 shows that a lone $ or # is left alone; and line 11 shows that there is no escape for \n, so a backslash in template text is simply a backslash. The specification notes that the quoting rules "do not allow for quoting special characters such as \n", and that the way to produce one is a Java expression.

Lines 3, 12 and 13 reveal a behaviour that the specification does not describe for template text. On Tomcat 11.0.26 a pair of backslashes before ${ in template text collapses to a single backslash and the expression is then not evaluated (line 3 printed \${books[0].title}, not \Dune), and each additional pair behaves the same way. Inside an attribute value the rule of the specification applies and \\${...} evaluates the expression (see attributes.jsp below). To print a backslash followed by an evaluated value in template text, produce the backslash with EL, ${'\\'}${books[0].title}, or avoid it.

JSP follows the whitespace rule of XML: whitespace in template text is not significant but is preserved. Directives and JSP comments produce no output, but the line break after them is template text, which is why the page of the first example begins with two empty lines. In a response that is HTML the extra lines are harmless; in a plain-text, CSV or XML response they can be fatal (an XML declaration must be the first characters of a file).

Source: Jakarta Pages 4.0 — 3.3.9 Removing Whitespaces from Template Text

The first page returned three empty lines (one per directive) and Books: 3 with its line break. The second returned one empty line and Books: 3 with no line break at all: template text that consists only of whitespace is removed, and the text \nBooks: (a line break and the word) is kept because it contains a non-whitespace character. That is the specification’s exact rule, and it explains why trimming leaves a leading line break and drops the trailing one. The configuration is the trim-directive-whitespaces element of jsp-property-group (false by default, no effect on JSP documents) or the trimDirectiveWhitespaces attribute of the page and tag directives. Tomcat adds a servlet parameter of its own, trimSpaces, with the values true, false, single and extended; single replaces such a run by one space and extended also removes leading and trailing whitespace of template text and collapses runs of whitespace and newlines to a single newline. The Tomcat documentation recommends single or extended to shrink responses in production. In a JSP document the rule is different and not configurable: text nodes that consist only of whitespace are dropped, except inside jsp:text, which is kept verbatim.

Source: Apache Tomcat 11 — Jasper 2 Configuration (trimSpaces)

The oldest JSP idiom, from the first generation of the technology, is to open a Java block in one scriptlet, write template text, and close the block in another. It is the reason why a scriptlet’s braces must balance across the page, and it is what a lot of existing code looks like, so the Bookshelf is shown in that form once and then in the current form.

Source: Jakarta Pages 4.0 — 1.3.2 Element Syntax (scripting elements) and chapter 9, Scripting

Source: Jakarta Standard Tag Library 3.0 — c:forEach

The scriptlet page produced three items, with class="classic" only on Emma (1815); the EL page produced the same three items, with an empty class="" on the others (the conditional expression always writes the attribute, whereas the scriptlet version omits it). The braces in the first page span three scriptlets, and a missing <% } %> shows up as a compile error of the generated servlet rather than a translation error: err-scriptlet-split.jsp (an if block that is never closed) produced Syntax error, insert "}" to complete Block against a line of the generated .java file. Scripting Elements (Legacy) explains why this style is discouraged and how to disable it with scripting-invalid; the example is here only because the books use it heavily and because its translation rules are the same as for every other element.

Source: Jakarta Pages 4.0 — 1.3.10 JSP Syntax Grammar (translation-error productions)

The rules on this page are old and have been stable. The change log in Appendix C of the Pages 4.0 specification lists no change to the core syntax, the comment forms or the quoting rules between JSP 3.1 and 4.0; the changes are the removals around them. The history that matters for syntax is:

Source: Jakarta Pages 4.0 — Appendix C, Changes

The books consulted for this section target JSP 1.2 and JSTL 1.0 (and Servlet 2.3); this page uses them only for the list of topics. What changed since:

Source: Jakarta Pages 4.0 — 6.2.2 Overview of Syntax of JSP Documents (jsp:root)

Source: Jakarta Pages 4.0 — 3.3.2 Deactivating EL Evaluation