17.3 Global Configuration Options

You can use the application deployment descriptor (web.xml) to define configuration options that apply to a group of JSP pages. These options are defined as subelements of the <jsp-property-group> element, which in turn is a subelement of the <jsp-config> element. More than one <jsp-property-group> element can be used, each with one or more nested <url-pattern> elements that associate the properties with all JSP pages that match the specified URL patterns:

<web-app>
  ...
  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.jsp</url-pattern>
      ...
    </jsp-property-grop>
    <jsp-property-group>
      <url-pattern>/jsp12/*</url-pattern>
      ...
    </jsp-property-grop>
  </jsp-config>
  ...
</web-app>

With exception for automatic include properties (described later), the JSP container applies the properties only from the <jsp-property-group> with the URL pattern that most closely matches the requested page. The specified properties apply to an entire translation unit, i.e., both the main JSP page and all files it includes using the include directive (with the exception for the file encoding property, which applies to individual files).

The URL pattern format and interpretation are the same as for servlet and filter mappings, described in Chapter 19. That is, one of the following types of patterns can be used:

Exact match rule

A complete context-relative path, e.g., /admin/authenticate.jsp. This rule matches only the specific path.

Longest path prefix rule

A context-relative path with a wildcard character (*), e.g., /admin/*. This rule matches all request with the same path before the wildcard character, and if there's more than one pattern that matches, the one with the longest matching path applies.

Extension rule

A wildcard character (*) followed by a dot and a file extension, e.g., *.jsp. This rule matches all requests that end with the specified extension.

The container compares each request URL to the defined mapping rules, looking for matches in the order exact match, longest path-prefix and extension, and applies the properties mapped to the first pattern that matches.

17.3.1 Declaring a File as a JSP Page

If a request matches a URL pattern defined within any <jsp-property-group> element, it's implicitly defined to be a JSP page, i.e., a file the JSP container must process. A potential use for this feature is to define additional extensions that should be treated as JSP pages:

<web-app ...>
  ...
  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.html</url-pattern>
    </jsp-property-grop>
  </jsp-config>
  ...
</web-app>

A deployment descriptor like this tells the container to process all requests with an .html extension as JSP pages; this might be used to add a piece of dynamic content to a previously static web site without having to rename all files.

17.3.2 Controlling the Interpretation of EL Expressions

Starting with JSP 2.0, EL expressions can directly be used in template text and in attribute values for any action element. A JSP application written for a prior version of the JSP specification, however, may use constructs that look like EL expressions and expect them to be used as literal strings instead of being evaluated.

To deal with this potential problem, the JSP 2.0 specification defines two ways to disable EL expression evaluation. First, EL expression evaluation is disabled by default for a web application with a deployment descriptor that is not Servlet 2.4 conformant (i.e., an application developed for a previous version of the Servlet and JSP specifications), and it's enabled by default for a web application with a Servlet 2.4 deployment descriptor. This guarantees that an old JSP application can be deployed in a JSP 2.0 container with full backwards compatibility, while a sensible default is provided for new applications. Second, the EL expression evaluation can be explicitly disabled in a JSP 2.0 application—for a single page with the elIgnored page attribute, or for a set of JSP pages with an <el-ignored> element in a JSP group:

<web-app ...>
  ...
  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.jsp</url-pattern>
      <el-ignored>true</el-ignored>
    </jsp-property-grop>
  </jsp-config>
  ...
</web-app>

The ability to disable EL evaluation in a JSP 2.0 application allows you to migrate an old application to the new JSP 2.0 features a few pages at a time, ensuring that the pages that have not yet been migrated behave as they did with JSP 1.2. If you define the EL evaluation mode with an <el-ignored> element in the deployment descriptor, you can override this setting with the elIgnored page attribute in individual pages. For instance, you can disable EL evaluation for all JSP pages with the deployment descriptor snippet shown here, and selectively enable it with the elIgnored attribute in each JSP page that's reviewed and migrated to JSP 2.0:

<%@ page elIgnored="false" %>

17.3.3 Controlling the Use of Scripting Elements

With all the new features available through the JSP EL, JSTL, and custom actions, scripting elements are rarely needed. A company may decide to implement a policy of forbidding scripting elements altogether, avoiding all the potential problems that scripting introduces. A policy like this can be enforced with the <scripting-invalid> element, for all or selected parts of the application:

<web-app ...>
  ...
  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.jsp</url-pattern>
      <scripting-invalid>true</scripting-invalid>
    </jsp-property-grop>
  </jsp-config>
  ...
</web-app>

With this configuration, the container refuses to process a JSP page that contains any scripting element (i.e., a scripting declaration, expression, or scriptlet). Since this represents a policy decision, there's no way to override this value in an individual JSP page.

17.3.4 Specifying the File Encoding

As you may recall from Chapter 14, the character encoding used for a JSP file can be defined within the file by the pageEncoding page attribute. This is all fine and dandy, as long as the file is in an encoding that uses the ASCII mapping for bytes 0 through 127; if not, the encoding cannot be read from the file. Some character encodings, such as UTF-16 and EBCDIC, don't share these byte-value mappings, so another approach is needed. The <page-encoding> element offers this alternative for classic JSP pages:

<web-app ...>
  ...
  <jsp-config>
    <jsp-property-group>
      <url-pattern>/ja/*</url-pattern>
      <page-encoding>Shift_JIS</page-encoding>
    </jsp-property-grop>
  </jsp-config>
  ...
</web-app>

This example tells the container to use the Shift_JIS encoding when reading a file in the /ja directory. As opposed to all other property settings, this setting applies to individual files rather than to the entire translation unit. This means that in addition to files requested directly, the specified file encoding is used for all files under /ja (in this example) added with an include directive in any JSP page, no matter what path is used to request that JSP page.

For JSP pages in XML syntax (so-called JSP Documents, described later), the file encoding is always determined based on the XML prolog in the file as described in the XML specification, so neither the pageEncoding attribute nor the <page-encoding> element should be used. If they are still used, and they specify a different encoding than the one determined according to the XML rules, the container doesn't accept the file and reports it as a translation error.

17.3.5 Specifying Automatically Included Files

If a lot of tag libraries are used for an application, or a set of pages need the same page attribute values to be set, it's easier to maintain the application if all the common declarations are placed in one file that is then included in all JSP pages. You can do so with the include directive, but then you run the risk of forgetting to include the file in a page. JSP 2.0 introduces a better solution: automatic includes.

You can use one or more <include-prelude> elements to include files at the beginning of all JSP pages that match the JSP property group URL pattern, and one or more <include-coda> elements to include files at the end of the JSP files. As opposed to all other configuration properties, you can even use multiple JSP property groups to define these two elements; the include elements from all groups that match the request URL are applied:

<web-app ...>
  ...
  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.jsp</url-pattern>
      <include-prelude>/WEB-INF/segments/taglibDecl.jspf</include-prelude>
      <include-prelude>/WEB-INF/segments/errorPageDecl.jspf</include-prelude>
      <include-coda>/WEB-INF/segments/copyright.jspf</include-coda>
    </jsp-property-grop>
    <jsp-property-group>
      <url-pattern>/main/*</url-pattern>
      <include-prelude>/WEB-INF/segments/noSessionDecl.jspf</include-prelude>
    </jsp-property-group>
  </jsp-config>
  ...
</web-app>

In this example, I use one group for the *.jsp pattern that include files with common tag library and error page declarations at the beginning of each file, plus a copyright notice at the end of each file. I also define a group for the /main/* pattern, including a file with a page attribute that disables sessions. A request like /mycontext/main/index.jsp matches the patterns for both groups, so the files defined in both groups are included. For a request like /mycontext/shopping/cart.jsp, only the first group's URL pattern matches, so only the files defined in this group are included.

17.3.6 Declaring Files as JSP Documents

As I will show you later in this chapter, JSP pages can be written as well-formed XML documents, using a slightly different syntax for things like tag library declarations and other directives than what you've seen so far. The default extension for a JSP page in the XML format is .jspx, starting with the JSP 2.0 specification. To make it possible to use other extensions, and to allow applications that use this extension for regular JSP files, the <is-xml> element can be used to control whether a file should be processed as a JSP page in XML format:

<web-app ...>
  ...
  <jsp-config>
    <jsp-property-group>
      <url-pattern>*.jspx</url-pattern>
      <is-xml>false</is-xml>
    </jsp-property-grop>
    <jsp-property-group>
      <url-pattern>*.svg</url-pattern>
      <is-xml>true</is-xml>
    </jsp-property-grop>
  </jsp-config>
  ...
</web-app>

As with EL evaluations, the default for this property depends on which version of the servlet specification the application's deployment descriptor adheres to, in order to guarantee backward compatibility. If the application has a pre-2.4 deployment descriptor, the .jspx extension means nothing special; files with this extension are not considered to be JSP pages at all. For an application with a 2.4 deployment descriptor, files with a .jspx extension are processed as JSP XML pages by default.

The deployment descriptor snippet shown here defines two JSP groups. The first one disables the .jspx default extension, so that files with this extension are instead handled as regular JSP pages. The second one declares that files with an .svg extension must be handled as JSP pages in XML syntax.