org.apache.sis.util.logging

## Class WarningListeners<S>

- Object
- - WarningListeners<S>

- Type Parameters:
    `S` - the type of the source of warnings.
  All Implemented Interfaces:
    Localized

      public class WarningListeners<S>
      extends Object
      implements Localized

  Holds a list of `WarningListener` instances and provides convenience methods for emitting warnings. This is a helper class for `DataStore` implementations or for other services susceptible to emit warnings. Observers can can add listeners for being notified about warnings, and processes can invoke one of the `warning(…)` methods for emitting warnings. All warnings are given to the listeners as `LogRecord` instances (this allows localizable messages and additional information like timestamp and stack trace). This `WarningListeners` class provides convenience methods like `warning(String, Exception)`, which builds `LogRecord` from an exception or from a string, but all those `warning(…)` methods ultimately delegate to `warning(LogRecord)`, thus providing a single point that subclasses can override. When a warning is emitted, the default behavior is:
  - If at least one `WarningListener` is registered, then all listeners are notified and the warning is not logged.
  - Otherwise if the value returned by `LogRecord​.getLoggerName()` is non-null, then the warning will be logged to that named logger.
  - Otherwise the warning is logged to the logger returned by `getLogger()`.
  Thread safety
  The same `WarningListeners` instance can be safely used by many threads without synchronization on the part of the caller. Subclasses should make sure that any overridden methods remain safe to call from multiple threads.
  Since:
    0.3
  See Also:
    `WarningListener`, `DataStore​.listeners`

  Defined in the `sis-utility` module

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `WarningListeners(S source)` Creates a new instance with initially no listener.
    `WarningListeners(S source, WarningListeners<? super S> other)` Creates a new instance initialized with the same listeners than the given instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addWarningListener(WarningListener<? super S> listener)` Adds a listener to be notified when a warning occurred.
    `List<WarningListener<? super S>>` | `getListeners()` Returns all registered warning listeners, or an empty list if none.
    `Locale` | `getLocale()` The locale to use for formatting warning messages, or `null` for the default locale.
    `Logger` | `getLogger()` Returns the logger where to send the warnings when no other destination is specified.
    `S` | `getSource()` Returns the source declared source of warnings.
    `boolean` | `hasListeners()` Returns `true` if this object contains at least one listener.
    `void` | `removeWarningListener(WarningListener<? super S> listener)` Removes a previously registered listener.
    `void` | `warning(Level level, String message, Exception exception)` Reports a warning at the given level represented by the given message and exception.
    `void` | `warning(LogRecord record)` Reports a warning represented by the given log record.
    `void` | `warning(String message, Exception exception)` Reports a warning represented by the given message and exception.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### WarningListeners

          public WarningListeners(S source)

      Creates a new instance with initially no listener. Warnings will be logger to the destination given by `getLogger()`, unless at least one listener is registered.
      Parameters:
        `source` - the declared source of warnings. This is not necessarily the real source, but this is the source that the implementor wants to declare as public API.

    - #### WarningListeners

          public WarningListeners(S source,
                                  WarningListeners<? super S> other)

      Creates a new instance initialized with the same listeners than the given instance. This constructor is useful when a `DataStore` or other data producer needs to be duplicated for concurrency reasons.
      Parameters:
        `source` - the declared source of warnings. This is not necessarily the real source, but this is the source that the implementor wants to declare as public API.
        `other` - the existing instance from which to copy the listeners, or `null` if none.
      Since:
        0.8

  - ### Method Detail

    - #### getSource

          public S getSource()

      Returns the source declared source of warnings. This value is specified at construction time.
      Returns:
        the declared source of warnings.
      Since:
        0.8

    - #### getLocale

          public Locale getLocale()

      The locale to use for formatting warning messages, or `null` for the default locale. If the `source` object given to the constructor implements the `Localized` interface, then this method delegates to its `getLocale()` method. Otherwise this method returns `null`.
      Specified by:
        `getLocale` in interface `Localized`
      Returns:
        the locale, or `null` if not explicitly defined.

    - #### getLogger

          public Logger getLogger()

      Returns the logger where to send the warnings when no other destination is specified. This logger is used when:
      - no listener has been registered, and
      - the `LogRecord` does not specify a logger.
      The default implementation infers a logger name from the package name of the `source` object. Subclasses should override this method if they can provide a more determinist logger instance, typically from a static final constant.
      Returns:
        the logger where to send the warnings when there is no other destination.

    - #### warning

          public void warning(LogRecord record)

      Reports a warning represented by the given log record. The default implementation forwards the given record to one of the following destinations, in preference order:
      1. `WarningListener​.warningOccured(source, record)` on all registered listeners it at least one such listener exists.
      2. `Logging​.getLogger(record.getLoggerName()).log(record)` if the logger name is non-null.
      3. `getLogger().log(record)` otherwise.
      Parameters:
        `record` - the warning as a log record.

    - #### warning

          public void warning(String message,
                              Exception exception)

      Reports a warning represented by the given message and exception. At least one of `message` and `exception` shall be non-null. If both are non-null, then the exception message will be concatenated after the given message. If the exception is non-null, its stack trace will be omitted at logging time for avoiding to pollute console output (keeping in mind that this method should be invoked only for non-fatal warnings). See below for more explanation.

      This method is a shortcut for `warning(Level​.WARNING, message, exception)`.

      Parameters:
        `message` - the message to log, or `null` if none.
        `exception` - the exception to log, or `null` if none.

    - #### warning

          public void warning(Level level,
                              String message,
                              Exception exception)

      Reports a warning at the given level represented by the given message and exception. At least one of `message` and `exception` shall be non-null. If both are non-null, then the exception message will be concatenated after the given message.
      Stack trace omission
      If there is no registered listener, then the `warning(LogRecord)` method will send the record to the logger, but without the stack trace. This is done that way because stack traces consume lot of space in the logging files, while being considered implementation details in the context of `WarningListeners` (on the assumption that the logging message provides sufficient information). If the stack trace is desired, then users can either:
      - invoke `warning(LogRecord)` directly, or
      - override `warning(LogRecord)` and invoke `LogRecord​.setThrown(Throwable)` explicitely, or
      - register a listener which will log the record itself.
      Parameters:
        `level` - the warning level.
        `message` - the message to log, or `null` if none.
        `exception` - the exception to log, or `null` if none.

    - #### addWarningListener

          public void addWarningListener(WarningListener<? super S> listener)
                                  throws IllegalArgumentException

      Adds a listener to be notified when a warning occurred. When a warning occurs, there is a choice:
      - If this object has no warning listener, then the warning is logged at `Level​.WARNING`.
      - If this object has at least one warning listener, then all listeners are notified and the warning is not logged by this object.
      Parameters:
        `listener` - the listener to add.
      Throws:
        `IllegalArgumentException` - if the given listener is already registered.

    - #### removeWarningListener

          public void removeWarningListener(WarningListener<? super S> listener)
                                     throws NoSuchElementException

      Removes a previously registered listener.
      Parameters:
        `listener` - the listener to remove.
      Throws:
        `NoSuchElementException` - if the given listener is not registered.

    - #### getListeners

          public List<WarningListener<? super S>> getListeners()

      Returns all registered warning listeners, or an empty list if none. This method returns an unmodifiable snapshot of the listener list at the time this method is invoked.
      Returns:
        immutable list of all registered warning listeners.
      Since:
        0.8

    - #### hasListeners

          public boolean hasListeners()

      Returns `true` if this object contains at least one listener.
      Returns:
        `true` if this object contains at least one listener, `false` otherwise.
      Since:
        0.4

Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.