com.opensymphony.xwork2.util

Class StrutsLocalizedTextProvider

java.lang.Object

com.opensymphony.xwork2.util.StrutsLocalizedTextProvider

All Implemented Interfaces:

LocalizedTextProvider, Serializable

public class StrutsLocalizedTextProvider
extends Object

Provides support for localization in the framework, it can be used to read only default bundles, or it can search the class hierarchy to find proper bundles.

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected ConcurrentMap<String,ResourceBundle>	bundlesMap
protected boolean	devMode
protected boolean	reloadBundles
protected boolean	searchDefaultBundlesFirst
static String	STRUTS_MESSAGES_BUNDLE
static String	XWORK_MESSAGES_BUNDLE

Constructor Summary

Constructors

Constructor and Description
StrutsLocalizedTextProvider()

Method Summary

Modifier and Type	Method and Description
void	addDefaultResourceBundle(String resourceBundleName) Adds the bundle to the internal list of default bundles.
protected MessageFormat	buildMessageFormat(String pattern, Locale locale)
void	clearBundle(String bundleName) Deprecated. A "no-op" since 6.0.0. Use clearBundle(java.lang.String, java.util.Locale) instead.
protected void	clearBundle(String bundleName, Locale locale) Clear a specific bundle + locale combination from the bundlesMap.
static void	clearDefaultResourceBundles() Deprecated. used only in tests
protected void	clearMissingBundlesCache() Clears the missingBundles contents.
String	findDefaultText(String aTextName, Locale locale) Returns a localized message for the specified key, aTextName.
String	findDefaultText(String aTextName, Locale locale, Object[] params) Returns a localized message for the specified key, aTextName, substituting variables from the array of params into the message.
protected String	findMessage(Class clazz, String key, String indexedKey, Locale locale, Object[] args, Set<String> checked, ValueStack valueStack) Traverse up class hierarchy looking for message.
ResourceBundle	findResourceBundle(String aBundleName, Locale locale) Finds the given resource bundle by it's name.
String	findText(Class aClass, String aTextName, Locale locale) Calls findText(Class aClass, String aTextName, Locale locale, String defaultMessage, Object[] args) with aTextName as the default message.
String	findText(Class aClass, String aTextName, Locale locale, String defaultMessage, Object[] args) Finds a localized text message for the given key, aTextName.
String	findText(Class aClass, String aTextName, Locale locale, String defaultMessage, Object[] args, ValueStack valueStack) Finds a localized text message for the given key, aTextName.
String	findText(ResourceBundle bundle, String aTextName, Locale locale) Finds a localized text message for the given key, aTextName, in the specified resource bundle with aTextName as the default message.
String	findText(ResourceBundle bundle, String aTextName, Locale locale, String defaultMessage, Object[] args) Finds a localized text message for the given key, aTextName, in the specified resource bundle.
String	findText(ResourceBundle bundle, String aTextName, Locale locale, String defaultMessage, Object[] args, ValueStack valueStack) Finds a localized text message for the given key, aTextName, in the specified resource bundle.
protected String	formatWithNullDetection(MessageFormat mf, Object[] args)
protected List<String>	getCurrentBundleNames()
protected ClassLoader	getCurrentThreadContextClassLoader()
protected com.opensymphony.xwork2.util.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg	getDefaultMessage(String key, Locale locale, ValueStack valueStack, Object[] args, String defaultMessage)
protected com.opensymphony.xwork2.util.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg	getDefaultMessageWithAlternateKey(String key, String alternateKey, Locale locale, ValueStack valueStack, Object[] args, String defaultMessage) A helper method that can be used by descendant classes to perform some common two-stage message lookup operations against the default resource bundles.
protected String	getMessage(String bundleName, Locale locale, String key, ValueStack valueStack, Object[] args)
static Locale	localeFromString(String localeStr, Locale defaultLocale) Deprecated. please use LocaleUtils.toLocale(String)
protected void	reloadBundles()
protected void	reloadBundles(Map<String,Object> context)
void	reset() Deprecated. used only in tests
void	setCustomI18NResources(String bundles)
void	setDelegatedClassLoader(ClassLoader classLoader)
void	setDevMode(String devMode)
void	setReloadBundles(String reloadBundles)
void	setSearchDefaultBundlesFirst(String searchDefaultBundlesFirst) Set the searchDefaultBundlesFirst flag state.
protected boolean	unableToFindTextForKey(com.opensymphony.xwork2.util.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg result) Determines if we found the text in the bundles.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

XWORK_MESSAGES_BUNDLE

public static final String XWORK_MESSAGES_BUNDLE

See Also:

Constant Field Values

STRUTS_MESSAGES_BUNDLE

