ResourceBundleMessageSource (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.context.support

## Class ResourceBundleMessageSource

- java.lang.Object
- - org.springframework.context.support.MessageSourceSupport
  - - org.springframework.context.support.AbstractMessageSource
    - - org.springframework.context.support.ResourceBundleMessageSource

- All Implemented Interfaces:
    Aware, BeanClassLoaderAware, HierarchicalMessageSource, MessageSource

      public class ResourceBundleMessageSource
      extends AbstractMessageSource
      implements BeanClassLoaderAware

  `MessageSource` implementation that accesses resource bundles using specified basenames. This class relies on the underlying JDK's `ResourceBundle` implementation, in combination with the JDK's standard message parsing provided by `MessageFormat`.

  This MessageSource caches both the accessed ResourceBundle instances and the generated MessageFormats for each message. It also implements rendering of no-arg messages without MessageFormat, as supported by the AbstractMessageSource base class. The caching provided by this MessageSource is significantly faster than the built-in caching of the `java.util.ResourceBundle` class.

  Unfortunately, `java.util.ResourceBundle` caches loaded bundles forever: Reloading a bundle during VM execution is not possible. As this MessageSource relies on ResourceBundle, it faces the same limitation. Consider `ReloadableResourceBundleMessageSource` for an alternative that is capable of refreshing the underlying bundle files.

  Author:
    Rod Johnson, Juergen Hoeller
  See Also:
    `setBasenames(java.lang.String...)`, `ReloadableResourceBundleMessageSource`, `ResourceBundle`, `MessageFormat`

- - ### Field Summary

    - ### Fields inherited from class org.springframework.context.support.MessageSourceSupport

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResourceBundleMessageSource()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected ResourceBundle` | `doGetBundle(String basename, Locale locale)` Obtain the resource bundle for the given basename and Locale.
    `protected ClassLoader` | `getBundleClassLoader()` Return the ClassLoader to load resource bundles with.
    `protected MessageFormat` | `getMessageFormat(ResourceBundle bundle, String code, Locale locale)` Return a MessageFormat for the given bundle and code, fetching already generated MessageFormats from the cache.
    `protected ResourceBundle` | `getResourceBundle(String basename, Locale locale)` Return a ResourceBundle for the given basename and code, fetching already generated MessageFormats from the cache.
    `protected MessageFormat` | `resolveCode(String code, Locale locale)` Resolves the given message code as key in the registered resource bundles, using a cached MessageFormat instance per message code.
    `protected String` | `resolveCodeWithoutArguments(String code, Locale locale)` Resolves the given message code as key in the registered resource bundles, returning the value found in the bundle as-is (without MessageFormat parsing).
    `void` | `setBasename(String basename)` Set a single basename, following `ResourceBundle` conventions: essentially, a fully-qualified classpath location.
    `void` | `setBasenames(String... basenames)` Set an array of basenames, each following `ResourceBundle` conventions: essentially, a fully-qualified classpath location.
    `void` | `setBeanClassLoader(ClassLoader classLoader)` Callback that supplies the bean `class loader` to a bean instance.
    `void` | `setBundleClassLoader(ClassLoader classLoader)` Set the ClassLoader to load resource bundles with.
    `void` | `setCacheSeconds(int cacheSeconds)` Set the number of seconds to cache loaded resource bundle files.
    `void` | `setDefaultEncoding(String defaultEncoding)` Set the default charset to use for parsing resource bundle files.
    `void` | `setFallbackToSystemLocale(boolean fallbackToSystemLocale)` Set whether to fall back to the system Locale if no files for a specific Locale have been found.
    `String` | `toString()` Show the configuration of this MessageSource.

    - ### Methods inherited from class org.springframework.context.support.AbstractMessageSource

      `getDefaultMessage, getMessage, getMessage, getMessage, getMessageFromParent, getMessageInternal, getParentMessageSource, isUseCodeAsDefaultMessage, resolveArguments, setParentMessageSource, setUseCodeAsDefaultMessage`

    - ### Methods inherited from class org.springframework.context.support.MessageSourceSupport

      `createMessageFormat, formatMessage, isAlwaysUseMessageFormat, renderDefaultMessage, setAlwaysUseMessageFormat`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ResourceBundleMessageSource

          public ResourceBundleMessageSource()

  - ### Method Detail

    - #### setBasename

          public void setBasename(String basename)

      Set a single basename, following `ResourceBundle` conventions: essentially, a fully-qualified classpath location. If it doesn't contain a package qualifier (such as `org.mypackage`), it will be resolved from the classpath root.

      Messages will normally be held in the "/lib" or "/classes" directory of a web application's WAR structure. They can also be held in jar files on the class path.

      Note that ResourceBundle names are effectively classpath locations: As a consequence, the JDK's standard ResourceBundle treats dots as package separators. This means that "test.theme" is effectively equivalent to "test/theme", just like it is for programmatic `java.util.ResourceBundle` usage.

      See Also:
        `setBasenames(java.lang.String...)`, `ResourceBundle.getBundle(String)`

    - #### setBasenames

          public void setBasenames(String... basenames)

      Set an array of basenames, each following `ResourceBundle` conventions: essentially, a fully-qualified classpath location. If it doesn't contain a package qualifier (such as `org.mypackage`), it will be resolved from the classpath root.

      The associated resource bundles will be checked sequentially when resolving a message code. Note that message definitions in a previous resource bundle will override ones in a later bundle, due to the sequential lookup.

      Note that ResourceBundle names are effectively classpath locations: As a consequence, the JDK's standard ResourceBundle treats dots as package separators. This means that "test.theme" is effectively equivalent to "test/theme", just like it is for programmatic `java.util.ResourceBundle` usage.

      See Also:
        `setBasename(java.lang.String)`, `ResourceBundle.getBundle(String)`

    - #### setDefaultEncoding

          public void setDefaultEncoding(String defaultEncoding)

      Set the default charset to use for parsing resource bundle files.

      Default is none, using the `java.util.ResourceBundle` default encoding: ISO-8859-1.

      NOTE: Only works on JDK 1.6 and higher. Consider using `ReloadableResourceBundleMessageSource` for JDK 1.5 support and more flexibility in setting of an encoding per file.

    - #### setFallbackToSystemLocale

          public void setFallbackToSystemLocale(boolean fallbackToSystemLocale)

      Set whether to fall back to the system Locale if no files for a specific Locale have been found. Default is "true"; if this is turned off, the only fallback will be the default file (e.g. "messages.properties" for basename "messages").

      Falling back to the system Locale is the default behavior of `java.util.ResourceBundle`. However, this is often not desirable in an application server environment, where the system Locale is not relevant to the application at all: Set this flag to "false" in such a scenario.

      NOTE: Only works on JDK 1.6 and higher. Consider using `ReloadableResourceBundleMessageSource` for JDK 1.5 support.

    - #### setCacheSeconds

          public void setCacheSeconds(int cacheSeconds)

      Set the number of seconds to cache loaded resource bundle files.
      - Default is "-1", indicating to cache forever.
      - A positive number will expire resource bundles after the given number of seconds. This is essentially the interval between refresh checks. Note that a refresh attempt will first check the last-modified timestamp of the file before actually reloading it; so if files don't change, this interval can be set rather low, as refresh attempts will not actually reload.
      - A value of "0" will check the last-modified timestamp of the file on every message access. Do not use this in a production environment!
      - Note that depending on your ClassLoader, expiration might not work reliably since the ClassLoader may hold on to a cached version of the bundle file. Consider `ReloadableResourceBundleMessageSource` in combination with resource bundle files in a non-classpath location.

      NOTE: Only works on JDK 1.6 and higher. Consider using `ReloadableResourceBundleMessageSource` for JDK 1.5 support and more flexibility in terms of the kinds of resources to load from (in particular from outside of the classpath where expiration works reliably).

    - #### setBundleClassLoader

          public void setBundleClassLoader(ClassLoader classLoader)

      Set the ClassLoader to load resource bundles with.

      Default is the containing BeanFactory's `bean ClassLoader`, or the default ClassLoader determined by `ClassUtils.getDefaultClassLoader()` if not running within a BeanFactory.

    - #### getBundleClassLoader

          protected ClassLoader getBundleClassLoader()

      Return the ClassLoader to load resource bundles with.

      Default is the containing BeanFactory's bean ClassLoader.

      See Also:
        `setBundleClassLoader(java.lang.ClassLoader)`

    - #### setBeanClassLoader

          public void setBeanClassLoader(ClassLoader classLoader)

      Description copied from interface: `BeanClassLoaderAware`
      Callback that supplies the bean `class loader` to a bean instance.

      Invoked after the population of normal bean properties but before an initialization callback such as `InitializingBean's` `InitializingBean.afterPropertiesSet()` method or a custom init-method.

      Specified by:
        `setBeanClassLoader` in interface `BeanClassLoaderAware`
      Parameters:
        `classLoader` - the owning class loader; may be `null` in which case a default `ClassLoader` must be used, for example the `ClassLoader` obtained via `ClassUtils.getDefaultClassLoader()`

    - #### resolveCodeWithoutArguments

          protected String resolveCodeWithoutArguments(String code,
                                           Locale locale)

      Resolves the given message code as key in the registered resource bundles, returning the value found in the bundle as-is (without MessageFormat parsing).
      Overrides:
        `resolveCodeWithoutArguments` in class `AbstractMessageSource`
      Parameters:
        `code` - the code of the message to resolve
        `locale` - the Locale to resolve the code for (subclasses are encouraged to support internationalization)
      Returns:
        the message String, or `null` if not found
      See Also:
        `AbstractMessageSource.resolveCode(java.lang.String, java.util.Locale)`, `MessageFormat`

    - #### resolveCode

          protected MessageFormat resolveCode(String code,
                                  Locale locale)

      Resolves the given message code as key in the registered resource bundles, using a cached MessageFormat instance per message code.
      Specified by:
        `resolveCode` in class `AbstractMessageSource`
      Parameters:
        `code` - the code of the message to resolve
        `locale` - the Locale to resolve the code for (subclasses are encouraged to support internationalization)
      Returns:
        the MessageFormat for the message, or `null` if not found
      See Also:
        `AbstractMessageSource.resolveCodeWithoutArguments(String, java.util.Locale)`

    - #### getResourceBundle

          protected ResourceBundle getResourceBundle(String basename,
                                         Locale locale)

      Return a ResourceBundle for the given basename and code, fetching already generated MessageFormats from the cache.
      Parameters:
        `basename` - the basename of the ResourceBundle
        `locale` - the Locale to find the ResourceBundle for
      Returns:
        the resulting ResourceBundle, or `null` if none found for the given basename and Locale

    - #### doGetBundle

          protected ResourceBundle doGetBundle(String basename,
                                   Locale locale)
                                        throws MissingResourceException

      Obtain the resource bundle for the given basename and Locale.
      Parameters:
        `basename` - the basename to look for
        `locale` - the Locale to look for
      Returns:
        the corresponding ResourceBundle
      Throws:
        `MissingResourceException` - if no matching bundle could be found
      See Also:
        `ResourceBundle.getBundle(String, java.util.Locale, ClassLoader)`, `getBundleClassLoader()`

    - #### getMessageFormat

          protected MessageFormat getMessageFormat(ResourceBundle bundle,
                                       String code,
                                       Locale locale)
                                            throws MissingResourceException

      Return a MessageFormat for the given bundle and code, fetching already generated MessageFormats from the cache.
      Parameters:
        `bundle` - the ResourceBundle to work on
        `code` - the message code to retrieve
        `locale` - the Locale to use to build the MessageFormat
      Returns:
        the resulting MessageFormat, or `null` if no message defined for the given code
      Throws:
        `MissingResourceException` - if thrown by the ResourceBundle

    - #### toString

          public String toString()

      Show the configuration of this MessageSource.
      Overrides:
        `toString` in class `Object`