S
- the type of the source of warnings.public class WarningListeners<S> extends Object implements Localized
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:
WarningListener
is registered,
then all listeners are notified and the warning is not logged.
LogRecord.getLoggerName()
is non-null,
then the warning will be logged to that named logger.getLogger()
.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.WarningListener
,
DataStore.listeners
Defined in the sis-utility
module
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.
|
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.
|
public WarningListeners(S source)
getLogger()
,
unless at least one listener is registered.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.public WarningListeners(S source, WarningListeners<? super S> other)
DataStore
or other data producer needs to
be duplicated for concurrency reasons.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.public S getSource()
public Locale getLocale()
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
.getLocale
in interface Localized
null
if not explicitly defined.public Logger getLogger()
LogRecord
does not specify a logger.source
object.
Subclasses should override this method if they can provide a more determinist logger instance,
typically from a static final constant.public void warning(LogRecord record)
WarningListener.warningOccured(source, record)
on all registered listeners it at least one such listener exists.Logging.getLogger(record.getLoggerName()).log(record)
if the logger name is non-null.getLogger().log(record)
otherwise.record
- the warning as a log record.public void warning(String message, Exception exception)
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)
.
message
- the message to log, or null
if none.exception
- the exception to log, or null
if none.public void warning(Level level, String message, Exception exception)
message
and exception
shall be non-null.
If both are non-null, then the exception message will be concatenated after the given message.
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:
warning(LogRecord)
directly, orwarning(LogRecord)
and invoke LogRecord.setThrown(Throwable)
explicitely, orlevel
- the warning level.message
- the message to log, or null
if none.exception
- the exception to log, or null
if none.public void addWarningListener(WarningListener<? super S> listener) throws IllegalArgumentException
Level.WARNING
.listener
- the listener to add.IllegalArgumentException
- if the given listener is already registered.public void removeWarningListener(WarningListener<? super S> listener) throws NoSuchElementException
listener
- the listener to remove.NoSuchElementException
- if the given listener is not registered.public List<WarningListener<? super S>> getListeners()
public boolean hasListeners()
true
if this object contains at least one listener.true
if this object contains at least one listener, false
otherwise.Copyright © 2010–2017 The Apache Software Foundation. All rights reserved.