com.opensymphony.xwork2.util

## Class GlobalLocalizedTextProvider

- java.lang.Object
- - com.opensymphony.xwork2.util.GlobalLocalizedTextProvider

- All Implemented Interfaces:
    LocalizedTextProvider, Serializable

      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 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
    `GlobalLocalizedTextProvider()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    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`.
    `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)`
    `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

    - #### GlobalLocalizedTextProvider

          public GlobalLocalizedTextProvider()

  - ### Method Detail

    - #### 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. 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:
        `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. 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:
        `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(ResourceBundle, String, 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

Copyright © 2000–2023 Apache Software Foundation. All rights reserved.