8.4 Determining a Formatting Locale

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: 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. 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. 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: 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. 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.