23.1 Setting and Using Configuration Variables

Some of the JSTL tag libraries use default values for attributes that are not specified explicitly in the action elements, e.g., the data source to be used by the database actions and the locale used by the I18N actions. As I described in Part II, you can set these default values using context parameters in the deployment descriptor, but you can also set them dynamically using a servlet, filter, or listener. A typical example is a filter or a servlet that sets the locale based on user profile information. The term used for the dynamic settings in the JSTL spec is configuration variables, and when combined with a context parameter, it's called a configuration setting.

Each configuration setting is identified by a unique name, such as javax.servlet.jsp.jstl.fmt.locale for the default locale. This is the name you use when you set a default value through a context parameter:

<web-app ...>
  ...
  <context-param>
    <param-name>
      javax.servlet.jsp.jstl.fmt.locale
    </param-name>
    <param-value>
      en-US
    </param-value>
  </context-param>
  ...
</web-app>

The same names are used to set, read, and remove the configuration variables programmatically, using a JSTL class called javax.servlet.jsp.jstl.core.Config. It has the following fields:

public static final String FMT_LOCALE = 
    "javax.servlet.jsp.jstl.fmt.locale";
public static final String FMT_FALLBACK_LOCALE = 
    "javax.servlet.jsp.jstl.fmt.fallbackLocale";
public static final String FMT_LOCALIZATION_CONTEXT = 
    "javax.servlet.jsp.jstl.fmt.localizationContext";
public static final String FMT_TIME_ZONE = 
    "javax.servlet.jsp.jstl.fmt.timeZone";
  
public static final String SQL_DATA_SOURCE = 
    "javax.servlet.jsp.jstl.sql.dataSource";
public static final String SQL_MAX_ROWS = 
    "javax.servlet.jsp.jstl.sql.maxRows";

The fields are simply constants for all variables names, to make it a bit easier to use the class.

The following get( ) methods read the value of a configuration variable:

public static Object get(javax.servlet.jsp.tagext.PageContext page,
    String name, int scope)
public static Object get(javax.servlet.ServletRequest request,
    String name)
public static Object get(javax.servlet.http.HttpSession session,
    String name)
public static Object get(javax.servlet.ServletContext application,
    String name)

These methods get a variable value from any scope, the request scope, the session scope, and the application scope, respectively. The method that takes a PageContext instance and a scope identifier as arguments is intended for custom actions, while the others are primarily intended for other component types, such as a servlet, that do not have access to a PageContext. The name argument is the configuration variable name, typically specified using the corresponding constant.

To set a configuration value, use one of the following methods:

public static void set(javax.servlet.jsp.tagext.PageContext page,
    String name, Object var, int scope)
public static void set(javax.servlet.ServletRequest request,
    String name, Object var)
public static void set(javax.servlet.http.HttpSession session,
    String name, Object var)
public static void set(javax.servlet.ServletContext application,
    String name, Object var)

The set( ) methods set a variable value in any scope, the request scope, the session scope and the application scope, respectively, following the same pattern as the get( ) methods.

The find( ) method scans all scopes in the order page, request, session, and application and returns the first occurrence, or null if it can't find it:

public static Object find(javax.servlet.jsp.tagext.PageContext page,
    String name)

The remaining methods remove configuration variables:

public static void remove(javax.servlet.jsp.tagext.PageContext page,
    String name, int scope)
public static void remove(javax.servlet.ServletRequest request,
    String name)
public static void remove(javax.servlet.http.HttpSession session,
    String name)
public static void remove(javax.servlet.ServletContext application,
    String name)

Even though the configuration variables are simply attributes of the objects that represent the different JSP scopes, it's important that you use the Config class methods to manipulate them, instead of calling the setAttribute( ), getAttribute( ), and removeAttribute( ) methods directly on the scope objects. The reason is that the JSP specification states that all scopes should behave as a single namespace,^[1] which means, for instance, that if you set a variable in the page scope, it should replace a variable with the same name in any other scope. The configuration variables, on the other hand, are intended to just temporarily override a value for the same variable in another scope, for instance temporarily override an application scope value with a page or request scope value. To accomplish this in a portable way, the Config class uses implementation-depended attribute names for the configuration variables in each scope (typically, it appends the scope name to the configuration variable name).

^[1] This rule is not enforced by many containers, but breaking it can lead to portability problems between containers that do and those that don't.

To set the locale for the JSTL I18N actions based on a clever combination of the preferences sent with the request headers and the client's IP address, for instance, a controller servlet or a filter can use the Config class like this before asking a JSP page to render the result:

import javax.servlet.jsp.jstl.core.Config;
import java.util.Locale;
import javax.servlet.*;
...
Locale prefLocale = getPrefLocale(request);
Config.set(request, Config.FMT_LOCALE, prefLocale);

The details about each configuration setting are described in the sections that follow.