You are viewing a plain text version of this content. The canonical link for it is here.
Posted to taglibs-dev@jakarta.apache.org by lu...@apache.org on 2002/01/04 01:29:21 UTC
cvs commit: jakarta-taglibs/standard/src/org/apache/taglibs/standard/tag/common/fmt BundleSupport.java LocaleSupport.java
luehe 02/01/03 16:29:21
Modified: standard/doc/web I18N_FunctionalDescription_6_EA3.html
standard/src/org/apache/taglibs/standard/tag/common/fmt
BundleSupport.java LocaleSupport.java
Log:
Added javax.servlet.jsp.jstl.i18n.locale context configuration
parameter, which allows application locale to be specified in
deployment descriptor file. The application's locale is taken from
this config parameter (if present) if the scoped attribute with the
same name does not exist.
The presence of either the scoped attribute or configuration parameter
disables browser-sensing capabilities for locales.
Revision Changes Path
1.7 +150 -137 jakarta-taglibs/standard/doc/web/I18N_FunctionalDescription_6_EA3.html
Index: I18N_FunctionalDescription_6_EA3.html
===================================================================
RCS file: /home/cvs/jakarta-taglibs/standard/doc/web/I18N_FunctionalDescription_6_EA3.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- I18N_FunctionalDescription_6_EA3.html 20 Dec 2001 03:49:56 -0000 1.6
+++ I18N_FunctionalDescription_6_EA3.html 4 Jan 2002 00:29:21 -0000 1.7
@@ -85,7 +85,7 @@
in that language (for example, a cancel button would be labelled
<tt>Cancel</tt>
for English and <tt>Abbrechen</tt> for German speaking customers).
-<p>Any action that requires a locale first calls the <tt>getLocales()</tt>
+<p>Any action that requires a locale first calls the <tt>ServletRequest.getLocales()</tt>
method on the incoming request, which provides a list, in order of preference,
of the locales that the client wants to use. This list is processed differently
depending on whether the action is an I18N or a formatting tag.
@@ -103,27 +103,31 @@
the action checks if there is a matching locale for the resource bundle
in question, by passing the resource bundle's base name and the client's
requested locale to the <tt>java.util.ResourceBundle.getBundle()</tt> method.
-This method appends the name of the requested client locale to the given
-base name and searches for a resource bundle with that name. A resource
-bundle may be backed by a class or a properties file. If no resource bundle
-with that name exists (and the requested locale has both a language and
-a country component), the method appends just the requested locale's language
-name to the given base name and searches for a resource bundle with that
-name. If no resource bundle with that name exists, and the requested locale
-differs from the container's default locale, the method continues the search
-by appending the name of the container's default locale to the given base
-name. If no resource bundle with that name exists (and the container's
-default locale has both a language and a country component), the method
+<p><tt>ResourceBundle.getBundle()</tt> implements the following search
+algorithm for resource bundles: It first appends the name of the requested
+client locale to the given base name and searches for a resource bundle
+with that name. A resource bundle may be backed by a class or a properties
+file. If no resource bundle with that name exists (and the requested locale
+has both a language and a country component), <tt>ResourceBundle.getBundle()</tt>
+appends just the requested locale's language name to the given base name
+and searches for a resource bundle with that name. If no resource bundle
+with that name exists, and the requested locale differs from the default
+locale of the container's Java runtime, <tt>ResourceBundle.getBundle()
+</tt>continues
+the search by appending the name of the container's default locale to the
+given base name. If no resource bundle with that name exists (and the container's
+default locale has both a language and a country component),
+<tt>ResourceBundle.getBundle()</tt>
appends just the language component of the container's default locale to
-the given base name. If there still is no match, the method searches for
-a resource bundle with just the given base name (without any locale name
-appended to it). If there still is no match, <tt>ResourceBundle.getBundle()
+the given base name. If there still is no match, <tt>ResourceBundle.getBundle()</tt>
+searches for a resource bundle with just the given base name (without any
+locale name appended to it). If there still is no match, <tt>ResourceBundle.getBundle()
</tt>raises
-a <tt>MissingResourceException</tt>, which is caught by the tag handler
-implementation and interpreted as if the resource bundle with the given
-base name does not exist for the requested client locale.
-<p>As a result of the search algorithm implemented by <tt>ResourceBundle.getBundle()</tt>,
-the locale of the resource bundle returned by <tt>ResourceBundle.getBundle()
+a <tt>MissingResourceException</tt>, which is caught by the action's tag
+handler implementation and interpreted as if the resource bundle with the
+given base name does not exist for the requested client locale.
+<p>As a result of this search algorithm for resource bundles, the locale
+of the resource bundle returned by <tt>ResourceBundle.getBundle()
</tt>may
either match both the country and language components of the requested
locale ("exact match"), only its language ("language match"), or neither
@@ -134,13 +138,16 @@
<p>If there is an exact match, it is used, and no further client locales
are checked. Otherwise, all remaining client locales are checked, and the
first language match is used. If no such match exists, the fallback locale
-stored in the <tt>javax.servlet.jsp.jstl.i18n.fallbackLocale</tt> attribute,
+from the <tt>javax.servlet.jsp.jstl.i18n.fallbackLocale</tt> scoped attribute,
which is searched in the page, request, session (if valid), and application
-scope(s) (in this order), is used (see Section 16: Configuration parameters).
-If this attribute is not found, or there still is no match, an error message
-of the form <tt>"???<key>???"</tt> (where
-<tt><key></tt> is the name
-of the message key to be looked up) is returned (see Section 8: <message>).
+scope(s) (in this order), or context configuration parameter (see Section
+17.2) is used. If no fallback locale has been specified, the default locale
+of the container's Java runtime is used. If no resource bundle (with the
+given base name) exists for the fallback or the container's default locale,
+an error message of the form <tt>"???<key>???"</tt> (where
+<tt><key></tt>
+is the name of the message key to be looked up) is returned (see Section
+8).
<p>The behavior is implementation-defined if the set of available resource
bundles changes during execution of the page. Implementations may thus
cache the best matching locale for a given resource bundle when one is
@@ -211,11 +218,11 @@
locale.
<p>Otherwise, the formatting action checks, for each of the client's preferred
locales (in order of preference), if there is a matching locale available.
-The <tt><formatNumber>
-</tt>and<tt> <parseNumber></tt>, and the <tt><formatDate>
-</tt>and
-<tt><parseDate>
-</tt>actions
+The <tt><formatNumber></tt>
+and<tt> <parseNumber></tt>, and the <tt><formatDate></tt>
+and
+<tt><parseDate></tt>
+actions
determine the available locales by calling <tt>java.text.NumberFormat.getAvailableLocales()</tt>
and <tt>java.text.DateFormat.getAvailableLocales()</tt>, respectively.
If there is an exact match (that is, a client's preferred locale specifies
@@ -227,34 +234,33 @@
on the same page do not have to determine it again.
<h4>
2.2. Application-based locales</h4>
-The browser-sensing capabilities for locales can be disabled by setting
-the <tt>javax.servlet.jsp.jstl.i18n.locale</tt> (scoped) attribute. This
-attribute may be set directly by application code for any of the JSP scopes.
-For example, an application might let its users pick their preferred locale
-and then set the <tt>javax.servlet.jsp.jstl.i18n.locale
-</tt>attribute
-accordingly. Alternatively, the <tt><locale> </tt>action may be used
-to set the <tt>javax.servlet.jsp.jstl.i18n.locale </tt>attribute with page
-scope only. This may be useful in the case where a client's preferred locale
-is retrieved from a database (using the JSTL database tags)and installed
-on the page using the <tt><locale></tt> tag.
-<p>The <tt>javax.servlet.jsp.jstl.i18n.locale</tt> attribute is searched
+The browser-sensing capabilities for locales may be disabled by setting
+the <tt>javax.servlet.jsp.jstl.i18n.locale</tt> scoped attribute or context
+configuration parameter (see Section 17.1). The scoped attribute is searched
in the page, request, session (if valid), and application scope(s) (in
-this order).
+this order), and may be set directly by application code for any of these
+scopes. For example, an application might let its users pick their preferred
+locale and then set the <tt>javax.servlet.jsp.jstl.i18n.locale</tt> attribute
+accordingly. Alternatively, the <tt><locale></tt> action may be used
+to set this attribute with page scope only. This may be useful in the case
+where a client's preferred locale is retrieved from a database (using the
+JSTL database tags)and installed on the page using the <tt><locale></tt>
+tag.
<h3>
3. Response encoding</h3>
-Every action that is responsible for establishing a locale passes that
-locale to the <tt>setLocale()</tt> method of the <tt>javax.servlet.ServletResponse</tt>.
-(This assumes that the response is buffered with a big enough buffer size,
-since <tt>setLocale()</tt> and <tt>setContentType()</tt> must be called
-before <tt>ServletResponse.getWriter()</tt> in order for the charset to
-affect the construction of the writer.)
+Any I18N-capable formatting action defined in this Functional Description
+that deals with locales sets the response's locale by calling <tt>ServletResponse.setLocale()</tt>
+with the locale determined according to the logic described in Section
+2. This assumes that the response is buffered with a big enough buffer
+size, since <tt>ServletResponse.setLocale()</tt> and <tt>ServletResponse.setContentType()</tt>
+must be called before <tt>ServletResponse.getWriter()</tt> in order for
+the specified locale or charset to affect the construction of the writer.
<p>More specifically, the response's <tt>setLocale()</tt> method is always
called by the <tt><locale></tt> action. In addition, it is called by
the following actions if browser-sensing capabilities for locales are enabled
(that is, in the absence of the <tt>javax.servlet.jsp.jstl.i18n.locale</tt>
-attribute):
-<br>
+scoped attribute or context configuration parameter):
+<ul>
<li>
Any <tt><bundle></tt> action.</li>
@@ -264,12 +270,10 @@
<li>
A <tt><formatNumber></tt> or <tt><formatDate></tt> action that is
-not enclosed within a <tt><bundle> </tt>action.</li>
-
-<br>
-<p>
-<p>After an action has called <tt>ServletResponse.setLocale()</tt>, it
-determines the character encoding associated with the locale (by calling
+not enclosed within a <tt><bundle></tt> action.</li>
+</ul>
+After an action has called <tt>ServletResponse.setLocale()</tt>, it determines
+the character encoding associated with the locale (by calling
<tt>ServletResponse.getCharacterEncoding()</tt>)
and stores it in the <tt>javax.servlet.jsp.jstl.i18n.request.charset</tt>
session attribute. This attribute may be used by the <tt><requestEncoding></tt>
@@ -292,8 +296,8 @@
<p>The <tt>javax.servlet.jsp.jstl.i18n.timeZone</tt> attribute may be set
directly by application code for any of the JSP scopes. For example, an
application might let its users pick their preferred time zone and then
-set the <tt>javax.servlet.jsp.jstl.i18n.timeZone
-</tt>attribute accordingly.
+set the <tt>javax.servlet.jsp.jstl.i18n.timeZone</tt>
+attribute accordingly.
Alternatively, the <tt><timeZone></tt> action may be used to set the
<tt>javax.servlet.jsp.jstl.i18n.timeZone</tt>
attribute for the current page context. This may be useful in the case
@@ -305,11 +309,10 @@
this order). If not found, the JSP container's time zone is used.
<h3>
5. <locale></h3>
-The <tt><locale></tt> action may be used to set or override the JSP
-attribute
-<tt>javax.servlet.jsp.jstl.i18n.locale</tt> with the locale specified
-by the <tt>value</tt> attribute in the scope given by the <tt>scope</tt>
-attribute (default: "page").
+The <tt><locale></tt> action may be used to set or override the
+<tt>javax.servlet.jsp.jstl.i18n.locale</tt>
+scoped attribute with the locale specified by the <tt>value</tt> attribute
+in the scope given by the <tt>scope</tt> attribute (default: "page").
<p>The locale specified by the <tt>value</tt> attribute must contain a
two-letter (lower-case) language code (as defined by ISO-639), and may
contain a two-letter (upper-case) country code (as defined by ISO-3166)<tt>.
@@ -321,7 +324,7 @@
<p>Example:
<p><tt> <fmt:locale value="en-US" variant="UNIX"/></tt>
<p>By using this action, the browser-sensing capabilities for locales described
-in Section 2 of this functional description are disabled. This means that
+in Section 2 of this Functional Description are disabled. This means that
if this action is being used, it should be declared at the beginning of
a page, before any other I18N-capable formatting tags. Otherwise, a different
locale might be used up to the position in the page where the <tt><locale></tt>
@@ -341,8 +344,8 @@
</tt>for more details
on the supported time zone formats.
<p>The <tt>var</tt> attribute may be used to expose the time zone as a
-JSP-scoped attribute of type <tt>java.util.TimeZone
-</tt>(with visibility
+JSP-scoped attribute of type <tt>java.util.TimeZone</tt>
+(with visibility
<tt>AT_END</tt>),
so that it can be referenced by any subsequent
<tt><formatDate></tt>
@@ -367,10 +370,10 @@
<br><tt> <user-of-bundle/></tt>
<br><tt> </fmt:bundle></tt>
<p>The resource bundle's locale is determined according to Section 2 of
-this functional description.
+this Functional Description.
<p>The <tt>var</tt> attribute may be used to expose the resource bundle
-as a JSP-scoped attribute of type <tt>java.util.ResourceBundle
-</tt>(with
+as a JSP-scoped attribute of type <tt>java.util.ResourceBundle</tt>
+(with
visibility <tt>AT_END</tt>), so that it can be referenced by any subsequent
<tt><message></tt>
actions that take a <tt>bundle</tt> attribute:
@@ -398,8 +401,8 @@
missing, it is read from the tag's body content.
<p>The resource bundle in which to look up the message key may be given
by the <tt>bundle</tt> attribute. If this attribute is missing, and the
-<tt><message>
-</tt>action
+<tt><message></tt>
+action
is nested inside a <tt><bundle></tt> tag, the resource bundle to use
is taken from the enclosing <tt><bundle></tt> tag. Otherwise, the resource
bundle with the default base name given by the
@@ -426,8 +429,8 @@
the servlet context, and an error message of the form <tt>"???<key>???"</tt>
(where
<tt><key></tt> is the name of the undefined key) is output to
-the current <tt>JspWriter
-</tt>object.
+the current <tt>JspWriter</tt>
+object.
<p>If the message corresponding to the given key is <i>compound</i>, that
is, contains one or more variables, it may be supplied with argument values
for these variables via the <tt>messageArgs</tt> attribute or one or more
@@ -526,7 +529,7 @@
numeric value is formatted as a number, currency, or percentage, respectively,
using the default formatting pattern for numbers (currencies, percentages)
of the page's locale, which is determined according to Section 2 of this
-functional description.
+Functional Description.
<p>The result is output to the current
<tt>JspWriter</tt> object, unless
the <tt>var</tt> attribute is given, in which case it is stored (as a string)
@@ -587,7 +590,7 @@
using the default formatting pattern for numbers (currencies, percentages)
of the locale specified by the <tt>parseLocale</tt> attribute. If the <tt>parseLocale</tt>
attribute is missing, the page's locale is used, which is determined according
-to Section 2 of this functional description.
+to Section 2 of this Functional Description.
<p>If the number specified via the <tt>value</tt> attribute uses a format
different from the page locale's default, the pattern required to parse
it may be specified using the <tt>pattern</tt> attribute.
@@ -614,7 +617,7 @@
attribute are formatted, using one of the predefined formatting styles
for dates (specified via the <tt>dateStyle</tt> attribute) and times (specified
via the <tt>timeStyle</tt> attribute) of the page's locale, which is determined
-according to Section 2 of this functional description. Legal values
+according to Section 2 of this Functional Description. Legal values
for the
<tt>dateStyle</tt> and <tt>timeStyle</tt> attributes are "default",
"short", "medium ", "long", and "full" (default: "default").
@@ -687,7 +690,7 @@
(specified via the <tt>timeStyle</tt> attribute) of the locale specified
by the <tt>parseLocale</tt> attribute. If the <tt>parseLocale</tt> attribute
is missing, the page's locale is used, which is determined according to
-Section 2 of this functional description. Legal values for the
+Section 2 of this Functional Description. Legal values for the
<tt>dateStyle</tt>
and <tt>timeStyle</tt> attributes are "default", "short", "medium ", "long",
and "full" (default: "default").
@@ -695,8 +698,8 @@
to parse it may be specified via the <tt>pattern</tt> attribute.
<p>If the given time information does not specify a time zone, it is interpreted
in the time zone given by the <tt>timeZone</tt> attribute. If this
-attribute is missing, and the <tt><parseDate>
-</tt>action is nested
+attribute is missing, and the <tt><parseDate></tt>
+action is nested
inside a <tt><timeZone></tt> tag, the time zone is taken from the enclosing
<tt><timeZone></tt>
tag. Otherwise, the default time zone given by the
@@ -743,18 +746,18 @@
resource bundle for exception messages.
<p>Otherwise, the <tt><exception></tt> action uses the return value
of the exception's
-<tt>getMessageKey()</tt> method as the key . If <tt>getMessageKey</tt>
+<tt>getMessageKey()</tt> method as the key . If <tt>getMessageKey()</tt>
returns null, the exception's fully qualified class name is used as the
key.
<p>The key is looked up in the resource bundle given by the <tt>bundle</tt>
attribute. If this attribute is missing, and the
-<tt><exception> </tt>action
-is nested inside a <tt><bundle> </tt>tag, the resource bundle to use
-is taken from the enclosing <tt><bundle></tt> tag. Otherwise, the default
-resource bundle for exception messages, whose default base name is given
-by the <tt>javax.servlet.jsp.jstl.i18n.exception.basename</tt> scoped attribute,
-is used. This attribute is searched in the page, request, session (if valid),
-and application scope(s) (in this order).
+<tt><exception></tt>
+action is nested inside a <tt><bundle></tt> tag, the resource bundle
+to use is taken from the enclosing <tt><bundle></tt> tag. Otherwise,
+the default resource bundle for exception messages, whose default base
+name is given by the <tt>javax.servlet.jsp.jstl.i18n.exception.basename</tt>
+scoped attribute, is used. This attribute is searched in the page, request,
+session (if valid), and application scope(s) (in this order).
<p>The result of looking up the key in the resource bundle is used as the
localized exception message. If the key is not found in the resource bundle,
or the default resource bundle for exception messages does not exist, the
@@ -775,29 +778,28 @@
The <tt><requestEncoding></tt> action may be used to set the request's
character encoding, in order to be able to correctly decode request parameter
values whose encoding is different from ISO-8859-1. This action is
-needed because browsers do not follow the HTTP spec by failing to include
-a <tt>Content-Type</tt> header in their requests.
+needed because browsers do not follow the HTTP specification by failing
+to include a <tt>Content-Type</tt> header in their requests.
<p>More specifically, the purpose of the <tt><requestEncoding></tt>
action is to set the request encoding to be the same as the response encoding
-in a page invoked by a form included in the response. Even when the encoding
-of the page that is generating the response containing the form is specified
-via the <tt>contentType</tt> attribute of a page directive, the response's
-locale (and thus character encoding) may differ from the value specified
-in the page directive if the page uses a <tt><locale> </tt>action or
-has enabled browser-sensing capabilities for locales, in which case the
-tag handler implementation of the I18N-capable formatting action calls
-<tt>ServletResponse.setLocale()</tt> (which also sets the response's encoding)
-with the specified or best-matching locale, respectively.
-<p>This assumes that the JSP container calls <tt>ServletResponse.setContentType()</tt>
+in a page invoked by a form included in the response. This is needed because
+even if the encoding of the page that is generating the response containing
+the form is specified via the <tt>contentType</tt> attribute of a page
+directive, the response's actual locale (and thus character encoding) may
+differ from the value specified in the page directive if the page contains
+an I18N-capable formatting action which sets the response's locale (and
+thus character encoding) by calling <tt>ServletResponse.setLocale()</tt>,
+thereby overriding any encoding specified in the page directive (see Section
+3). This assumes that the JSP container calls <tt>ServletResponse.setContentType()</tt>
(with the value of the page directive's <tt>contentType</tt> attribute,
if present) at the beginning of the page, and that any subsequent call
-to<tt> ServletResponse.setLocale() </tt>(by an I18N-capable formatting
+to <tt>ServletResponse.setLocale()</tt> (by any I18N-capable formatting
action in the page) overrides the page's existing encoding, so that the
-locale (and encoding) set by the last I18N-capable formatting action wins.
-(This assumes that the response is buffered with a big enough buffer size,
-since <tt>setLocale()</tt> and <tt>setContentType()</tt> must be called
-before <tt>ServletResponse.getWriter()</tt> in order for the charset to
-affect the construction of the writer.)
+locale (and encoding) set by the last I18N-capable formatting action in
+the page wins. (This assumes that the response is buffered with a big enough
+buffer size, since <tt>ServletResponse.setLocale()</tt> and <tt>ServletResponse.setContentType()</tt>
+must be called before <tt>ServletResponse.getWriter()</tt> in order for
+the specified locale or charset to affect the construction of the writer.)
<p>Example:
<p> <tt><fmt:requestEncoding value="Shift_JIS" /></tt>
<p>This action calls the <tt>setCharacterEncoding()</tt> method on the
@@ -814,16 +816,40 @@
and application scope(s) (in this order). If this attribute is not found,
the default character encoding (ISO-8859-1) is used.
<h3>
-17. Configuration parameters</h3>
-This section discusses I18N- and formatting-related initialization parameters
-in a web application's deployment descriptor (DD) file.
+17. Context configuration parameters</h3>
+This section discusses I18N- and formatting-related context configuration
+parameters that may be specified in a web application's deployment descriptor.
+<h4>
+17.1 javax.servlet.jsp.jstl.i18n.locale</h4>
+This parameter specifies the application's default locale. By specifying
+this parameter, browser-sensing capabilities for locales are disabled.
+<p>Example:
+<p><tt> <web-app></tt>
+<br><tt> <context-param></tt>
+<br><tt> <param-name>javax.servlet.jsp.jstl.i18n.locale</param-name></tt>
+<br><tt> <param-value>fr-CA</param-value></tt>
+<br><tt> </context-param></tt>
+<br><tt> </web-app></tt>
+<h4>
+17.2 javax.servlet.jsp.jstl.i18n.fallbackLocale</h4>
+This parameter specifies the application's default fallback locale for
+resource bundles, which is used if browser-sensing capabilities are enabled,
+but none of the available locales for the resource bundle in question match
+any of the client's preferred locales.
+<p>Example:
+<p><tt> <web-app></tt>
+<br><tt> <context-param></tt>
+<br><tt> <param-name>javax.servlet.jsp.jstl.i18n.fallbackLocale</param-name></tt>
+<br><tt> <param-value>fr-CA</param-value></tt>
+<br><tt> </context-param></tt>
+<br><tt> </web-app></tt>
<h4>
-17.1 javax.servlet.jsp.jstl.i18n.basename</h4>
+17.3 javax.servlet.jsp.jstl.i18n.basename</h4>
This parameter specifies the base name of the application's default resource
bundle, which is used if a <tt><message></tt> action does not specify
a <tt>bundle</tt> attribute and is not nested inside a
-<tt><bundle>
-</tt>action.
+<tt><bundle></tt>
+action.
<p>Example:
<p><tt> <web-app></tt>
<br><tt> <context-param></tt>
@@ -832,7 +858,7 @@
<br><tt> </context-param></tt>
<br><tt> </web-app></tt>
<h4>
-17.2 javax.servlet.jsp.jstl.i18n.exception.basename</h4>
+17.4 javax.servlet.jsp.jstl.i18n.exception.basename</h4>
This parameter specifies the base name of the application's default resource
bundle for exception messages, which is used by the <tt><exception></tt>
action.
@@ -844,20 +870,7 @@
<br><tt> </context-param></tt>
<br><tt> </web-app></tt>
<h4>
-17.3 javax.servlet.jsp.jstl.i18n.fallbackLocale</h4>
-This parameter specifies the application's default fallback locale, which
-is used if browser-sensing capabilities are enabled, but none of the available
-locales for the resource bundle in question match any of the client's preferred
-locales.
-<p>Example:
-<p><tt> <web-app></tt>
-<br><tt> <context-param></tt>
-<br><tt> <param-name>javax.servlet.jsp.jstl.i18n.fallbackLocale</param-name></tt>
-<br><tt> <param-value>fr-CA</param-value></tt>
-<br><tt> </context-param></tt>
-<br><tt> </web-app></tt>
-<h4>
-17.4 javax.servlet.jsp.jstl.i18n.timeZone</h4>
+17.5 javax.servlet.jsp.jstl.i18n.timeZone</h4>
This parameter specifies the application's default time zone in which any
times and dates formatted using the <tt><formatDate></tt> action are
represented.
@@ -870,11 +883,11 @@
<br><tt> </web-app></tt>
<h3>
18. Developer support</h3>
-The locale-determination logic for resource bundles described in Section
-2.1.1 is exposed as a general convenience method so it may be used by any
-tag handler implementation that needs to produce localized messages. For
-example, a tag handler's exception messages may be intended directly for
-user consumption on an error page and therefore need to be localized.
+The locale-determination logic for resource bundles, as described in Section
+2.1.1 of this Functional Description, is exposed as a general convenience
+method so that it may be used by any tag handler implementation that needs
+to produce localized messages, e.g., exception messages that are intended
+directly for user consumption on an error page.
<p>The convenience method, named <tt>getLocalizedMessage()</tt> and exposed
by the <tt>org.apache.taglibs.jstl.extra.i18n.Locale</tt> class, looks
up a given message key in the resource bundle with a given base name (or
@@ -893,7 +906,7 @@
<br><tt> * attribute and whose locale is determined
according to the</tt>
<br><tt> * algorithm described in Section 2.1.1
-of the functional description.</tt>
+of this Functional Description.</tt>
<br><tt> *</tt>
<br><tt> * If the javax.servlet.jsp.jstl.i18n.basename
attribute is not found</tt>
@@ -927,7 +940,7 @@
<br><tt> * base name whose locale is determined
according to the</tt>
<br><tt> * algorithm described in Section 2.1.1
-of the functional description.</tt>
+of this Functional Description.</tt>
<br><tt> *</tt>
<br><tt> * If no resource bundle with the given
base name exists,</tt>
@@ -968,7 +981,7 @@
<br><tt> * attribute and whose locale is determined
according to the</tt>
<br><tt> * algorithm described in Section 2.1.1
-of the functional description.</tt>
+of this Functional Description.</tt>
<br><tt> *</tt>
<br><tt> * Before being returned, the result of
the lookup undergoes parametric</tt>
@@ -1012,7 +1025,7 @@
<br><tt> * base name whose locale is determined
according to the</tt>
<br><tt> * algorithm described in Section 2.1.1
-of the functional description.</tt>
+of this Functional Description.</tt>
<br><tt> *</tt>
<br><tt> * Before being returned, the result of
the lookup undergoes parametric</tt>
1.8 +18 -12 jakarta-taglibs/standard/src/org/apache/taglibs/standard/tag/common/fmt/BundleSupport.java
Index: BundleSupport.java
===================================================================
RCS file: /home/cvs/jakarta-taglibs/standard/src/org/apache/taglibs/standard/tag/common/fmt/BundleSupport.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- BundleSupport.java 19 Dec 2001 01:46:02 -0000 1.7
+++ BundleSupport.java 4 Jan 2002 00:29:21 -0000 1.8
@@ -229,25 +229,31 @@
Locale loc = null;
ResourceBundle ret = null;
- loc = (Locale)
- pageContext.findAttribute(LocaleSupport.LOCALE_ATTRIBUTE);
+ loc = LocaleSupport.getLocale(pageContext, LocaleSupport.LOCALE);
if (loc != null) {
- // use resource bundle with specified locale
+ /*
+ * Use resource bundle with specified locale. If specified locale
+ * is not available, fall back on container's default locale.
+ */
ret = getBundle(basename, loc);
} else {
// use resource bundle with best matching locale
ret = getBestMatch(pageContext, basename);
if (ret == null) {
- // no match available, check if fallback locale exists
- String fallback = (String)
- pageContext.findAttribute(FALLBACK_LOCALE);
- if (fallback == null)
- fallback = pageContext.getServletContext().
- getInitParameter(FALLBACK_LOCALE);
- if (fallback != null) {
- // use resource bundle with fallback locale
- loc = LocaleSupport.parseLocale(fallback, null);
+ // no match available, use fallback locale (if present)
+ loc = LocaleSupport.getLocale(pageContext, FALLBACK_LOCALE);
+ if (loc != null) {
ret = getBundle(basename, loc);
+ } else {
+ /*
+ * No fallback locale specified. Use container's default
+ * locale, which was already considered by
+ * ResourceBundle.getBundle() in getBestMatch(), but was
+ * not returned by the latter, since it did not match
+ * the language/country of any of the client's preferred
+ * locales
+ */
+ ret = getBundle(basename, Locale.getDefault());
}
}
}
1.6 +34 -4 jakarta-taglibs/standard/src/org/apache/taglibs/standard/tag/common/fmt/LocaleSupport.java
Index: LocaleSupport.java
===================================================================
RCS file: /home/cvs/jakarta-taglibs/standard/src/org/apache/taglibs/standard/tag/common/fmt/LocaleSupport.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- LocaleSupport.java 12 Dec 2001 01:24:19 -0000 1.5
+++ LocaleSupport.java 4 Jan 2002 00:29:21 -0000 1.6
@@ -74,8 +74,7 @@
//*********************************************************************
// Package-scoped constants
- static final String LOCALE_ATTRIBUTE =
- "javax.servlet.jsp.jstl.i18n.locale";
+ static final String LOCALE = "javax.servlet.jsp.jstl.i18n.locale";
//*********************************************************************
@@ -125,7 +124,7 @@
public int doEndTag() throws JspException {
Locale locale = parseLocale(value, variant);
- pageContext.setAttribute(LOCALE_ATTRIBUTE, locale, scope);
+ pageContext.setAttribute(LOCALE, locale, scope);
setResponseLocale(pageContext, locale);
return EVAL_PAGE;
@@ -252,7 +251,7 @@
Tag fromTag,
boolean format,
Locale[] avail) {
- Locale ret = (Locale) pageContext.findAttribute(LOCALE_ATTRIBUTE);
+ Locale ret = (Locale) pageContext.findAttribute(LOCALE);
if (ret == null) {
Tag t = findAncestorWithClass(fromTag, BundleSupport.class);
if (t != null) {
@@ -282,6 +281,37 @@
*/
if (format)
LocaleSupport.setResponseLocale(pageContext, ret);
+
+ return ret;
+ }
+
+ /*
+ * Returns the locale specified by the named scoped attribute or context
+ * configuration parameter.
+ *
+ * <p> The named scoped attribute is searched in the page, request,
+ * session (if valid), and application scope(s) (in this order). If no such
+ * attribute exists in any of the scopes, the locale is taken from the
+ * named context configuration parameter.
+ *
+ * @param pageContext the page in which to search for the named scoped
+ * attribute or context configuration parameter
+ * @param name the name of the scoped attribute or context configuration
+ * parameter
+ *
+ * @return the locale specified by the named scoped attribute or context
+ * configuration parameter, or <tt>null</tt> if no scoped attribute or
+ * configuration parameter with the given name exists
+ */
+ static Locale getLocale(PageContext pageContext, String name) {
+ Locale ret = (Locale) pageContext.findAttribute(name);
+ if (ret == null) {
+ String loc =
+ pageContext.getServletContext().getInitParameter(name);
+ if (loc != null) {
+ ret = LocaleSupport.parseLocale(loc, null);
+ }
+ }
return ret;
}
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>