Package org.apache.sis.storage

## Class DataStoreException

- Object
- - Throwable
  - - Exception
    - - DataStoreException

- All Implemented Interfaces:
    `Serializable`, `LocalizedException`
  Direct Known Subclasses:
    `ConcurrentReadException`, `ConcurrentWriteException`, `DataStoreClosedException`, `DataStoreContentException`, `DataStoreReferencingException`, `ForwardOnlyStorageException`, `IllegalFeatureTypeException`, `IllegalNameException`, `IllegalOpenParameterException`, `InternalDataStoreException`, `ReadOnlyStorageException`, `UnsupportedQueryException`

      public class DataStoreException
      extends Exception
      implements LocalizedException

  Thrown when a `DataStore` can not complete a read or write operation.
  Localization
  The `getMessage()` and `getLocalizedMessage()` methods return the same message, but sometime in different languages. The general policy is that `getMessage()` returns the message in the JVM default locale while `getLocalizedMessage()` returns the message in the locale specified by the last call to `DataStore​.setLocale(Locale)`. In a client-server architecture, the former is typically the locale of the system administrator while the later is presumably the locale of the client connected to the server. However this policy is applied on a best-effort basis only.
  Since:
    0.3
  See Also:
    Serialized Form

  Defined in the `sis-storage` module

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DataStoreException()` | Creates an exception with no cause and no details message.
    `DataStoreException​(String message)` | Creates an exception with the specified details message.
    `DataStoreException​(String message, Throwable cause)` | Creates an exception with the specified details message and cause.
    `DataStoreException​(Throwable cause)` | Creates an exception with the specified cause and no details message.
    `DataStoreException​(Locale locale, String format, String filename, Object store)` | Creates a localized exception with a message saying that the given store can not be processed.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    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 a localized version of the exception message, typically for final user.
    `String` | `getMessage()` | Returns the exception message in the default locale, typically for system administrator.
    `DataStoreException` | `initCause​(Throwable cause)` | Initializes the cause of this throwable to the specified value.

    - ### Methods inherited from class Throwable

      `addSuppressed, fillInStackTrace, getCause, getStackTrace, getSuppressed, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### DataStoreException

          public DataStoreException()

      Creates an exception with no cause and no details message.

    - #### DataStoreException

          public DataStoreException​(String message)

      Creates an exception with the specified details message.
      Parameters:
        `message` - the detail message in the default locale.

    - #### DataStoreException

          public DataStoreException​(Throwable cause)

      Creates an exception with the specified cause and no details message.
      Parameters:
        `cause` - the cause for this exception.

    - #### DataStoreException

          public DataStoreException​(String message,
                                    Throwable cause)

      Creates an exception with the specified details message and cause.
      Parameters:
        `message` - the detail message in the default locale.
        `cause` - the cause for this exception.

    - #### DataStoreException

          public DataStoreException​(Locale locale,
                                    String format,
                                    String filename,
                                    Object store)

      Creates a localized exception with a message saying that the given store can not be processed. Location in the file where the error occurred while be fetched from the given `store` argument if possible, for example by invoking the `LineNumberReader​.getLineNumber()` or `XMLStreamReader​.getLocation()` method. If the given `store` argument is not one of the recognized types, then it is ignored.

      Examples of messages created by this constructor:

      - Can not read “Foo” as a file in the Bar format.
      - Can not read after column 10 or line 100 of “Foo” as part of a file in the Bar format.
      Parameters:
        `locale` - the locale of the message to be returned by `getLocalizedMessage()`, or `null`.
        `format` - short name or abbreviation of the data format (e.g. "CSV", "GML", "WKT", etc).
        `filename` - name of the file or data store where the error occurred.
        `store` - the input or output object from which to get the current position, or `null` if none. This can be a `LineNumberReader` or `XMLStreamReader` for example.
      Since:
        0.8

  - ### Method Detail

    - #### getMessage

          public String getMessage()

      Returns the exception message in the default locale, typically for system administrator.
      Specified by:
        `getMessage` in interface `LocalizedException`
      Overrides:
        `getMessage` in class `Throwable`
      Returns:
        the message of this exception.

    - #### getLocalizedMessage

          public String getLocalizedMessage()

      Returns a localized version of the exception message, typically for final user. This is often the same message than the one returned by `getMessage()`, but may in some occasions be different if `DataStore​.setLocale(Locale)` has been invoked with a different locale.
      `getMessage()` versus `getLocalizedMessage()`
      When `getMessage()` and `getLocalizedMessage()` are not equivalent, the Apache SIS policy is that `getMessage()` returns the message in the default locale while `getLocalizedMessage()` returns the message in a locale that depends on the context in which the exception has been thrown. In a client-server architecture, the former is often the locale on the server side while the later is the locale on the client side if that information has been provided to the `DataStore`.
      Specified by:
        `getLocalizedMessage` in interface `LocalizedException`
      Overrides:
        `getLocalizedMessage` in class `Throwable`
      Returns:
        the localized message of this exception.
      Since:
        0.8
      See Also:
        `DataStore​.setLocale(Locale)`

    - #### getInternationalMessage

          public InternationalString getInternationalMessage()

      If this exception is capable to return the message in various locales, returns that message. Otherwise returns `null`.
      Specified by:
        `getInternationalMessage` in interface `LocalizedException`
      Returns:
        the exception message, or `null` if this exception can not produce international message.
      Since:
        0.8

    - #### initCause

          public DataStoreException initCause​(Throwable cause)

      Initializes the cause of this throwable to the specified value.
      Overrides:
        `initCause` in class `Throwable`
      Parameters:
        `cause` - the cause saved for later retrieval by the `Throwable​.getCause()` method.
      Returns:
        a reference to this `DataStoreException` instance.
      Since:
        0.8