public static final String STRUTS_MESSAGES_BUNDLE

See Also:

Constant Field Values

bundlesMap

protected final ConcurrentMap<String,ResourceBundle> bundlesMap

devMode

protected boolean devMode

reloadBundles

protected boolean reloadBundles

searchDefaultBundlesFirst

protected boolean searchDefaultBundlesFirst

Constructor Detail

StrutsLocalizedTextProvider

public StrutsLocalizedTextProvider()

Method Detail

clearDefaultResourceBundles

@Deprecated
public static void clearDefaultResourceBundles()

Deprecated. used only in tests

Clears the internal list of resource bundles.

localeFromString

@Deprecated
public static Locale localeFromString(String localeStr,
                                                  Locale defaultLocale)

Deprecated. please use LocaleUtils.toLocale(String)

Builds a Locale from a String of the form en_US_foo into a Locale with language "en", country "US" and variant "foo". This will parse the output of Locale.toString().

Parameters:

localeStr - The locale String to parse.

defaultLocale - The locale to use if localeStr is null.

Returns:

requested Locale

findText

public String findText(Class aClass,
                       String aTextName,
                       Locale locale)

Calls findText(Class aClass, String aTextName, Locale locale, String defaultMessage, Object[] args) with aTextName as the default message.

Parameters:

aClass - class name

aTextName - text name

locale - the locale

Returns:

the localized text, or null if none can be found and no defaultMessage is provided

See Also:

findText(Class aClass, String aTextName, Locale locale, String defaultMessage, Object[] args)

findText

public String findText(Class aClass,
                       String aTextName,
                       Locale locale,
                       String defaultMessage,
                       Object[] args)

Finds a localized text message for the given key, aTextName. Both the key and the message itself is evaluated as required. The following algorithm is used to find the requested message:

1. If searchDefaultBundlesFirst is true, look for the message in the default resource bundles first.
2. Look for message in aClass' class hierarchy.
   1. Look for the message in a resource bundle for aClass
   2. If not found, look for the message in a resource bundle for any implemented interface
   3. If not found, traverse up the Class' hierarchy and repeat from the first sub-step
3. If not found and aClass is a ModelDriven Action, then look for message in the model's class hierarchy (repeat sub-steps listed above).
4. If not found, look for message in child property. This is determined by evaluating the message key as an OGNL expression. For example, if the key is user.address.state, then it will attempt to see if "user" can be resolved into an object. If so, repeat the entire process from the beginning with the object's class as aClass and "address.state" as the message key.
5. If not found, look for the message in aClass' package hierarchy.
6. If still not found, look for the message in the default resource bundles (Note: the lookup is not repeated again if searchDefaultBundlesFirst was true).
7. Return defaultMessage

When looking for the message, if the key indexes a collection (e.g. user.phone[0]) and a message for that specific key cannot be found, the general form will also be looked up (i.e. user.phone[*]).

If a message is found, it will also be interpolated. Anything within ${...} will be treated as an OGNL expression and evaluated as such.

Parameters:

aClass - the class whose name to use as the start point for the search

aTextName - the key to find the text message for

locale - the locale the message should be for

defaultMessage - the message to be returned if no text message can be found in any resource bundle

args - arguments resource bundle

Returns:

the localized text, or null if none can be found and no defaultMessage is provided

findText

public String findText(Class aClass,
                       String aTextName,
                       Locale locale,
                       String defaultMessage,
                       Object[] args,
                       ValueStack valueStack)

Finds a localized text message for the given key, aTextName. Both the key and the message itself is evaluated as required. The following algorithm is used to find the requested message:

1. If searchDefaultBundlesFirst is true, look for the message in the default resource bundles first.
2. Look for message in aClass' class hierarchy.
   1. Look for the message in a resource bundle for aClass
   2. If not found, look for the message in a resource bundle for any implemented interface
   3. If not found, traverse up the Class' hierarchy and repeat from the first sub-step
3. If not found and aClass is a ModelDriven Action, then look for message in the model's class hierarchy (repeat sub-steps listed above).
4. If not found, look for message in child property. This is determined by evaluating the message key as an OGNL expression. For example, if the key is user.address.state, then it will attempt to see if "user" can be resolved into an object. If so, repeat the entire process from the beginning with the object's class as aClass and "address.state" as the message key.
5. If not found, look for the message in aClass' package hierarchy.
6. If still not found, look for the message in the default resource bundles (Note: the lookup is not repeated again if searchDefaultBundlesFirst was true).
7. Return defaultMessage

When looking for the message, if the key indexes a collection (e.g. user.phone[0]) and a message for that specific key cannot be found, the general form will also be looked up (i.e. user.phone[*]).

