JSP Documents (XML Syntax)

A JSP page in the usual syntax is a text file with some <% %> and ${ } islands. Most of what authors write is HTML, and HTML tolerates unclosed <br>, unquoted attributes and bare ampersands, so the usual syntax makes no attempt to be XML. That is fine for HTML, and a problem when the output must be XML: XHTML served as application/xhtml+xml, SVG, Atom or RSS feeds, a SOAP-era web-service reply, or a document that goes on to an XSLT pipeline. A JSP document keeps the page well-formed by construction, because a parser checks the file before any Java is generated.

The specification lists the intended uses: pass a document straight to the container, manipulate it with XML-aware tools, generate it from another XML document with a transformation, or generate it programmatically. It also separates two audiences. JSP documents are for page authors. The XML view is internal to the container and is of interest only to tag library authors and container implementors, because that is what a TagLibraryValidator sees (see The XML View).

Source: Jakarta Pages 4.0 — 6.1 Overview of JSP Documents and of XML Views

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

The container must decide, for every file it treats as a JSP page, whether the file is in the usual syntax or in XML syntax. Section 6.2.1 gives three rules and a strict order of precedence.

If a file is identified as a JSP document and is not well-formed and namespace-aware XML, translation fails. Nothing is sent to the client except the 500 error page.

The web.xml below belongs to the Bookshelf of this page (property groups are covered on the Configuration and Property Groups page). The first group switches one file back to the usual syntax even though its extension is .jspx, which is the example the specification itself uses for false; the second makes every .xhtml file a JSP document. Both use the Servlet 6.1 descriptor.

Source: Jakarta Pages 4.0 — 3.3.7 Denoting XML Documents

Source: Jakarta Pages 4.0 — 6.2.1 Identifying JSP Documents

A .xhtml file that is not a valid JSP page in the usual syntax shows the effect. books.xhtml is a JSP document only because of the second group:

legacy.jspx contains an unclosed <br> and a taglib directive, both illegal in XML. With <is-xml>false</is-xml> it is translated as a normal page and the container never runs an XML parser on it:

Source: Jakarta Pages 4.0 — 3.3.1 JSP Property Groups

The smallest useful JSP document is a template XML element tree with one action inside. The Bookshelf servlet forwards the list of books to /WEB-INF/views/books-xml.jspx (the servlet is the one from the Getting Started page, with a parameter that selects the view for these experiments). The page below is XHTML 1.0 Strict with a DOCTYPE generated by jsp:output, a content type chosen by jsp:directive.page and the Jakarta Tags core library bound with xmlns:c.

Several things happened that a page in the usual syntax would not do. The container added an XML declaration because there is no jsp:root. It inserted the DOCTYPE immediately before the first element, from the three jsp:output attributes. It removed every whitespace-only text node (the indentation and line breaks between elements), which is why the output is one line. The jsp prefix is bound to http://java.sun.com/JSP/Page on the root element, and the prefix itself is irrelevant: only that URI marks an element as a standard action. The jsp namespace declaration does not appear in the output, while the XHTML namespace does, because the html element is template data and is passed through.

Source: Jakarta Pages 4.0 — 6.4.1 Example: A Simple JSP Document

Source: Jakarta Pages 4.0 — 5.13 jsp:output

A page in the usual syntax imports a tag library with <%@ taglib prefix="c" uri="..." %>. A JSP document cannot, because <%@ is not XML, so the taglib directive is not allowed in a JSP document and libraries are imported with xmlns attributes. Standard actions are recognized by namespace, never by prefix.

Four rules decide what happens to other elements.

An unbound prefix is a different matter. The XML parser has no idea what c: means, so a document that uses c:forEach without an xmlns:c fails before JSP processing starts. This is the most common first error after copying a page from the usual syntax:

A default namespace also changes what unqualified elements mean. If xmlns="..." pointed at a tag library, unqualified elements would become invocations of its tags, a trap the specification points out in its namespace-aware example (6.4.2). The Bookshelf pages bind XHTML as the default namespace and give every library an explicit prefix.

Source: Jakarta Pages 4.0 — 6.3.1 Namespaces, Standard Actions, and Tag Libraries

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

jsp:root is the optional root element of a JSP document. It was mandatory in JSP 1.2, and the specification expects most documents in Pages 4.0 not to use it. It matters for two reasons: it marks a file as a JSP document without the .jspx extension or a property group, and it lets a document produce something other than a single XML document: a sequence of XML documents, or non-XML content such as plain text. It may appear only as the root of a JSP document or of a tag file in XML syntax, or the translation fails.

Tomcat 11.0.26 checks the version and lists the accepted values in its message: Invalid version number: [5.0], must be "1.2", "2.0", "2.1", "2.2", "2.3", "3.0", "3.1" or "4.0" (observed with version="5.0").

The second use is easiest to see with two root-level elements. A real XML document has one root, so a document without jsp:root could not do this; with it, the two book elements are emitted as a sequence, and, by default, without an XML declaration:

The same mechanism generates non-XML content. The Bookshelf export below is a semicolon-separated text file. There are no template elements, only jsp:text and an action. The line break is inside the jsp:text body, so it is kept verbatim.

