Package org.apache.sis.util.iso

## Class ResourceInternationalString

- Object
- - AbstractInternationalString
  - - ResourceInternationalString

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

      public 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 fully qualified class name of the base resource bundle (without locale suffix) is specified at construction time. 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("org.mypackage.MyResources", "MyKey");

  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.
  Class loaders
  Developers can specify explicitly the `ClassLoader` to use be overriding the `getBundle(Locale)` method. This is recommended if the running environment loads modules in isolated class loaders, as OSGi does for instance.
  API note: We do not provide `ClassLoader` argument in the constructor of this class because class loaders can often be hard-coded (thus avoiding the cost of an extra field) and are usually not serializable.
  Apache SIS resources
  Apache SIS has its own resources mechanism, built on top of the standard `ResourceBundle` with the addition of type safety and optional arguments to be formatted in the localized string. Those resource bundles provide `formatInternational(int, …)` static methods for creating international strings with the same functionality than this `ResourceInternationalString`. See `org​.apache​.sis​.util​.resources` for more information.
  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:
    0.3
  See Also:
    `ResourceBundle​.getBundle(String, Locale)`, Serialized Form

  Defined in the `sis-utility` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected String` | `key` | The key for the resource to fetch.
    `protected String` | `resources` | The name of the resource bundle, as a fully qualified class name.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ResourceInternationalString​(String resources, String key)` | Creates a new international string from the specified resource bundle and key.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object object)` | Compares this international string with the specified object for equality.
    `protected 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`

- - ### Field Detail

    - #### resources

          protected final String resources

      The name of the resource bundle, as a fully qualified class name. This value is given at construction time and can not be `null`.

    - #### key

          protected final String key

      The key for the resource to fetch. This value is given at construction time and can not be `null`.

  - ### Constructor Detail

    - #### ResourceInternationalString

          public ResourceInternationalString​(String resources,
                                             String key)

      Creates a new international string from the specified resource bundle and key. The class loader will be the one of the `toString(Locale)` caller, unless the `getBundle(Locale)` method is overridden.
      Parameters:
        `resources` - the name of the resource bundle, as a fully qualified class name.
        `key` - the key for the resource to fetch.

  - ### Method Detail

    - #### getBundle

          protected ResourceBundle getBundle​(Locale locale)
                                      throws MissingResourceException

      Returns the resource bundle for the given locale. The default implementation fetches the bundle from the name given at construction time. Subclasses can override this method if they need to fetch the bundle in an other way.
      Class loaders
      By default, this method loads the resources using the caller's class loader. Subclasses can override this method in order to specify a different class loader. For example, the code below works well if `MyResource` is a class defined in the same module than the one that contain the resources to load:

      >     @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.
      Throws:
        `MissingResourceException` - if no resource bundle can be found for the base name specified at construction time.
      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 an other 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 base name or 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.