If a message is found, it will also be interpolated. Anything within ${...} will be treated as an OGNL expression and evaluated as such.

If a message is not found a DEBUG level log warning will be logged.

Parameters:

aClass - the class whose name to use as the start point for the search

aTextName - the key to find the text message for

locale - the locale the message should be for

defaultMessage - the message to be returned if no text message can be found in any resource bundle

args - arguments

valueStack - the value stack to use to evaluate expressions instead of the one in the ActionContext ThreadLocal

Returns:

the localized text, or null if none can be found and no defaultMessage is provided

findText

public String findText(ResourceBundle bundle,
                       String aTextName,
                       Locale locale)

Finds a localized text message for the given key, aTextName, in the specified resource bundle with aTextName as the default message.

If a message is found, it will also be interpolated. Anything within ${...} will be treated as an OGNL expression and evaluated as such.

Parameters:

bundle - a resource bundle name

aTextName - text name

locale - the locale

Returns:

the localized text, or null if none can be found and no defaultMessage is provided

See Also:

findText(java.util.ResourceBundle, String, java.util.Locale, String, Object[])

findText

public String findText(ResourceBundle bundle,
                       String aTextName,
                       Locale locale,
                       String defaultMessage,
                       Object[] args)

Finds a localized text message for the given key, aTextName, in the specified resource bundle.

If a message is found, it will also be interpolated. Anything within ${...} will be treated as an OGNL expression and evaluated as such.

If a message is not found a WARN log will be logged.

Parameters:

bundle - the bundle

aTextName - the key

locale - the locale

defaultMessage - the default message to use if no message was found in the bundle

args - arguments for the message formatter.

Returns:

the localized text, or null if none can be found and no defaultMessage is provided

addDefaultResourceBundle

public void addDefaultResourceBundle(String resourceBundleName)

Adds the bundle to the internal list of default bundles. If the bundle already exists in the list it will be re-added.

Specified by:

addDefaultResourceBundle in interface LocalizedTextProvider

Parameters:

resourceBundleName - the name of the bundle to add.

getCurrentBundleNames

protected List<String> getCurrentBundleNames()

getCurrentThreadContextClassLoader

protected ClassLoader getCurrentThreadContextClassLoader()

setCustomI18NResources

public void setCustomI18NResources(String bundles)

findDefaultText

public String findDefaultText(String aTextName,
                              Locale locale)

Returns a localized message for the specified key, aTextName. Neither the key nor the message is evaluated.

Specified by:

findDefaultText in interface LocalizedTextProvider

Parameters:

aTextName - the message key

locale - the locale the message should be for

Returns:

a localized message based on the specified key, or null if no localized message can be found for it

findDefaultText

public String findDefaultText(String aTextName,
                              Locale locale,
                              Object[] params)

Returns a localized message for the specified key, aTextName, substituting variables from the array of params into the message. Neither the key nor the message is evaluated.

Specified by:

findDefaultText in interface LocalizedTextProvider

Parameters:

aTextName - the message key

locale - the locale the message should be for

params - an array of objects to be substituted into the message text

Returns:

A formatted message based on the specified key, or null if no localized message can be found for it

findText

public String findText(ResourceBundle bundle,
                       String aTextName,
                       Locale locale,
                       String defaultMessage,
                       Object[] args,
                       ValueStack valueStack)

Finds a localized text message for the given key, aTextName, in the specified resource bundle.

If a message is found, it will also be interpolated. Anything within ${...} will be treated as an OGNL expression and evaluated as such.

If a message is not found a WARN log will be logged.

Specified by:

findText in interface LocalizedTextProvider

Parameters:

bundle - the bundle

aTextName - the key

locale - the locale

defaultMessage - the default message to use if no message was found in the bundle

args - arguments for the message formatter.

valueStack - the OGNL value stack.

Returns:

the localized text, or null if none can be found and no defaultMessage is provided

setDelegatedClassLoader

public void setDelegatedClassLoader(ClassLoader classLoader)

Parameters:

classLoader - a ClassLoader to look up the bundle from if none can be found on the current thread's classloader

clearBundle

public void clearBundle(String bundleName)

Deprecated. A "no-op" since 6.0.0. Use clearBundle(java.lang.String, java.util.Locale) instead.

Clear a specific bundle from the bundlesMap. Warning: This method is now a "no-op". It was ineffective due to the way the bundlesMap is used in combination with locale. Descendants should use the method clearBundle(java.lang.String, java.util.Locale) instead.

Parameters:

bundleName - The bundle to remove from the bundle map

clearBundle

protected void clearBundle(String bundleName,
                           Locale locale)

