Module org.apache.sis.util
Package org.apache.sis.util

# Interface LocalizedException

All Known Implementing Classes:
  `CanNotProbeException`, `ConcurrentReadException`, `ConcurrentWriteException`, `DataStoreClosedException`, `DataStoreContentException`, `DataStoreException`, `DataStoreReferencingException`, `ForwardOnlyStorageException`, `IllegalFeatureTypeException`, `IllegalNameException`, `IllegalOpenParameterException`, `IncompatibleResourceException`, `InternalDataStoreException`, `NoSuchDataException`, `ReadOnlyStorageException`, `ResourceAlreadyExistsException`, `UnparsableObjectException`, `UnsupportedEncodingException`, `UnsupportedQueryException`, `UnsupportedStorageException`

public interface LocalizedException
An exception which can produce an error message in the client locale. Exceptions implementing this interface apply the following policy:

- `getMessage()` returns the message in the default locale. In a client-server architecture, this is often the locale on the server side.
- `getLocalizedMessage()` returns the message in a locale that depends on the context in which the exception has been thrown. This is often the locale used by a `Format` or `DataStore` instance, and can be presumed to be the locale on the client side.
- `getInternationalMessage()` may return the message in arbitrary locale (optional operation). This method is specific to Apache SIS.

## Example

If an error occurred while a Japanese client connected to an European server, the localized message may be sent to the client in Japanese language while the same error may be logged on the server side in the French language. This allows system administrator to analyze the issue without the need to understand client's language. The above policy is applied on a best-effort basis only. For example, exceptions that do not implement `LocalizedException` may use any locale (not necessarily the default one), and `LocalizedException` used as wrappers around other exception usually lost their localization capability.

Since:
  0.8
See Also:
  - `Exceptions​.getLocalizedMessage(Throwable, Locale)`
  - `DataStore​.setLocale(Locale)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `InternationalString`
  `getInternationalMessage()`
  If this exception is capable to return the message in various locales, returns that message.
  `String`
  `getLocalizedMessage()`
  Returns the message in the locale that depends on the context in which this exception has been thrown.
  `String`
  `getMessage()`
  Returns the message in the default locale.

- ## Method Details

  - ### getMessage

    String getMessage()
    Returns the message in the default locale. In a client-server architecture, this is usually the locale on the server side. This is the recommended language for logging messages to be read by system administrators.
    Returns:
      the exception message in the JVM default locale.

  - ### getLocalizedMessage

    String getLocalizedMessage()
    Returns the message in the locale that depends on the context in which this exception has been thrown. For example, it may be the local of a client application connected to a distant server. This is the recommended language to show in widgets.
    Returns:
      the exception message in the locale of a service configured for a particular client.

  - ### getInternationalMessage

    InternationalString getInternationalMessage()
    If this exception is capable to return the message in various locales, returns that message. Otherwise returns `null`.
    Returns:
      the exception message, or `null` if this exception cannot produce international message.