Configuration and Property Groups

A web application can carry general JSP configuration in its deployment descriptor, WEB-INF/web.xml, in a single jsp-config element (a child of web-app) with two kinds of children: taglib elements, which map a tag-library URI to a tag library descriptor, and jsp-property-group elements, which attach properties to a set of files. The same element can appear in a web-fragment.xml inside a library JAR; the Servlet specification says that jsp-property-group elements from fragments are additive, and recommends that fragments use path patterns, not extension patterns, together with a subdirectory named after the fragment, so a fragment’s group cannot capture the application’s own JSP files.

The configuration is part of the container contract, not of the JSP engine. Since Servlet 3.0 the servlet container reads jsp-config from web.xml and every fragment and makes it available through ServletContext.getJspConfigDescriptor(); the JSP engine (Jasper in Tomcat, WaSP in GlassFish, Jetty’s Apache JSP) asks the container instead of re-parsing the descriptor. The returned JspConfigDescriptor is read-only: it has getTaglibs() and getJspPropertyGroups() and no setters, so there is no programmatic way to add a property group. Configuration is declarative, in the descriptor.

The element order inside jsp-property-group is fixed by the schema (jsp_4_0.xsd): the description group, one or more url-pattern, then el-ignored, error-on-el-not-found, page-encoding, scripting-invalid, is-xml, include-prelude, include-coda, deferred-syntax-allowed-as-literal, trim-directive-whitespaces, default-content-type, buffer and error-on-undeclared-namespace. Tomcat 11.0.26 does not validate web.xml by default and accepted a group with el-ignored placed before url-pattern (verified), but a validating tool, an IDE or another container may not, so keep the schema order.

The Bookshelf assembles one jsp-config element in the sections that follow. This servlet reads it back and prints it, which is also the quickest way to check what the container really parsed.

Source: Jakarta Pages 4.0 — 3.1 JSP Configuration Information in web.xml

Source: Jakarta Servlet 6.1 API — JspConfigDescriptor

Source: Jakarta Servlet 6.1 — 8.3 JSP Container Pluggability

Source: Jakarta Servlet 6.1 — 8.2.3 Assembling the Descriptor from web.xml, web-fragment.xml and Annotations

Source: Jakarta EE XML schema jsp_4_0.xsd

The web.xml itself is the Servlet 6.1 one, shown with the others in Servlet Fundamentals: the jakartaee namespace and version="6.1". Note that the JSP 1.2-era <taglib> element placed directly under <web-app> no longer exists; it moved inside jsp-config in Servlet 2.4 (see Where the Books Are Outdated).

A taglib directive names a tag library by URI: <%@ taglib prefix="c" uri="jakarta.tags.core" %>. The container turns that URI into a TLD resource path through the taglib map, a table from URI to a resource path inside the web application. The map is built from several sources, listed here from highest to lowest precedence as the Pages specification states them (section 7.3.2):

Entries 3 and 4 are why you almost never write a taglib element today: a TLD that declares <uri> is found automatically, and so is every library inside a JAR. The explicit map still has two uses. It is the only way to give a tag library a URI that its TLD does not declare, for example an alias or an application-internal name, and it is the way to point a URI at one specific TLD when several candidates exist.

A taglib element has exactly two children. taglib-uri is the URI to be used in taglib directives; it may be an absolute URI or a relative one, and the specification forbids two entries with the same taglib-uri. taglib-location is the context-relative location of the TLD file (or of a JAR with META-INF/taglib.tld).

The Bookshelf keeps a TLD with one EL function and gives it the application-internal name urn:bookshelf:text.

Source: Jakarta Pages 4.0 — 3.2 Taglib Map

Source: Jakarta Pages 4.0 — 7.3.3 Taglib Map in web.xml

Source: Jakarta Pages 4.0 — 7.3.2 TLD Resource Path

Two behaviours around the map are worth knowing, and both were observed on Tomcat 11.0.26. A URI that is not in the map is interpreted as a direct path to the TLD, the fallback meant for casual use during development (spec 7.3.6.2), so uri="/WEB-INF/tlds/bookshelf.tld" worked and printed BY PATH!. A URI that matches nothing at all is a fatal translation error:

