com.beasys.commerce.i18n.jsp.tags
Class LocalizeTag

java.lang.Object
  |
  +--javax.servlet.jsp.tagext.TagSupport
        |
        +--com.beasys.commerce.i18n.jsp.tags.I18nTag
              |
              +--com.beasys.commerce.i18n.jsp.tags.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.beasys.commerce.i18n.jsp.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 MessageBundle	bundle
protected static java.lang.String	BUNDLE
protected java.lang.String	bundleName
protected java.lang.String	charset
protected static java.util.HashMap	charsetMap
protected java.lang.String	contentType
protected java.lang.String	country
protected static java.lang.String	COUNTRY
protected java.lang.String	language
protected static java.lang.String	LANGUAGE
protected java.lang.String[]	languages
protected java.util.Locale	locale
protected java.lang.String	variant
protected static java.lang.String	VARIANT

Fields inherited from class com.beasys.commerce.i18n.jsp.tags.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.beasys.commerce.i18n.jsp.tags.I18nTag

debug, info, logLevelDebug, logLevelInfo, warning

Methods inherited from class javax.servlet.jsp.tagext.TagSupport

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

protected static final java.lang.String BUNDLE

LANGUAGE

protected static final java.lang.String LANGUAGE

COUNTRY

protected static final java.lang.String COUNTRY

VARIANT

protected static final java.lang.String VARIANT

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

charset

protected java.lang.String charset

contentType

protected java.lang.String contentType

locale

protected java.util.Locale locale

language

protected java.lang.String language

bundle

protected MessageBundle 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()