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, 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`
    `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)` Add's the bundle to the internal list of default bundles.
    `protected MessageFormat` | `buildMessageFormat(String pattern, Locale locale)`
    `void` | `clearBundle(String bundleName)` Clear a specific bundle from the `bundlesMap` Warning: This method may be ineffective due to the way the `bundlesMap` is used in combination with locale.
    `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 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)`
    `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

  - ### 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 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
      2. If not found and aClass is a `ModelDriven` Action, then look for message in the model's class hierarchy (repeat sub-steps listed above).
      3. 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 fromthe beginning with the object's class as aClass and "address.state" as the message key.
      4. If not found, look for the message in aClass' package hierarchy.
      5. If still not found, look for the message in the default resource bundles.
      6. 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 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
      2. If not found and aClass is a `ModelDriven` Action, then look for message in the model's class hierarchy (repeat sub-steps listed above).
      3. 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 fromthe beginning with the object's class as aClass and "address.state" as the message key.
      4. If not found, look for the message in aClass' package hierarchy.
      5. If still not found, look for the message in the default resource bundles.
      6. 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 WARN log 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)

      Add's 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)

      Clear a specific bundle from the `bundlesMap` Warning: This method may be 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

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

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

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

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