Source: Jakarta Pages 4.0 — 7.2.3 Tag Library Directive

Tag libraries, TLD files and EL functions are the subject of Tag Library Descriptors & EL Functions; here only the mapping matters. The two JSTL validators that a TLD can name, ScriptFreeTLV and PermittedTaglibsTLV, are enforced through a TLD, not through jsp-config, and are described with the TLD elements (Jakarta Tags 3.0, chapter 14, "Tag Library Validators", shows the <validator> entries).

Source: Jakarta Tags 3.0 — 14. Tag Library Validators

A JSP property group is a collection of properties that apply to a set of files that represent JSP pages. A group is a jsp-property-group element with one or more url-pattern children (which files) and any number of property elements (which settings). Four points of the specification define how groups behave.

Source: Jakarta Pages 4.0 — 3.3 JSP Property Groups

Source: Jakarta Pages 4.0 — 3.3.1 JSP Property Groups

Source: Jakarta EE XML schema jsp_4_0.xsd

Besides these properties a group carries url-pattern and the optional description, display-name and icon of the schema’s description group, which have no effect on the page. The page directive attributes themselves are described on Directives; here only their relation to the groups matters.

A group applies to the resources that match any of its url-pattern values. The patterns use the same syntax as the Servlet specification’s chapter 12 (URL mapping), with one difference: they are bound at translation time, against the path of the JSP file, not at request time against the request URL. Three forms are used in practice.

