6.1 Overview

In a servlet-based Web application, you can specify application-wide initialization parameters ”known as context initialization parameters ”for your application in the deployment descriptor; for example, the following code fragment stores the value es-MX in a context initialization parameter:

 <!-- Specifying a default locale in WEB-INF/web.xml -->  <web-app>    <context-param>       <param-name>  javax.servlet.jsp.jstl.fmt.locale  </param-name>       <param-value>  es-MX  </param-value>    </context-param>    ... </web-app> 

You might suspect that the parameter name javax.servlet.jsp.jstl.fmt. locale serves some official purpose, and you'd be right ”if you add that context initialization parameter to your deployment descriptor ( WEB-INF/web.xml ), as in the preceding code fragment, you will set the default locale for JSTL I18N and formatting actions. In the preceding code fragment, that locale is set to Mexican Spanish.

It's often desirable to override settings for a particular scope; for example, you might want to temporarily override the javax.servlet.jsp.jstl.fmt.locale context initialization parameter for a page, request, or session, so JSTL lets you create scoped variables that override context initialization parameters. Those scoped variables are known as configuration variables, and they are most often created by JSTL actions; for example, you can use the <fmt:setLocale> action like this:

 <fmt:setLocale value='fr-CA' scope='request'/> 

The <fmt:setLocale> action in the preceding code fragment creates a French Canadian locale and stores it in a configuration variable in request scope. During the request, that configuration variable will take precedence over the context initialization parameter named javax.servlet.jsp.jstl.fmt.locale . When the request is over, the configuration variable is removed, and the default locale returns to the value specified in the context initialization parameter, assuming no other configuration variables of the same name exist in other scopes.

The combination of context initialization parameter and configuration variable is defined by the JSTL specification as a configuration setting. Configuration settings let you specify default values with context initialization parameters and subsequently override those defaults with configuration variables with a JSTL action or a business component. Configuration settings are defined by static constants in the javax.servlet.jsp.jstl. core .Config class and a name that corresponds to that constant; for example, the configuration setting named javax.servlet.jsp.jstl.locale is defined by the FMT_LOCALE constant in the Config class.

You use a configuration setting's name in deployment descriptors, but you use the static constants in business components , such as servlets or life-cycle listeners. Throughout this book, configuration settings are referred to by their constants; for example, the configuration setting named javax.servlet.jsp.jstl.fmt.locale is referred to as the FMT_LOCALE configuration setting.

The FMT_LOCALE configuration setting discussed in this section is one of six configuration settings in JSTL 1.0. All of the JSTL 1.0 configuration settings are listed in Table 6.1.

Table 6.1. JSTL 1.0 Configuration Settings

Constant [a]	Name [b]
FMT_LOCALE	j.s.j.j.fmt.locale
FMT_FALLBACK_LOCALE	j.s.j.j.fmt.fallbackLocale
FMT_LOCALIZATION_CONTEXT	j.s.j.j.fmt.localizationContext
FMT_TIME_ZONE	j.s.j.j.fmt.timeZone
SQL_DATA_SOURCE	j.s.j.j.sql.dataSource
SQL_MAX_ROWS	j.s.j.j.sql.maxRows

^[a] The constants are defined by the javax.servlet.jsp.jstl.core.Config class.

^[b] j.s.j.j = javax.servlet.jsp.jstl

The first three configuration settings listed in Table 6.1 are used by JSTL I18N and formatting tags. The fourth, which lets you specify a time zone, is used only by formatting actions. The last two let you specify an SQL data source and a limit for database queries.

In JSTL 1.0, four actions change configuration settings. Table 6.2 lists those actions and the configuration settings they modify.

Table 6.2. JSTL 1.0 Actions That Modify Configuration Settings

Action	Configuration Setting
<fmt:setLocale>	FMT_LOCALE
<fmt:setBundle>	FMT_LOCALIZATION_CONTEXT
<fmt:setTimeZone>	FMT_TIME_ZONE
<sql:setDataSource>	SQL_DATA_SOURCE

Notice that all of the actions in Table 6.2 are named setXXX , where XXX represents a configuration setting. The FMT_FALLBACK_LOCALE and SQL_MAX_ROWS configuration settings are not set by any JSTL actions; if you want to set them, you can specify them as context initialization parameters or you can set them in a business component.

Configuration settings all work the same way, so we will focus mostly on one configuration setting ” FMT_LOCALE ”throughout the rest of this chapter. Learning about that configuration setting will help you understand how all configuration settings work.

The FMT_LOCALE Configuration Setting

This book documents JSTL configuration settings with tables like Table 6.3, which documents the FMT_LOCALE configuration setting

Table 6.3. The FMT_LOCALE Configuration Setting

Config Constant	FMT_LOCALE
Name	javax.servlet.jsp.jstl.fmt.locale
Type	java.lang.String or java.util.Locale
Set by	<fmt:setLocale>, Deployment Descriptor, Config class
Used by	<fmt:bundle>, <fmt:setBundle>, <fmt:message>, <fmt:formatNumber>, <fmt:parseNumber>, <fmt:formatDate>, <fmt:parseDate>

Each configuration setting has a type. All JSTL configuration settings can be specified with a string or an object; for example, you can specify the FMT_LOCALE configuration setting as a string, such as en-US or fr-CA , or as an instance of java.util.Locale .

