Package org.apache.sis.util

# Class DefaultInternationalString

Object
AbstractInternationalString
DefaultInternationalString

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

public class DefaultInternationalString extends AbstractInternationalString implements Serializable
An international string using a map of strings for different locales. Strings for new locales can be added, but existing strings can not be removed or modified. This behavior is a compromise between making constructions easier, and being suitable for use in immutable objects.

## Thread safety

Instances of `DefaultInternationalString` are thread-safe. While those instances are not strictly immutable, SIS typically references them as if they were immutable because of their add-only behavior.

Since:
  1.1
See Also:
  - `Types​.toInternationalString(Map, String)`
  - Serialized Form

Defined in the `sis-utility` module

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DefaultInternationalString()`
  Creates an initially empty international string.
  `DefaultInternationalString(String string)`
  Creates an international string initialized with the given string.
  `DefaultInternationalString(Map<Locale,String> strings)`
  Creates an international string initialized with the given localized strings.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(Locale locale, String string)`
  Adds a string for the given locale.
  `boolean`
  `equals(Object object)`
  Compares this international string with the specified object for equality.
  `Set<Locale>`
  `getLocales()`
  Returns the set of locales defined in this international string.
  `int`
  `hashCode()`
  Returns a hash code value for this international text.
  `boolean`
  `isSubsetOf(Object candidate)`
  Returns `true` if all localized texts stored in this international string are contained in the specified object.
  `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`

- ## Constructor Details

  - ### DefaultInternationalString

    public DefaultInternationalString()
    Creates an initially empty international string. Localized strings can been added using one of `add(…)` methods.

  - ### DefaultInternationalString

    public DefaultInternationalString(String string)
    Creates an international string initialized with the given string. Additional localized strings can been added using one of `add(…)` methods. The string specified to this constructor is the one that will be returned if no localized string is found for the `Locale` argument in a call to `toString(Locale)`.
    Parameters:
      `string` - the string in no specific locale, or `null` if none.

  - ### DefaultInternationalString

    public DefaultInternationalString(Map<Locale,String> strings)
    Creates an international string initialized with the given localized strings. The content of the given map is copied, so changes to that map after construction will not be reflected into this international string.
    Parameters:
      `strings` - the strings in various locales, or `null` if none.
    See Also:
      - `Types​.toInternationalString(Map, String)`

- ## Method Details

  - ### add

    public void add(Locale locale, String string) throws IllegalArgumentException
    Adds a string for the given locale.
    Parameters:
      `locale` - the locale for the `string` value.
      `string` - the localized string.
    Throws:
      `IllegalArgumentException` - if a different string value was already set for the given locale.

  - ### getLocales

    public Set<Locale> getLocales()
    Returns the set of locales defined in this international string.
    Returns:
      the set of locales.
    TODO:
      Current implementation does not return a synchronized set. We should synchronize on the same lock than the one used for accessing the internal locale map.

  - ### toString

    public String toString(Locale locale)
    Returns a string in the specified locale. If there is no string for that `locale`, then this method searches for a locale without the variant part. If no string are found, then this method searches for a locale without the country part. For example if the `"fr_CA"` locale was requested but not found, then this method looks for the `"fr"` locale. The root locale is tried last.

    #### Handling of `Locale​.ROOT` argument value

    `Locale​.ROOT` can be given to this method for requesting a "unlocalized" string, typically some programmatic values like enumerations or identifiers. While identifiers often look like English words, `Locale​.ROOT` is not considered synonymous to `Locale​.ENGLISH` because the values may differ in the way numbers and dates are formatted (e.g. using the ISO 8601 standard for dates instead of English conventions). In order to produce a value close to the common practice, this method handles `Locale​.ROOT` as below:
    - If a string has been explicitly added for `Locale​.ROOT`, then that string is returned.
    - Otherwise, acknowledging that UML identifiers in OGC/ISO specifications are primarily expressed in the English language, this method looks for strings associated to `Locale​.US` as an approximation of "unlocalized" strings.
    - If no English string was found, then this method looks for a string for the system default locale.
    - If none of the above steps found a string, then this method returns an arbitrary string.

    #### 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 given locale if available, or in an implementation-dependent fallback locale otherwise.
    See Also:
      - `Locale​.getDefault()`
      - `Locale​.ROOT`

  - ### isSubsetOf

    public boolean isSubsetOf(Object candidate)
    Returns `true` if all localized texts stored in this international string are contained in the specified object. More specifically:
    - If `candidate` is an instance of `InternationalString`, then this method returns `true` if, for all locale-string pairs contained in `this`, `candidate.toString(locale)` returns a string equals to `string`.
    - If `candidate` is an instance of `CharSequence`, then this method returns `true` if `toString(Locale)` returns a string equals to `candidate.toString()` for all locales.
    - If `candidate` is an instance of `Map`, then this methods returns `true` if all locale-string pairs are contained into `candidate`.
    - Otherwise, this method returns `false`.
    Parameters:
      `candidate` - the object which may contains this international string.
    Returns:
      `true` if the given object contains all localized strings found in this international string.

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