Clear a specific bundle + locale combination from the bundlesMap. Intended for descendants to use clear a bundle + locale combination.

Parameters:

bundleName - The bundle (combined with locale) to remove from the bundle map

locale - Provides the locale to combine with the bundle to get the key

Since:

6.0.0

clearMissingBundlesCache

protected void clearMissingBundlesCache()

Clears the missingBundles contents. This allows descendants to clear the "missing bundles cache" when desired (or needed). Note: This method may be used when the bundlesMap state has changed in such a way that bundles that were previously "missing" may now be available (e.g. after calling addDefaultResourceBundle(java.lang.String) when the AbstractLocalizedTextProvider has already been used for failed bundle lookups of a given key, or some transitory state made a bundle lookup fail.

Since:

6.0.0

reloadBundles

protected void reloadBundles()

reloadBundles

protected void reloadBundles(Map<String,Object> context)

buildMessageFormat

protected MessageFormat buildMessageFormat(String pattern,
                                           Locale locale)

formatWithNullDetection

protected String formatWithNullDetection(MessageFormat mf,
                                         Object[] args)

setReloadBundles

public void setReloadBundles(String reloadBundles)

setDevMode

public void setDevMode(String devMode)

setSearchDefaultBundlesFirst

public void setSearchDefaultBundlesFirst(String searchDefaultBundlesFirst)

Set the searchDefaultBundlesFirst flag state. This flag may be used by descendant TextProvider implementations to determine if default bundles should be searched for messages first (before the standard flow of the LocalizedTextProvider implementation the descendant provides).

Parameters:

searchDefaultBundlesFirst - provide String "true" or "false" to set the flag state accordingly.

Since:

6.0.0

findResourceBundle

public ResourceBundle findResourceBundle(String aBundleName,
                                         Locale locale)

Finds the given resource bundle by it's name.

Will use Thread.currentThread().getContextClassLoader() as the classloader.

Specified by:

findResourceBundle in interface LocalizedTextProvider

Parameters:

aBundleName - the name of the bundle (usually it's FQN classname).

locale - the locale.

Returns:

the bundle, null if not found.

reset

@Deprecated
public void reset()

Deprecated. used only in tests

Clears all the internal lists.

unableToFindTextForKey

protected boolean unableToFindTextForKey(com.opensymphony.xwork2.util.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg result)

Determines if we found the text in the bundles.

Parameters:

result - the result so far

Returns:

true if we could not find the text, false if the text was found (=success).

getDefaultMessage

protected com.opensymphony.xwork2.util.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg getDefaultMessage(String key,
                                                                                                                  Locale locale,
                                                                                                                  ValueStack valueStack,
                                                                                                                  Object[] args,
                                                                                                                  String defaultMessage)

Returns:

the default message.

getDefaultMessageWithAlternateKey

protected com.opensymphony.xwork2.util.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg getDefaultMessageWithAlternateKey(String key,
                                                                                                                                  String alternateKey,
                                                                                                                                  Locale locale,
                                                                                                                                  ValueStack valueStack,
                                                                                                                                  Object[] args,
                                                                                                                                  String defaultMessage)

A helper method that can be used by descendant classes to perform some common two-stage message lookup operations against the default resource bundles. The default resource bundles are searched for a value using key first, then alternateKey when the first search fails, then utilizing defaultMessage (which may be null) if both key lookup operations fail.

A known use case is when a key indexes a collection (e.g. user.phone[0]) for which some specific keys may exist, but not all, along with a general key (e.g. user.phone[*]). In such cases the specific key would be passed in the key parameter and the general key would be passed in the alternateKey parameter.

Parameters:

key - the initial key to search for a value within the default resource bundles.

alternateKey - the alternate (fall-back) key to search for a value within the default resource bundles, if the initial key lookup fails.

locale - the Locale to be used for the default resource bundle lookup.

valueStack - the ValueStack associated with the operation.

args - the argument array for parameterized messages (may be null).

defaultMessage - the default message String to use if both key lookup operations fail.

Returns:

the GetDefaultMessageReturnArg result containing the processed message lookup (by key first, then alternateKey if key's lookup fails). If both key lookup operations fail, defaultMessage is used for processing. If defaultMessage is null then the return result may be null.

getMessage

protected String getMessage(String bundleName,
                            Locale locale,
                            String key,
                            ValueStack valueStack,
                            Object[] args)

Returns:

the message from the named resource bundle.

findMessage

protected String findMessage(Class clazz,
                             String key,
                             String indexedKey,
                             Locale locale,
                             Object[] args,
                             Set<String> checked,
                             ValueStack valueStack)

Traverse up class hierarchy looking for message. Looks at class, then implemented interface, before going up hierarchy.

Returns:

the message