Overview | Package | Class | Tree | Deprecated | Index | Help
| © 2002 BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.bea.p13n.taglib.i18n
Class LocalizeTag

    java.lang.Object
      |
      +--javax.servlet.jsp.tagext.TagSupport
            |
            +--com.bea.p13n.taglib.i18n.I18nTag
                  |
                  +--com.bea.p13n.taglib.i18n.LocalizeTag

public class LocalizeTag
extends I18nTag

Corresponds to `<i18n:localize>`.

This tag is used in the localization of JSP pages. All pages that have an internationalization requirement should use this tag in conjunction with the <i18n:getMessage> tag, so long as they are not being included in larger pages. If the page is being included in a larger page, that page should be the one to use `<i18n:localize>`. This is because `<i18n:localize>` sets the byte encoding for the page, and you can only do this once at the beginning before any bytes are written out.

This tag allows a page developer to define the language, country, variant, and base bundle name to be used throughout a page when accessing resource bundles via the `<i18n:getMessage>` tag. This serves as a convenience so that these things need only be specified once and not for every `<i18n:getMessage>` tag. This tag also specifies a character encoding and content type to be specified for a JSP page. Because of this, the tag should be used as early in the page as possible - before anything is written to the output stream - so that the bytes are properly encoded.

Note: the use of this tag should exclude the use of the `<%@ page contentType="<something>" >` page directive defined in the JSP specification. This is because the directive is unnecessary if you're using this tag, and can result in inconsistent or wrong `contentType` declarations.

The conventions used in this tag and in the `<i18n:getMessage>` tag are based on the more general conventions used to internationalize Java applications. Studying the Javadoc for `java.util.ResourceBundle` and `java.util.Locale` will help the tag user understand the ideas that served as the foundation for these tags.

This tag uses the `com.bea.p13n.taglib.i18n.JspMessageBundle` class. Unlike a ResourceBundle, the JspMessageBundle looks only for properties files (like the PropertyResourceBundle) within the ServletContext (on the doc path). This means that JSP developers can keep MessageBundle properties files relative to the associated JSP page, instead of having to have them on the `CLASSPATH`. Another difference is that MessageBundles are specified using the "/" character instead of the ".". For instance, the path to a MessageBundle might look like "`/jsp/ordersystem/placeOrder`".

If no bundle name is specified, then bundle name defaults to the name of the JSP page. For instance, if you have a JSP page called "`placeOrder.jsp`", then JspMessageBundle would look in the same directory for a "`placeOrder.properties`" file to serve as the JspMessageBundle for the "`placeOrder.jsp`" page.

If a bundle name is specicified, then it can be specified absolutely or relatively. Absolute paths are treated as such if they begin with a "/". Paths not beginning with "/" are searched for relative to the JSP page's location.

When searching for a JspMessageBundle, both the doc root and repository directories are considered, in that order. Repository directories are If no message bundle can be found, a MissingResourceException occurs. directories specified during Servlet registration and serve as a place to store common files such as images. See the WLPS documentation for a more in-depth description of the repository directory convention.

The tag works by examining all provided parameters and default parameters and doing the following:

1. Determining the base bundle name

   If a base bundle name is not provided, the bundle name defaults to the name of the JSP page + ".properties". For example, if the name of the JSP page is "placeOrder.jsp", then the default bundle name would be "placeOrder.properties".

2. Determining the language to use

   - If no language is specified, the default is US English (`en_us`).
   - If a bundle for the specified language doesn't exist (or cannot be found), the tag cycles through other languages accepted by the client (if any) to see if a match between an accepted language and a provided bundle can be made. If a match can be made, the first language that matches is the language that is used. If no message bundle can be found, then language is set to nothing ("") and "UTF-8" encoding will be used unless otherwise specified.

