Package org.apache.struts2.text

# Class GlobalLocalizedTextProvider

java.lang.Object
org.apache.struts2.text.GlobalLocalizedTextProvider

All Implemented Interfaces:
  `Serializable`, `LocalizedTextProvider`

public class GlobalLocalizedTextProvider extends Object
Provides support for localization in the framework, it can be used to read only default bundles.

Note that unlike `StrutsLocalizedTextProvider`, this class `GlobalLocalizedTextProvider` will only search the default bundles for localized text.

See Also:
  - Serialized Form

- ## Field Summary

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GlobalLocalizedTextProvider()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addDefaultResourceBundle(String bundleName)`
  Adds the bundle to the internal list of default bundles.
  `protected MessageFormat`
  `buildMessageFormat(String pattern, Locale locale)`
  `protected void`
  `clearBundle(String bundleName, Locale locale)`
  Clear a specific bundle + locale combination from the `bundlesMap`.
  `protected void`
  `clearMissingBundlesCache()`
  Clears the `missingBundles` contents.
  `protected String`
  `extractIndexedName(String textKey)`
  `String`
  `findDefaultText(String textKey, Locale locale)`
  Returns a localized message for the specified key, aTextName.
  `String`
  `findDefaultText(String textKey, 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 bundleName, Locale locale)`
  Finds the given resource bundle by it's name.
  `String`
  `findText(Class<?> startClazz, String textKey, Locale locale)`
  Calls `LocalizedTextProvider.findText(Class startClazz, String textKey, Locale locale, String defaultMessage, Object[] args)` with textKey as the default message.
  `String`
  `findText(Class<?> startClazz, String textKey, Locale locale, String defaultMessage, Object[] args)`
  Finds a localized text message for the given key, textKey.
  `String`
  `findText(Class<?> startClazz, String textKey, Locale locale, String defaultMessage, Object[] args, ValueStack valueStack)`
  Finds a localized text message for the given key, textKey.
  `String`
  `findText(ResourceBundle bundle, String textKey, 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 textKey, 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 textKey, 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 org.apache.struts2.text.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg`
  `getDefaultMessage(String key, Locale locale, ValueStack valueStack, Object[] args, String defaultMessage)`
  `protected org.apache.struts2.text.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)`
  `protected void`
  `logMissingText(Class<?> startClazz, String textKey, Locale locale, org.apache.struts2.text.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg result, String indexedTextName)`
  `protected void`
  `reloadBundles()`
  `protected void`
  `reloadBundles(Map<String,Object> context)`
  `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(org.apache.struts2.text.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 Details

  - ### 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 Details

  - ### GlobalLocalizedTextProvider

    public GlobalLocalizedTextProvider()

- ## Method Details

  - ### findText

    public String findText(Class<?> startClazz, String textKey, Locale locale)
    Description copied from interface: `LocalizedTextProvider`
    Calls `LocalizedTextProvider.findText(Class startClazz, String textKey, Locale locale, String defaultMessage, Object[] args)` with textKey as the default message.
    Parameters:
      `startClazz` - class name
      `textKey` - text name
      `locale` - the locale
    Returns:
      the localized text, or null if none can be found and no defaultMessage is provided
    See Also:
      - `LocalizedTextProvider.findText(Class startClazz, String textKey, Locale locale, String defaultMessage, Object[] args)`

  - ### findText

    public String findText(Class<?> startClazz, String textKey, Locale locale, String defaultMessage, Object[] args)
    Description copied from interface: `LocalizedTextProvider`
    Finds a localized text message for the given key, textKey. Both the key and the message itself is evaluated as required. The following algorithm is used to find the requested message:
    1. Look for the message in the default resource bundles.
    2. If not found, 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:
      `startClazz` - the class whose name to use as the start point for the search
      `textKey` - 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<?> startClazz, String textKey, Locale locale, String defaultMessage, Object[] args, ValueStack valueStack)
    Description copied from interface: `LocalizedTextProvider`
    Finds a localized text message for the given key, textKey. Both the key and the message itself is evaluated as required. The following algorithm is used to find the requested message:
    1. Look for the message in the default resource bundles.
    2. If not found, 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:
      `startClazz` - the class whose name to use as the start point for the search
      `textKey` - 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 textKey, Locale locale)
    Description copied from interface: `LocalizedTextProvider`
    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
      `textKey` - text name
      `locale` - the locale
    Returns:
      the localized text, or null if none can be found and no defaultMessage is provided
    See Also:
      - `LocalizedTextProvider.findText(ResourceBundle, String, Locale, String, Object[])`

  - ### findText

    public String findText(ResourceBundle bundle, String textKey, Locale locale, String defaultMessage, Object[] args)
    Description copied from interface: `LocalizedTextProvider`
    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
      `textKey` - 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 bundleName)
    Description copied from interface: `LocalizedTextProvider`
    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:
      `bundleName` - 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 textKey, Locale locale)
    Description copied from interface: `LocalizedTextProvider`
    Returns a localized message for the specified key, aTextName. Neither the key nor the message is evaluated.
    Specified by:
      `findDefaultText` in interface `LocalizedTextProvider`
    Parameters:
      `textKey` - 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 textKey, Locale locale, Object[] params)
    Description copied from interface: `LocalizedTextProvider`
    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:
      `textKey` - 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 textKey, Locale locale, String defaultMessage, Object[] args, ValueStack valueStack)
    Description copied from interface: `LocalizedTextProvider`
    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
      `textKey` - 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

    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 `LocalizedTextProvider.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 bundleName, Locale locale)
    Description copied from interface: `LocalizedTextProvider`
    Finds the given resource bundle by it's name.

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

    Specified by:
      `findResourceBundle` in interface `LocalizedTextProvider`
    Parameters:
      `bundleName` - the name of the bundle (usually it's FQN classname).
      `locale` - the locale.
    Returns:
      the bundle, `null` if not found.

  - ### unableToFindTextForKey

    protected boolean unableToFindTextForKey(org.apache.struts2.text.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 org.apache.struts2.text.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg getDefaultMessage(String key, Locale locale, ValueStack valueStack, Object[] args, String defaultMessage)
    Returns:
      the default message.

  - ### getDefaultMessageWithAlternateKey

    protected org.apache.struts2.text.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 `AbstractLocalizedTextProvider.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

  - ### extractIndexedName

    protected String extractIndexedName(String textKey)

  - ### logMissingText

    protected void logMissingText(Class<?> startClazz, String textKey, Locale locale, org.apache.struts2.text.AbstractLocalizedTextProvider.GetDefaultMessageReturnArg result, String indexedTextName)