Mixing a wildcard in the middle of a path is not a valid pattern. Tomcat 11.0.26 refused to start a web application whose group used /buf/*.jsp, with java.lang.IllegalArgumentException: Invalid <url-pattern> [/buf/*.jsp] in servlet mapping in the log; the application then answered 404. To cover the JSP files of one directory, use /buf/*.

Several groups, and the servlet mappings, can all match one file. The Pages specification (section 3.3) says:

The wording "the properties of that group apply" suggests that the other matching groups are ignored. Tomcat 11.0.26 does not do that for the ordinary properties: it decides each property separately, taking it from the most specific matching group that declares it. A less specific group’s value therefore still applies when the more specific group is silent about it. The experiments below make the difference visible, and they are the behaviour of Tomcat; a container that follows the sentence literally would give the outcome the specification describes. Declaring in the most specific group every property that matters removes the difference.

Source: Jakarta Pages 4.0 — 3.3 JSP Property Groups

Source: Jakarta Servlet 6.1 — 12.2 Specification of Mappings

The sequence ${expr} was not reserved before JSP 2.0, and #{expr} was not reserved before JSP 2.1, so an old page can contain such text with no intention of calling the expression language. The el-ignored property passes both sequences through verbatim for the matching files. The default depends on the version of the descriptor: a web.xml in Servlet 2.3 or earlier format ignores EL (backward compatibility), a Servlet 2.4 or later one evaluates it. Since the Bookshelf descriptor is version="6.1", EL is on, and a group is needed only for the pages that must stay as they are.

The page can override the group with <%@ page isELIgnored="false" %>. Tag files have no default: they always evaluate EL unless the tag directive says isELIgnored="true". The specification states the whole truth table:

Whether EL is on also decides whether the quote sequences \$ and \# are recognised: with EL evaluation enabled they produce a literal $ and #; with EL disabled they are not recognised at all, and the backslash stays in the output.

Source: Jakarta Pages 4.0 — 3.3.2 Deactivating EL Evaluation

Disabling EL is a compatibility tool, not a security control. If the goal is to stop an injected ${...} from being evaluated, remember that the sequence in the source of a page is the author’s, and that EL never re-evaluates request data it prints. The risk of EL is in expressions built from user input, which Security discusses.

scripting-invalid set to true makes scriptlets, declarations and expressions a translation error for the matching files. Scripting is on by default. JSP 2.0 introduced the element as an easier replacement for the older practice of enforcing the rule with a tag-library validator (ScriptFreeTLV in the Jakarta Tags TLDs). It is the single most useful hardening switch in the descriptor (Scripting Elements (Legacy) shows what to write instead): a project that has moved to EL and tags can turn scripting off for every page and stop a scriptlet from ever re-entering the code base.

Source: Jakarta Pages 4.0 — 3.3.3 Disabling Scripting Elements

Source: Jakarta Pages 4.0 — Table JSP.3-3 Scripting Settings

The error is raised at translation time, so the page fails on the first request (or at precompilation), never in the middle of a response. The setting applies to the whole translation unit, which means that a scriptlet inside a file included with the include directive is rejected too. A tag file is not affected by the group and keeps whatever scripting its own directives allow.

By default an EL expression that names an identifier nobody defined resolves to null, and the output is an empty string. That hides typos: ${owner} for a misspelt request attribute looks like an empty field, not a bug. Jakarta Pages 3.1 added an option to raise jakarta.el.PropertyNotFoundException instead. The group element error-on-el-not-found sets it for matching pages; the page directive attribute errorOnELNotFound and the tag directive attribute of the same name override it. Tag files have no group default: they return null unless their own directive says true.

The scope of the setting is the identifier, not the property: it applies to a name that no resolver can resolve (the NotFoundELResolver at the end of the chain). A property that is missing from an existing bean still raises PropertyNotFoundException regardless of the setting, as the Expression Language chapter explains (see Expression Language Basics).

Source: Jakarta Pages 4.0 — 3.3.4 Unknown EL Identifiers

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

Turning it on is a good development-time default. In production the 500 page it produces is an ordinary error page, so the error-page handling described on Error Handling applies to it.

page-encoding sets the pageEncoding of the files of a group: the character set in which the source files are stored, so the container decodes them correctly. Its valid values are those of the pageEncoding attribute. It matters only for pages in standard syntax; a JSP document in XML syntax takes its encoding from the XML declaration or a byte-order mark. Without any statement the page is read as ISO-8859-1, which is why a UTF-8 file with a non-ASCII title can show mojibake when nothing configures the encoding.

It is a translation-time error to name different encodings in the pageEncoding attribute of a page and in a group that matches the page, and also to name different encodings in the XML declaration of a document and in a matching group. Naming the same encoding twice is legal. A group should therefore be the single place that declares the encoding, and a page that needs a different one must sit in a different group.

Source: Jakarta Pages 4.0 — 3.3.5 Declaring Page Encodings

The response encoding, the request encoding and the byte-order-mark detection algorithm are separate subjects. The request side is not a jsp-config property at all: it is the Servlet element <request-character-encoding> of web.xml (and <response-character-encoding> for the response), which is why no property group sets it. All of them are covered on Character Encoding, together with default-content-type (below).

include-prelude and include-coda name context-relative files that the container includes, as if with the include directive, at the start and at the end of every JSP page of the group. They are the configuration equivalent of "every page begins with the same taglib directives and ends with the same footer", and the standard way to remove that boilerplate. Both elements can repeat inside one group, in which case the files are included in the order written.

When more than one group matches a page, the preludes of all of them are included, in the order in which the groups appear in web.xml; the codas likewise, in order. The specification points out that this is unlike the other properties, where a single group’s pattern is selected. A prelude or coda follows the rules of a statically included JSP segment: start and end tags must be in the same file, so a prelude cannot open an HTML element that only the coda closes if that element is built from a JSP tag. The conventional extension for such fragments is .jspf, and the files belong under WEB-INF so they cannot be requested directly.

Source: Jakarta Pages 4.0 — 3.3.6 Defining Implicit Includes

The coda order observed is coda1 then coda2, in descriptor order, and not the nesting order (coda2 first) that a reader might expect from "the outer group closes last". If the order matters, put both files in one group, in the order needed. A prelude that does not exist is an error for every page of the group:

Source: Jakarta Pages 4.0 — 3.3.6 Defining Implicit Includes

is-xml marks the files of a group as JSP documents: XML-syntax pages that must be well-formed XML. The default extension .jspx (and .tagx for tag files) already means "document". The element exists for two reverse cases, both shown in the specification: setting is-xml to false for *.jspx to treat those files as ordinary pages, and setting it to true for another extension, such as *.svg, so that a generator of XML output is written as a document. Like page-encoding, it applies per file and not per translation unit. The syntax of documents (jsp:root, jsp:output, namespaces) is the subject of JSP Documents (XML Syntax); here only the switch matters.

Source: Jakarta Pages 4.0 — 3.3.7 Denoting XML Documents

Two details of the response are worth reading closely. The unused xmlns:c declaration was dropped from the output, and the content type is text/xml, not the image/svg+xml that an SVG response normally carries, so a document meant to be served as an image needs its content type set explicitly.

From JSP 2.1 the sequence #{ is reserved for deferred EL expressions, so a page that uses it in template text, for example a placeholder such as #{title} meant for a client-side template, fails to translate. The element deferred-syntax-allowed-as-literal (default false), or the page attribute deferredSyntaxAllowedAsLiteral, allows it as plain text. The related compatibility rule (spec 3.4) is that #{expr} as the value of a tag attribute is evaluated only when the TLD declares jsp-version 2.1 or later; in a TLD that declares an older version it is a string literal.

Source: Jakarta Pages 4.0 — 3.3.8 Deferred Syntax

When only a few places need the literal, the quote sequences are cheaper than a group. With EL evaluation enabled, \# produces a # and \$ a $, so no configuration is involved:

Source: Jakarta Pages 4.0 — 1.6 Quoting and Escape Conventions

Source: Jakarta Pages 4.0 — 3.4 Backwards Compatibility with JSP 2.0

Whitespace in template text is preserved, so every taglib directive, every c:set and every blank line between actions adds a line break to the response. trim-directive-whitespaces (default false), or the page attribute trimDirectiveWhitespaces, removes template text that consists only of whitespace. Text that contains anything else is kept exactly. It has no effect on JSP documents. In the specification’s example, two taglib lines followed by Hello World! produce two blank lines without the setting and none with it; in Tomcat 11.0.26 that exact case already printed no blank lines in the test application, so the visible effect is shown below with actions in the page.

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

Source: Jakarta Pages 4.0 — 1.3.8 White Space

The setting is safe for HTML. It is not safe for content where blank lines matter, such as plain text or Markdown generated by a page, and for <pre> blocks built from separate actions; set it per group, not blindly for everything.

default-content-type supplies the response content type of the group’s pages when the page has no contentType attribute. Its values are those of the contentType attribute, including the charset. Without it, and without any contentType, Tomcat 11.0.26 answered text/html;charset=UTF-8 in the test application (observed with no group at all); the Pages specification still names ISO-8859-1 as the fallback character encoding for page decoding. Stating the value in a group makes the answer independent of the container’s default, which matters for portability.

buffer sets the buffering of the page’s out writer for the group: the same values as the buffer attribute of the page directive, none or a size in kilobytes such as 32kb. The default is container-specific; Tomcat’s is 8 KB (observed 8192). A larger buffer lets a page set headers, cookies or an error status after producing a lot of output, because nothing is committed until the buffer fills; none makes every write go straight to the response and is rarely what you want.

Source: Jakarta Pages 4.0 — 3.3.10 Declaring Default Content Type

Source: Jakarta Pages 4.0 — 3.3.11 Setting Default Buffer Size

Both settings are overridden by the contentType and buffer attributes of the page directive. The relation of default-content-type to pageEncoding, to <response-character-encoding> in web.xml and to fmt:requestEncoding belongs to Character Encoding.

In a JSP page in standard syntax a tag whose prefix was never declared is, by default, silently ignored: the text <z:greeting/> is copied to the output as plain template text. That turns a forgotten taglib directive into an invisible bug. error-on-undeclared-namespace (default false) makes it a translation error, as it already is for JSP documents. The strict area of the Bookshelf turns it on, in the group shown in the error-on-el-not-found section.

Source: Jakarta Pages 4.0 — 3.3.12 Raising Errors for Undeclared Namespaces

The configuration of the standard tag library is a different mechanism from jsp-config, but it lives in the same descriptor and is often needed together, so it is part of this page. Jakarta Tags 3.0 (section 2.8) defines configuration settings: values that change how the actions behave and that can be set in two ways. Application-wide, as a context-param in web.xml whose name is the setting’s name and whose value is a string. For one scope, as a configuration variable stored in the page, request, session or application scope, with the class jakarta.servlet.jsp.jstl.core.Config. A configuration variable overrides the context parameter for as long as its scope lasts. The class hides the real attribute name, so that a variable set in the request scope does not collide with a same-named variable in the session; use Config, never setAttribute, to set them. The actions that read these settings are described on JSTL i18n & Messages and JSTL Formatting.

Source: Jakarta Tags 3.0 — 2.8 Configuration Data

Source: Jakarta Tags 3.0 — 8.11 Configuration Settings (i18n)

Source: Jakarta Tags 3.0 — 9.11 Configuration Settings (formatting)

Source: Jakarta Tags 3.0 — 10.9 Configuration Settings (SQL)

Source: Jakarta Tags 3.0 API — Config

A further variable, jakarta.servlet.jsp.jstl.fmt.request.charset, is not a setting you configure: fmt:requestEncoding stores the request encoding it detected in the session scope under that name. The Config class offers get, set and remove for each scope (PageContext, ServletRequest, HttpSession, ServletContext) and find, which a tag handler uses: it looks in the page, request, session and application scopes in turn and finally in the context parameter of the same name. Because get looks only at the variable in the given scope, a servlet that wants the context parameter reads it with ServletContext.getInitParameter(Config.FMT_TIME_ZONE), as the example does. The sql actions, and why a data source belongs outside the view, are explained on the JSTL SQL page of this section.

The Bookshelf sets the French locale, the Madrid time zone and a bundle for the whole application, then overrides each at the narrowest scope that needs it.

Source: Jakarta Tags 3.0 — 2.8 Configuration Data

Source: Jakarta Tags 3.0 — 8.11.3 I18n Localization Context

The same thing from Java, for a servlet that decides the zone per request. The servlet stores a configuration variable in the request scope with Config.set; the JSP’s fmt:formatDate picks it up with no change.

Source: Jakarta Tags 3.0 API — Config

Source: Jakarta Tags 3.0 — 9.11.1 TimeZone

The sql.dataSource and sql.maxRows context parameters follow the same pattern, sql.maxRows taking an integer. They were declared and deployed successfully in the test application, but no database was used, so their behaviour is only described, not demonstrated. A data source defined in web.xml with a JDBC parameter string puts the database URL, user and password in the descriptor; use a JNDI data source from the container instead, and never commit a password to the file (the placeholder rule of this section applies to every descriptor shown).

Putting the settings together, this is the group a new project should start from. Everything in it is declared in one place, so that a page behaves the same on any container and a new developer reads the rules from the descriptor.

Source: Jakarta Pages 4.0 — 3.3 JSP Property Groups

The baseline puts the views under WEB-INF, so they cannot be requested directly, and the group pattern /WEB-INF/views/* (a valid path prefix) selects them. A taglibs.jspf prelude with the taglib directives removes the first lines of every page. That baseline was not run as a single descriptor; each of its elements was exercised individually in the groups above. Development-time engine parameters (recompilation checks, generated-source retention) and precompilation are not jsp-config settings; they are init-param values of the JSP servlet and a build step, covered on the Jasper configuration page of this section.

Source: Apache Tomcat 11 — Jasper 2 JSP Engine How To, Configuration

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

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

Source: Jakarta Servlet 6.1 — 8.3 JSP Container Pluggability

The JSP and JSTL books consulted for this section (listed in the section bibliography) describe the configuration of the JSP 1.2 and JSTL 1.0 era. The concepts they teach (a tag-library URI mapped to a TLD, application-wide defaults for the tag library, the wish to keep scripting out of pages) survived; the mechanisms did not.

Source: Jakarta Pages 4.0 — 3.2 Taglib Map

Source: Jakarta Pages 4.0 — 7.3.4 Implicit Map Entries from TLDs

Source: Jakarta Tags 3.0 — 2.8 Configuration Data