# Class ResourceInternationalString

Object
AbstractInternationalString
ResourceInternationalString

All Implemented Interfaces:
  `Serializable`, `CharSequence`, `Comparable<InternationalString>`, `Formattable`, `InternationalString`

public abstract class ResourceInternationalString extends AbstractInternationalString implements Serializable
An international string backed by a `ResourceBundle`. Resource bundles can be Java classes or properties files, one for each language. The resource bundle is specified by `getBundle(Locale)`, which must be defined by subclasses. The subclass will typically invoke `ResourceBundle​.getBundle(resources, locale)` where resources is the fully qualified class name of the base resource bundle (without locale suffix). The appropriate resource bundle is loaded at runtime for the client's language by looking for a class or a properties file with the right suffix, for example `"_en"` for English or `"_fr"` for French. See the `ResourceBundle​.getBundle(…)` Javadoc for more information.

## Example

If a file named "`MyResources​.properties`" exists in `org​.mypackage` and contains the following line:

    MyKey = some value

Then an international string for `"some value"` can be created using the following code:

    InternationalString value = new ResourceInternationalString("MyKey") {
        @Override protected ResourceBundle getBundle(Locale locale) {
            return ResourceBundle.getBundle("org.mypackage.MyResources", locale);
        }
    };

The `"some value"` string will be localized if the required properties files exist, for example "`MyResources_fr​.properties`" for French or "`MyResources_it​.properties`" for Italian, etc. If needed, users can gain more control by overriding the `getBundle(Locale)` method.

## Immutability and thread safety

This class is immutable and thus inherently thread-safe if the bundles created by `getBundle(Locale)` is also immutable. Subclasses may or may not be immutable, at implementation choice. But implementers are encouraged to make sure that subclasses remain immutable for more predictable behavior.

Since:
  1.1
See Also:
  - `ResourceBundle​.getBundle(String, Locale)`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final String`
  `key`
  The key for the resource to fetch.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ResourceInternationalString(String key)`
  Creates a new international string from the specified key.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object object)`
  Compares this international string with the specified object for equality.
  `protected abstract ResourceBundle`
  `getBundle(Locale locale)`
  Returns the resource bundle for the given locale.
  `int`
  `hashCode()`
  Returns a hash code value for this international text.
  `String`
  `toString(Locale locale)`
  Returns a string in the specified locale.

  ### Methods inherited from class AbstractInternationalString

  `charAt, compareTo, formatTo, length, subSequence, toString`

  ### Methods inherited from class Object

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

  ### Methods inherited from interface CharSequence

  `chars, codePoints, isEmpty`

- ## Field Details

  - ### key

    protected final String key
    The key for the resource to fetch. This value is given at construction time and cannot be `null`.

- ## Constructor Details

  - ### ResourceInternationalString

    protected ResourceInternationalString(String key)
    Creates a new international string from the specified key.
    Parameters:
      `key` - the key for the resource to fetch.

- ## Method Details

  - ### getBundle

    protected abstract ResourceBundle getBundle(Locale locale)
    Returns the resource bundle for the given locale. This implementation must be provided by subclasses because, in a modularized application, the call to the `ResourceBundle​.getBundle(String, Locale)` method is caller-sensitive. This method is typically implemented as below:

            @Override
            protected ResourceBundle getBundle(final Locale locale) {
                return ResourceBundle.getBundle(resources, locale, MyResource.class.getClassLoader());
            }

    Parameters:
      `locale` - the locale for which to get the resource bundle.
    Returns:
      the resource bundle for the given locale.
    See Also:
      - `ResourceBundle​.getBundle(String, Locale, ClassLoader)`

  - ### toString

    public String toString(Locale locale) throws MissingResourceException
    Returns a string in the specified locale. If there is no string for the specified `locale`, then this method searches for a string in another locale as specified in the `ResourceBundle` class description.

    #### Handling of `null` argument value

    In the default implementation, the `null` locale is handled as a synonymous of `Locale​.ROOT`. However, subclasses are free to use a different fallback. Client code are encouraged to specify only non-null values for more determinist behavior.
    Specified by:
      `toString` in interface `InternationalString`
    Specified by:
      `toString` in class `AbstractInternationalString`
    Parameters:
      `locale` - the desired locale for the string to be returned.
    Returns:
      the string in the specified locale, or in a fallback locale.
    Throws:
      `MissingResourceException` - if no resource can be found for the key specified at construction time.
    See Also:
      - `Locale​.getDefault()`
      - `Locale​.ROOT`

  - ### equals

    public boolean equals(Object object)
    Compares this international string with the specified object for equality.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - the object to compare with this international string.
    Returns:
      `true` if the given object is equal to this string.

  - ### hashCode

    public int hashCode()
    Returns a hash code value for this international text.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code value for this international text.