CSV cells that contain ;, quotes or line breaks need quoting, and a title that starts with = is interpreted as a formula when the file is opened in a spreadsheet. A real export belongs in a servlet with a CSV library; the example shows only the mechanism.

Source: Jakarta Pages 4.0 — 6.3.2 The jsp:root Element

Source: Jakarta Pages 4.0 — 6.4.3 Example: Generating non-XML documents

jsp:output controls the prolog of the generated document and exists only in the XML syntax. It cannot have a body and may appear in JSP documents and in tag files in XML syntax. In a page in the usual syntax it is a translation error; Tomcat reports <jsp:output> must not be used in standard syntax (observed).

The DOCTYPE is determined at translation time and written just before the first output element. The format is <!DOCTYPE root PUBLIC "public" "system"> when a public identifier is present and <!DOCTYPE root SYSTEM "system"> otherwise. Repeating an attribute with a different value is a translation error. The author is responsible for the URI being valid.

Three Bookshelf variants show the declaration rules. root-decl.jspx forces the declaration on a document that has a jsp:root; noroot-omit.jspx removes it from one that does not:

Asking for a DOCTYPE without a system literal is rejected at translation time, as the specification demands:

A DOCTYPE written in the source file is something else: it makes the container validate the document (see DTD Validation and Entities). jsp:output only writes a DOCTYPE into the response.

Source: Jakarta Pages 4.0 — 5.13 jsp:output

Source: Jakarta Pages 4.0 — 6.3.3 The jsp:output Element

Only the page and include directives (see Directives) have XML elements that work in an ordinary JSP document; the others belong to tag files.

jsp:directive.include is how a document reuses a fragment. The fragment below is itself XML with its own default namespace, which is the safe style, because the specification resets the default namespace to "" at the root of an included XML segment so that the includer’s default namespace is not inherited:

Note the redundant xmlns on the fragment’s element and the line break after it in the output (observed). For request-time inclusion of another resource, jsp:include is used exactly as in the usual syntax; it is a standard action and needs no change.

A taglib directive in a document fails at parse time, because <%@ is not legal XML:

Source: Jakarta Pages 4.0 — 6.3.4 The jsp:directive.page Element

Source: Jakarta Pages 4.0 — 6.3.5 The jsp:directive.include Element

Source: Jakarta Pages 4.0 — 1.10.5 Including Data in JSP Pages

Declarations, scriptlets and expressions have exactly one legal form in a JSP document, the XML elements. The old <% %> forms are not XML, so a scriptlet in a document is a parse error:

The XML elements have no attributes, and their bodies hold the code. The code must itself be well-formed text, so < and & are written as < and & or wrapped in a CDATA section.

The one place the XML syntax invents new notation is the request-time attribute value of a custom action. The usual syntax writes <c:out value="<%= expr %>"/>, which is not well-formed because of the < in the attribute. In a JSP document the same value is written value="%= expr %": without the angle brackets, and with optional white space around the expression. This notation applies to custom actions only. On a template element such as <a href="%= url %"> the text is not an expression and is passed through verbatim; the specification’s workaround is to build the element from jsp:text and jsp:expression. Modern pages do not need either: href="${url}" is an EL expression in both syntaxes.

Everything that applies to scripting in the usual syntax applies here too: <scripting-invalid>true</scripting-invalid> in a property group makes the container reject these elements, and the better replacement is EL, JSTL and tag files. The XML view section below turns the same idea into a validator that works at the level of a whole application.

Source: Jakarta Pages 4.0 — 6.3.7 Scripting Elements

Source: Jakarta Pages 4.0 — 10.1.11 Request-Time Attribute Expressions

Source: Jakarta Pages 4.0 — 3.3.3 Disabling Scripting Elements

A page in the usual syntax passes any text it does not understand through to the response. A JSP document passes structured template data: XML elements that are not actions, after the parser has processed them, plus the content of jsp:text. The semantic model does not change; only how the data is described. The sections below follow the rules in section 6.2.3 and 6.3.9.

JSP documents use XML’s own encoding rules instead of the usual-syntax page-encoding rules. The specification’s appendix B says the page encoding of a JSP document is determined as in appendix F.1 of XML 1.0 (byte-order mark or the encoding pseudo-attribute of the XML declaration, UTF-8 by default), and the file is read with that encoding. There is no pageEncoding to maintain for a document in XML syntax.

The source was read as Latin-1 because its declaration says so, and the response is re-encoded in UTF-8; the declaration the container generated names the response encoding, not the source encoding. The same is true of the content type. Without a contentType attribute the initial response content type is text/html for pages in the usual syntax and text/xml for JSP documents, and the initial response encoding for documents is UTF-8 (section 4.2). All the Bookshelf pages above show text/xml;charset=UTF-8 for that reason. XHTML served as text/xml is rendered as XML, not as an HTML page; set application/xhtml+xml with jsp:directive.page (as books-xml.jspx does) if the browser should treat it as XHTML, or use the default-content-type property of a property group for a set of pages.