3. Determining character encoding (`charset`) to use

   - If character encoding is not specified, a charset appropriate for the language determined in step 2 is chosen. It is generally encouraged to use this functionality by leaving the charset unspecified since this is more flexible and fault tolerant. An exception might be when two languages like Greek and Japanese need to be displayed in the same page, so the page developer chooses to set the charset to "UTF-8" due to this fact.
   - If a character encoding is specified, then that will be the charset used by the page, regardless of what language was chosen in step 2.

   Once the charset is determined, it is specified for the page by calling the `setContentType()` method on the servlet response. A call to `setContentType()` might look like this:

   `response.setContentType("text/html; charset=ISO-8859-1");`

   When specifying the encoding, it is important to note that there is no guaranty of what encodings are supported for your particular operating system, virtual machine, or client browsers. See http://www.java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html to see what Sun supports in their J2SE package.

   If for any reason an encoding for a language cannot be determined and none is specified, UTF-8 encoding is used.

   The table below shows how this tag will map languages to character encodings by default. Note that you can override the tag's default character encoding by specifying your own by the `charset` parameter if you need to.

   Language Code | Language Name | Character Encoding
   ar | Arabic | ISO-8859-6
   be | Byelorussian | ISO-8859-5
   bg | Bulgarian | ISO-8859-5
   ca | Catalan | ISO-8859-1
   cs | Czech | ISO-8859-2
   da | Danish | ISO-8859-1
   de | German | ISO-8859-1
   el | Greek | ISO-8859-7
   en | English | ISO-8859-1
   es | Spanish | ISO-8859-1
   et | Estonian | ISO-8859-1
   fi | Finnish | ISO-8859-1
   fr | French | ISO-8859-1
   hr | Croatian | ISO-8859-2
   hu | Hungarian | ISO-8859-2
   is | Icelandic | ISO-8859-1
   it | Italian | ISO-8859-1
   iw | Hebrew | ISO-8859-8
   ja | Japanese | Shift_JIS
   ko | Korean | EUC_KR
   lt | Lithuanian | ISO-8859-2
   lv | Latvian (Lettish) | ISO-8859-2
   mk | Macedonian | ISO-8859-5
   nl | Dutch | ISO-8859-1
   no | Norwegian | ISO-8859-1
   pl | Polish | ISO-8859-2
   pt | Portuguese | ISO-8859-1
   ro | Romanian | ISO-8859-2
   ru | Russian | ISO-8859-5
   sh | Serbo-Croatian | ISO-8859-5
   sk | Slovak | ISO-8859-2
   sl | Slovenian | ISO-8859-2
   sq | Albanian | ISO-8859-2
   sr | Serbian | ISO-8859-5
   sv | Swedish | ISO-8859-1
   th | Thai | TIS620
   tr | Turkish | ISO-8859-9
   uk | Ukrainian | ISO-8859-5
   zh | Chinese | GB2312
   other |  | UTF-8

Tag Parameters:

Tag Attribute | Required | Description
bundleName | no | The base name of the MessageBundle to use to retrieve localized text for a JSP page.
language | no | A String - two character ISO Languange Code - denoting the user's preferred language, or a String[ ] containing a list of preferred languages for a user with stronger preferences indexed lower (earlier) in the array.
country | no | The two character ISO Country Code for a country. For example, this code would be used to look for a MessageBundle containing text localized to English speaking users in the US as apposed to English speaking users in the UK.
variant | no | A String representing a locale's variant. The variant is used when localization demands a more specific locale than can be denoted by having just language and a country.
locale | no | Instead of specifying language, country, and variant as Strings, a `java.util.Locale` object can be provided. If provided, the values in the Locale's language, country, and variant fields will negate any of the other language, country, and variant values passed to the tag as Strings.
charset | no | The name of the character encoding set to use for this page - defaults to "UTF-8" if no encoding can be determined for the chosen language, otherwise an encoding approprite for the chosen language is used.
contentType | no | The type of content contained in the page, defaults to "`text/html`".

See Also:
  `GetMessageTag`, Serialized Form

Field Summary
`protected static boolean` | `allowEncodedPropFiles`
`protected java.util.ResourceBundle` | `bundle`
`static java.lang.String` | `BUNDLE` name of the attribute in the PageContext (request scoped) that contains a reference to the JspMessageBundle setup by the Localize tag.
`static java.lang.String` | `BUNDLE_NAME` name of the attribute in the PageContext (request scoped) that contains the String with the name of the bundle set up by the Localize tag.
`protected java.lang.String` | `bundleName`
`protected static java.util.HashMap` | `charsetMap`
`protected java.lang.String` | `contentType`
`protected java.lang.String` | `country`
`static java.lang.String` | `COUNTRY` name of the attribute in the PageContext (request scoped) that contains the String with the country for the bundle set up by the Localize tag.
`protected static boolean` | `initedAllowEncodedPropFiles`
`protected java.lang.String` | `language`
`static java.lang.String` | `LANGUAGE` name of the attribute in the PageContext (request scoped) that contains the String with the language for the bundle set up by the Localize tag.
`protected java.lang.String[]` | `languages`
`protected java.util.Locale` | `locale`
`protected java.lang.String` | `pageCharset`
`protected java.lang.String` | `propCharset`
`protected static java.lang.String` | `PROPCHARSET`
`protected java.lang.String` | `variant`
`static java.lang.String` | `VARIANT` name of the attribute in the PageContext (request scoped) that contains the String with the variant for the bundle set up by the Localize tag.

Fields inherited from class com.bea.p13n.taglib.i18n.I18nTag
`logLevel, printStackTraces, verbose`

Fields inherited from class javax.servlet.jsp.tagext.TagSupport
`id, pageContext`

Constructor Summary
`LocalizeTag()`

