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 Warning­Listener instances and provides convenience methods for emitting warnings. The convenience warning(…) methods can build Log­Record from an exception or from a string.

In the default implementation, all warning(…) methods delegate to warning(Log­Record), thus providing a single point that subclasses can override for intercepting all warnings. The default behavior is:

• If at least one Warning­Listener is registered, then all listeners are notified and the warning is not logged.
• Otherwise the warning is logged to the logger returned by get­Logger().

Thread safety

The same Warning­Listeners 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:

Warning­Listener, Data­Store.listeners

Defined in the sis-utility module

Constructor Summary

Constructors

Constructor and Description
Warning­Listeners(S source) Creates a new instance with initially no listener.

Method Summary

Modifier and Type	Method and Description
void	add­Warning­Listener(Warning­Listener<? super S> listener) Adds a listener to be notified when a warning occurred.
Locale	get­Locale() The locale to use for formatting warning messages, or null for the default locale.
Logger	get­Logger() Returns the logger where to send the warnings.
boolean	has­Listeners() Returns true if this object contains at least one listener.
void	remove­Warning­Listener(Warning­Listener<? super S> listener) Removes a previously registered listener.
void	warning(Log­Record 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, get­Class, hash­Code, notify, notify­All, to­String, wait, wait, wait

Constructor Detail

WarningListeners

public WarningListeners(S source)

Creates a new instance with initially no listener. Warnings will be logger to the given logger, 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.

Method Detail

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 get­Locale() method. Otherwise this method returns null.

Specified by:

get­Locale in interface Localized

Returns:

The locale, or null if not explicitly defined.

getLogger

public Logger getLogger()

Returns the logger where to send the warnings. The default implementation returns a logger for the package name of the source object. Subclasses should override this method if they can provide a fixed logger instance (typically a static final constant).

Returns:

The logger where to send the warnings when there is no registered listeners.

warning

public void warning(LogRecord record)

Reports a warning represented by the given log record. The default implementation notifies the listeners if any, or logs the message to the logger returned by get­Logger() 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.

Stack trace omission

If there is no registered listener, then the warning(Log­Record) 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 Warning­Listeners (on the assumption that the logging message provides sufficient information). If the stack trace is desired, then users can either:

• invoke warning(Log­Record) directly, or
• override warning(Log­Record) and invoke Log­Record.set­Thrown(Throwable) explicitely, or
• register a listener which will log the record itself.

Parameters:

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:

Illegal­Argument­Exception - 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:

No­Such­Element­Exception - If the given listener is not registered.

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