Table 6.3 also tells you which JSTL actions set the FMT_LOCALE configuration setting (only <fmt:setLocale>) and which actions use it (quite a few).

Temporarily Overriding Configuration Settings

Figure 6-1 shows a simple Web application that illustrates how the FMT_LOCALE configuration setting works. There are two JSP pages in the application. The first page, referred to as Page 1, is shown at startup (shown on the left in Figure 6-1). That page has a submit button that takes you to the second page, referred to as Page 2 (shown on the right in Figure 6-1).

Figure 6-1. Using the FMT_LOCALE Configuration Setting

The first thing you need to know to make sense of the application shown in Figure 6-1 is that French is specified as the default locale with a context initialization parameter in the deployment descriptor. That deployment descriptor is listed in Listing 6.1.

Listing 6.1 WEB-INF/web.xml

 <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE web-app   PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"   "http://java.sun.com/j2ee/dtds/web-app_2.3.dtd"> <web-app>    <context-param>       <param-name>  javax.servlet.jsp.jstl.fmt.locale  </param-name>       <param-value>  fr  </param-value>    </context-param>    <welcome-file-list>       <welcome-file>page_1.jsp</welcome-file>    </welcome-file-list> </web-app> 

When the application shown in Figure 6-1 starts up, it displays Page 1 ( page_1.jsp ), which is designated as a welcome file in the deployment descriptor. That page uses a scriptlet to print the value of the FMT_LOCALE configuration setting, which is initially French ( fr ) because that's what was specified in the deployment descriptor. Listing 6.2 shows how that JSP page is implemented.

The scriptlet that prints the value of the FMT_LOCALE configuration setting uses the static find method from the JSTL Config class to find the value of the FMT_LOCALE configuration setting. That method searches for a configuration variable in page, request, session, and application scopes, in that order; if it finds the configuration variable, it returns that variable's value. If the method does not find the configuration variable, it checks to see if a corresponding context initialization parameter exists; if so, it returns that parameter's value. In that way, scoped variables override context initialization parameters for configuration settings. ^[3]

^[3] See "The Config Class" on page 239 for more information about the Config class.

Listing 6.2 page_1.jsp

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html>    <head>       <title>Page 1</title>    </head>    <body>       <%@ taglib uri='http://java.sun.com/jstl/fmt' prefix='fmt'%>       <%@ page import='javax.servlet.jsp.jstl.core.*' %>       <h1>Page 1</h1>       <%-- The following scriptlet prints the value of the            FMT_LOCALE configuration setting --%>       <% Object o =  Config.find(pageContext, Config.FMT_LOCALE);  out.print("Initial Locale Configuration Setting: <b>");          out.print(o + "</b><br>");       %>  <fmt:setLocale value='en' scope='page'/>  <p>       <% o =  Config.find(pageContext, Config.FMT_LOCALE);  out.print("After &lt;fmt:setLocale value='en'&gt;");          out.print(" Locale Configuration Setting: <b>" +                      o + "</b><br>");       %>       <form action='page_2.jsp'>          <input type='submit' value='Go to Page 2'/>       </form>    </body> </html> 

After it prints the FMT_LOCALE configuration setting, the preceding JSP page uses the <fmt:setLocale> action to override that setting with English for page scope, like this:

 <fmt:setLocale value='en' scope='page'/> 

Subsequently, the JSP page prints the FMT_LOCALE configuration setting again, to verify that for Page 1, the default locale has changed from French to English.

When you click on the submit button in Page 1, the browser loads Page 2, which is listed in Listing 6.3.

Listing 6.3 page_2.jsp

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html>    <head>       <title>Page 2</title>    </head>    <body>       <%@ page import='javax.servlet.jsp.jstl.core.*' %>       <h1>Page 2</h1>       <% Object o =  Config.find(pageContext, Config.FMT_LOCALE);  out.print("Locale Configuration Setting: <b>" +                     o + "</b><br>");       %>    </body> </html> 

Page 2 (page_2.jsp), listed above, prints the FMT_LOCALE configuration setting with the same scriplet used in Page 1.

Clicking on the submit button in Page 1 generates a new request, so the English override of the context initialization parameter in Page 1 ”which was specified for page scope ”goes out of scope. Because that override goes out of scope, the FMT_LOCALE configuration setting for Page 2 returns to French.

What would happen if you changed this line of code from Page 1:

 <fmt:setLocale value='en' scope='page'/> 

to this:

 <fmt:setLocale value='en' scope='request'/> 

Will the output be different? No, because clicking on the Go to Page 2 button generates a new request, and the <fmt:setLocale> action in Page 1 sets the FMT_LOCALE configuration setting for the current request, so the setting once again goes out of scope. If you want to change the FMT_LOCALE configuration setting for Page 2, you can specify session or application scope for <fmt:setLocale>, like this:

 <fmt:setLocale value='en' scope='session'/> 

With the <fmt:setLocale> scope attribute set to session , as in the preceding code fragment, the FMT_LOCALE configuration setting will hold for Page 2, as shown in Figure 6-2.

Figure 6-2. Overriding the FMT_LOCALE Configuration Setting in Session Scope