Package org.apache.sis.util.logging

## Interface WarningListener<S>

- Type Parameters:
    `S` - the base type of objects that emit warnings (the source).
  All Superinterfaces:
    `EventListener`

      @Deprecated
      public interface WarningListener<S>
      extends EventListener

  Deprecated.
  Replaced by `Filter`.
  Intercepts non-fatal error messages logged by `DataStore` or other SIS objects. Warnings are encapsulated in `LogRecord` objects and logged at `Level​.WARNING` if the emitter does not have registered any `WarningListener`. This listener allows applications to intercept warning records for displaying them in a dialog (or any other action that the application may choose) instead than logging them.
  Comparison with alternative approaches: it is also possible to listen to login events by registering a custom `Handler` to the logger. But `Handler` instances are registered on a per-logger basis and receive all messages sent to that logger regardless their emitter. By contrast, `WarningListener` instances are registered on a per-`DataStore` basis (or any other emitter) and receive all messages sent by that emitter regardless the destination logger. The emitter is part of the information given to the `warningOccured(Object, LogRecord)` method, in addition to the log record.
  Since:
    0.3
  See Also:
    `WarningListeners`, `DataStore​.addWarningListener(WarningListener)`, `StoreListener`

  Defined in the `sis-utility` module

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `default Filter` | `asFilter()` | Deprecated. Wraps this listener in a `java​.util​.logging​.Filter` for transitioning to the replacement of this interface.
    `Class<S>` | `getSourceClass()` | Deprecated. Returns the type of objects that emit warnings of interest for this listener.
    `void` | `warningOccured​(S source, LogRecord warning)` | Deprecated. Reports the occurrence of a non-fatal error.

- - ### Method Detail

    - #### getSourceClass

          Class<S> getSourceClass()

      Deprecated.
      Returns the type of objects that emit warnings of interest for this listener. This is typically, but not necessarily, the class having the name returned by `LogRecord​.getSourceClassName()`, or one of its parent classes.
      Returns:
        the base type of objects that emit warnings (the source).

    - #### warningOccured

          void warningOccured​(S source,
                              LogRecord warning)

      Deprecated.
      Reports the occurrence of a non-fatal error. The emitter process (often a `DataStore` in the midst of a reading process) will continue following the call to this method.

      The `LogRecord` provides the warning message together with programmatic information like the source class name and method name where the warning occurred. The log record may optionally contains the exception which has been thrown.

      Applications may choose to ignore the warning, display a dialog or take any other action they choose. Applications do not need to log the warning, since logging will be done automatically if the emitter has no registered warning listeners.

      Parameters:
        `source` - the object that emitted a warning, or `null` if not available.
        `warning` - the warning message together with programmatic information.

    - #### asFilter

          default Filter asFilter()

      Deprecated.
      Wraps this listener in a `java​.util​.logging​.Filter` for transitioning to the replacement of this interface.