The XML view character encoding (the general rules are on the Character Encoding page), the encoding used when the view is externalised to a validator, is always UTF-8.

Source: Jakarta Pages 4.0 — B.1 Detection Algorithm for JSP pages

Source: Jakarta Pages 4.0 — 4.2 Response Character Encoding

Source: Jakarta Pages 4.0 — 4.4 XML View Character Encoding

A JSP document that has a DOCTYPE declaration must be validated by the container during translation, and failures are translation errors like any other. Pages 4.0 requires only DTD validation; containers should not validate against other schema languages. This is also how a document gets custom entities: an internal DTD subset defines them. The catch is that validation also applies to every element and attribute. A DOCTYPE without declarations for the document’s elements, and for the xmlns attributes, fails. The specification warns that a DTD must make explicit provision for the jsp prefix and its xmlns:jsp attribute if the document is going to use JSP elements.

The same file with <!DOCTYPE p [ <!ENTITY author "Frank Herbert"> ]> and nothing else fails with Element type "p" must be declared. (observed), because the presence of a DOCTYPE turns validation on. Prefer a document with no DOCTYPE and put the DOCTYPE in the output with jsp:output. The response then contains the identifier but the container does not try to fetch and validate against the DTD.

Source: Jakarta Pages 4.0 — 6.2.4 JSP Document Validation

The same rules apply to tag files. A tag file in XML syntax has the extension .tagx, a .tag file is never in XML syntax, and jsp:root can (but need not) appear in a .tagx and cannot appear in a .tag. The tag directives become jsp:directive.tag, jsp:directive.attribute and jsp:directive.variable. Two differences from JSP documents: the default of omit-xml-declaration is always yes, and the tag directive cannot have a pageEncoding attribute (the encoding comes from XML); using it is a translation-time error.

Tag files live under /WEB-INF/tags (or /META-INF/tags in a JAR), and the directory in urn:jsptagdir: and the document needs no taglib directive. Tag files in general, with .tag syntax, are the subject of the tag-files page of this part.

Source: Jakarta Pages 4.0 — 8.6 Tag Files in XML Syntax

Every JSP page, in either syntax, has an XML view: an XML document derived from it by a fixed mapping. The container does not run the page from it. Its job is validation. When a tag library declares a <validator> in its TLD, the container hands the validator a jakarta.servlet.jsp.tagext.PageData object whose getInputStream() returns the XML view, and the validator returns ValidationMessage objects for anything wrong. For a JSP document the transformation is small. For a page in the usual syntax it is a full rewrite.

Because a page in the usual syntax has all of its template text collapsed into jsp:text elements, a validator sees no detail about its HTML. A JSP document keeps its template elements visible, so a validator (or an XSLT transformation) can check, for example, that a page contains exactly one h1. That is the actual advantage of writing in XML.

jsp:id is an attribute that the container must support on every element of the view, in the namespace of the JSP standard actions with any prefix that the container picks, and it is unique within a view. A validator puts it in ValidationMessage.getId() so the container can map the problem back to a location. It is not available to page authors.

Source: Jakarta Pages 4.0 — 10.1 XML View of a JSP Document, JSP Page or Tag File

Source: Jakarta Pages 4.0 — 10.1.13 The jsp:id Attribute

Source: Jakarta Pages 4.0 — 10.2 Validating an XML View of a JSP page

The scripting-invalid property group turns scripting off for a set of files, one URL pattern at a time. The XML view lets an application go further and enforce its own rule in one place, with an error message of its own and with a line reference. The validator below parses the view with a namespace-aware SAX parser and reports every jsp:declaration, jsp:scriptlet and jsp:expression, whichever syntax the page used. The validator reports the container-assigned jsp:id as the location.

The TLD is the same shape as xmlview.tld, with the class name replaced and <uri>https://example.org/bookshelf/no-scripting</uri>;. A clean document and two offenders, one in each syntax, show the effect:

Tomcat printed the jsp:id (5 and 6) as the location, and rejected the page when it was translated, so the error appears on the first request of a page, or at precompilation. The rule applies to a page only if the page imports the library, so a real application would add the library to every view through a prelude in a property group (include-prelude). The parsing uses plain JAXP, and the same view could be handed to an XML Schema validator or an XSLT stylesheet.

Source: Jakarta Pages 4.0 — 7.4.1.2 Validator Classes

Source: Jakarta Pages 4.0 Javadoc — ValidationMessage

The XML syntax itself has been stable since JSP 2.0. Section 6.5 of the specification, a non-normative section, still lists two wished-for features that nobody has implemented: producing XML natively (a node tree instead of text) and XML Schema and XInclude support.

Source: Jakarta Pages 4.0 — Appendix C: Changes

Source: Jakarta Pages 4.0 — 6.5 Possible Future Directions for JSP documents

Web Development with JavaServer Pages (Manning, 2001, listed in the section bibliography) treats JSP documents and the XML view in its chapter on validating custom tag libraries, and JSTL in Action (Manning, 2003) spends its early chapters on the XML rules that JSP syntax follows. Both were written for JSP 1.2.