8.4 Determining a Formatting Locale

So far in this chapter, all of the code examples have used <fmt:setLocale> to specify the locale used by the <fmt:formatNumber>, <fmt:parseNumber>, <fmt:formatDate>, and <fmt:parseDate> actions. But in practice, it's usually not necessary to use <fmt:setLocale> to establish a formatting locale because the formatting actions perform a rather elaborate search for a locale. This section discusses that search.

Before we discuss the search for a formatting locale, you must understand the concept of a localization context. You can read about localization contexts in "Localization Context Lookup" on page 268, but in a nutshell , a localization context is a simple JavaBeans component (bean) that maintains a resource bundle and a locale. For our purposes in this chapter, the resource bundle is immaterial, but the locale stored in a localization context is often used by formatting actions.

The search that formatting actions perform to locate a formatting locale proceeds as follows :

1. An Enclosing <fmt:bundle> Action

   All <fmt:bundle> actions establish a localization context, meaning they store a resource bundle and a locale in a localization context. If a formatting action is nested in a <fmt:bundle> action, it uses the locale stored in the localization context established by its enclosing <fmt:bundle> action.

2. The FMT_LOCALIZATION_CONTEXT Configuration Setting

   If a formatting action is not nested in a <fmt:bundle> action, it checks to see if the FMT_LOCALIZATION_CONTEXT configuration setting has been set; if so, the formatting action uses the locale stored in that configuration setting.

3. Formatting Locale Lookup

   If a formatting action is not nested in a <fmt:bundle> action and the FMT_LOCALIZATION_CONTEXT configuration setting has not been set, the formatting action performs a formatting locale lookup. That lookup is discussed in "Formatting Locale Lookup" on page 354.

Let's discuss each of the preceding steps in more detail.

1 An Enclosing <fmt:bundle> Action

Formatting actions that are nested in a <fmt:bundle> action use the locale stored in that <fmt:bundle> action's localization context; for example:

 <%-- The following <fmt:bundle> action establishes a localization       context that is only used in the body of the <fmt:bundle>      action --%> <fmt:bundle basename='messages'>    <%-- The i18n and formatting actions nested in the enclosing         <fmt:bundle> action use the localization context         established by the enclosing <fmt:bundle> action --%>    <fmt:message key='formatting.example.number'/>    ...    <fmt:formatNumber value='234682.155'/>    ... </fmt:bundle> 

In the preceding code fragment, the <fmt:bundle> action tries to locate a resource bundle whose base name is messages ; if it finds that resource bundle, it creates a localization context and stores the resource bundle and the locale that was used to locate that resource bundle in its localization context. ^[17] All of the <fmt:message> actions and all of the formatting actions nested in that <fmt:bundle> action use the same localization context; for example, in the preceding code fragment, the <fmt:message> action uses the resource bundle stored in the <fmt:bundle> action's localization context, and the <fmt:formatNumber> action uses the locale stored in the <fmt:bundle> action's localization context.

^[17] See "Resource Bundle Lookup" on page 274 for more information about how <fmt:bundle> establishes a localization context.

2 The FMT_LOCALIZATION_CONTEXT Configuration Setting

If a formatting action is not nested in a <fmt:bundle> action and the FMT_LOCALIZATION_CONTEXT configuration setting has been set, that formatting action uses the locale stored in the FMT_LOCALIZATION_CONTEXT configuration setting's localization context; for example:

 <%-- This <fmt:setBundle> action establishes a localization context       and stores it in the FMT_LOCALIZATION_CONTEXT configuration      setting --%> <fmt:setBundle basename='messages'/> <%-- Because the following <fmt:formatNumber> action is not nested      in a <fmt:bundle> action, it gets its locale from the      localization context established by the preceding      <fmt:setBundle> action --%> <fmt:formatNumber value='234682.155'/> 

In the preceding code fragment, the FMT_LOCALIZATION_CONTEXT configuration setting is set by the <fmt:setBundle> action. ^[18] The locale stored in the FMT_LOCALIZATION_CONTEXT configuration setting is used by the <fmt:formatNumber> action.

^[18] There are other ways to set the FMT_LOCALIZATION_CONTEXT configuration setting; see "Localization Context Lookup" on page 268 for more information.

If the localization context stored in the FMT_LOCALIZATION_CONTEXT configuration setting does not have a locale, formatting actions that do not reside in the body of a <fmt:bundle> action perform a formatting locale lookup, which is described in the next step.

3 Formatting Locale Lookup

If a formatting action is not nested in a <fmt:bundle> action and the FMT_LOCALIZATION_CONTEXT configuration setting has not been set, that formatting action performs a formatting locale lookup; for example:

 <%-- If the FMT_LOCALIZATION_CONTEXT configuration setting has not       been set, the following <fmt:formatNumber> action performs      a formatting locale lookup to find a locale to use to      format its value --%> <fmt:formatNumber value='234682.155'/> 

In the preceding code fragment, the <fmt:formatNumber> action is not nested in a <fmt:bundle> action. If the FMT_LOCALIZATION_CONTEXT configuration setting has not been set, that <fmt:formatNumber> action performs a formatting locale lookup, which is discussed in the next section.

Formatting Locale Lookup

Formatting actions that are not nested in a <fmt:bundle> action perform a formatting locale lookup if the FMT_LOCALIZATION_CONTEXT configuration setting has not been set or if that configuration setting does not contain a locale.

The formatting locale lookup tries to find an appropriate locale among a set of available locales. For <fmt:formatNumber> and <fmt:parseNumber>, the available locales are determined by a call to the getAvailableLocales method from java.text.NumberFormat . For <fmt:formatDate> and <fmt:parseDate>, the available locales are determined by a call to the getAvailableLocales method from java.text.DateFormat .

The formatting locale lookup proceeds as follows:

1. Find a Matching Locale with the User 's Preferred Locales

   First, the formatting actions compare each of the user's preferred locales against each of the available locales; when a match is found, the algorithm terminates and that locale is used by the formatting action.

   There are two ways that you can specify your preferred locales: with your browser's language preferences or by setting the FMT_LOCALE configuration setting; the latter takes precedence over the former. You can set the FMT_LOCALE configuration setting in a number of ways; one way is with the <fmt:setLocale> action, which is how most of the code examples in this chapter establish a formatting locale.

2. Find a Matching Locale with the Fallback Locale

   If a formatting action cannot find a matching locale with a user's preferred locales, it will compare the fallback locale with each of the available locales.

   The fallback locale is specified with the FMT_FALLBACK_LOCALE configuration setting. There is no JSTL action that sets the FMT_FALLBACK_LOCALE configuration setting, so you must set that configuration setting in a deployment descriptor or a business component.

A preferred locale (or the fallback locale) matches an available locale if:

• They match exactly; that is, if the language, country, and variants all match, OR:

• The language and country match, OR:

• The language matches and the available locale does not specify a country.