Method Summary
`protected java.util.ArrayList` | `buildLanguagesList()`
`protected void` | `determineCharset()`
`protected void` | `determineLanguage()` Go through the languages and see if a bundle can be paired up with any of these languages.
`int` | `doStartTag()`
`protected void` | `ensureCharsetMapCreated()`
`java.lang.String` | `getBundleName()`
`java.lang.String` | `getCharset()`
`java.lang.String` | `getContentType()`
`java.lang.String` | `getCountry()`
`java.lang.String[]` | `getLanguage()`
`java.util.Locale` | `getLocale()`
`java.lang.String` | `getVariant()`
`protected java.lang.String` | `mapLanguageToCharset(java.lang.String languageCode)`
`void` | `release()`
`void` | `setBundleName(java.lang.String bundleName)`
`void` | `setCharset(java.lang.String charset)`
`void` | `setContentType(java.lang.String contentType)`
`void` | `setCountry(java.lang.String country)`
`protected void` | `setDefaults()`
`void` | `setLanguage(java.lang.String language)`
`void` | `setLanguage(java.lang.String[] languages)`
`void` | `setLocale(java.util.Locale locale)`
`void` | `setVariant(java.lang.String variant)`

Methods inherited from class com.bea.p13n.taglib.i18n.I18nTag
`debug, info, logLevelDebug, logLevelInfo, logLevelWarning, warning, warning`

Methods inherited from class javax.servlet.jsp.tagext.TagSupport
`doAfterBody, doEndTag, findAncestorWithClass, getId, getParent, getValue, getValues, removeValue, setId, setPageContext, setParent, setValue`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### BUNDLE

    public static final java.lang.String BUNDLE

  name of the attribute in the PageContext (request scoped) that contains a reference to the JspMessageBundle setup by the Localize tag.

### BUNDLE_NAME

    public static final java.lang.String BUNDLE_NAME

  name of the attribute in the PageContext (request scoped) that contains the String with the name of the bundle set up by the Localize tag.

### LANGUAGE

    public static final java.lang.String LANGUAGE

  name of the attribute in the PageContext (request scoped) that contains the String with the language for the bundle set up by the Localize tag.

### COUNTRY

    public static final java.lang.String COUNTRY

  name of the attribute in the PageContext (request scoped) that contains the String with the country for the bundle set up by the Localize tag.

### VARIANT

    public static final java.lang.String VARIANT

  name of the attribute in the PageContext (request scoped) that contains the String with the variant for the bundle set up by the Localize tag.

### PROPCHARSET

    protected static final java.lang.String PROPCHARSET

### initedAllowEncodedPropFiles

    protected static boolean initedAllowEncodedPropFiles

### allowEncodedPropFiles

    protected static boolean allowEncodedPropFiles

### charsetMap

    protected static java.util.HashMap charsetMap

### bundleName

    protected java.lang.String bundleName

### languages

    protected java.lang.String[] languages

### country

    protected java.lang.String country

### variant

    protected java.lang.String variant

### pageCharset

    protected java.lang.String pageCharset

### propCharset

    protected java.lang.String propCharset

### contentType

    protected java.lang.String contentType

### locale

    protected java.util.Locale locale

### language

    protected java.lang.String language

### bundle

    protected java.util.ResourceBundle bundle

Constructor Detail

### LocalizeTag

    public LocalizeTag()

Method Detail

### release

    public void release()

  Overrides:
    release in class javax.servlet.jsp.tagext.TagSupport

### setDefaults

    protected void setDefaults()

### getBundleName

    public java.lang.String getBundleName()

### setBundleName

    public void setBundleName(java.lang.String bundleName)

### getLanguage

    public java.lang.String[] getLanguage()

### setLanguage

    public void setLanguage(java.lang.String language)

### setLanguage

    public void setLanguage(java.lang.String[] languages)

### getCountry

    public java.lang.String getCountry()

### setCountry

    public void setCountry(java.lang.String country)

### getVariant

    public java.lang.String getVariant()

### setVariant

    public void setVariant(java.lang.String variant)

### getLocale

    public java.util.Locale getLocale()

### setLocale

    public void setLocale(java.util.Locale locale)

### getCharset

    public java.lang.String getCharset()

### setCharset

    public void setCharset(java.lang.String charset)

### getContentType

    public java.lang.String getContentType()

### setContentType

    public void setContentType(java.lang.String contentType)

### doStartTag

    public int doStartTag()

  Overrides:
    doStartTag in class javax.servlet.jsp.tagext.TagSupport

### determineLanguage

    protected void determineLanguage()

  Go through the languages and see if a bundle can be paired up with any of these languages.

### determineCharset

    protected void determineCharset()

### buildLanguagesList

    protected java.util.ArrayList buildLanguagesList()

### mapLanguageToCharset

    protected java.lang.String mapLanguageToCharset(java.lang.String languageCode)

### ensureCharsetMapCreated

    protected void ensureCharsetMapCreated()

Overview | Package | Class | Tree | Deprecated | Index | Help
| © 2002 BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002 BEA Systems, Inc. All Rights Reserved