Class StoreListeners
- Object
-
- WarningListeners
-
- StoreListeners
-
- All Implemented Interfaces:
Localized
public class StoreListeners extends WarningListeners implements Localized
Holds a list ofStoreListener
instances and provides convenience methods for sending events. This is a helper class forDataStore
andResource
implementations.Observers can add listeners for being notified about events, and producers can invoke one of the
warning(…)
and other methods for emitting events.Warning eventsAll warnings are given to the listeners asLogRecord
instances (this allows localizable messages and additional information like stack trace, timestamp, etc.). ThisStoreListeners
class provides convenience methods likewarning(String, Exception)
, which buildLogRecord
from an exception or from a string. But all thosewarning(…)
methods ultimately delegate towarning(LogRecord)
, thus providing a single point that subclasses can override. When a warning is emitted, the default behavior is:- Notify all listeners registered for
WarningEvent
type in thisStoreListeners
and in the parent managers. - If previous step found no listener registered for
WarningEvent
, then log the warning in the first logger found in following choices:- The logger specified by
LogRecord.getLoggerName()
if non-null. - Otherwise the logger specified by
DataStoreProvider.getLogger()
if the provider can be found. - Otherwise a logger whose name is the source
DataStore
package name.
- The logger specified by
Thread safetyThe sameStoreListeners
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:
- 1.0
Defined in the
sis-storage
module
-
-
Constructor Summary
Constructors Constructor Description StoreListeners(StoreListeners parent, Resource source)
Creates a new instance with the given parent and initially no listener.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description <T extends StoreEvent>
voidaddListener(Class<T> eventType, StoreListener<? super T> listener)
Registers a listener to notify when the specified kind of event occurs.void
addWarningListener(WarningListener listener)
Deprecated.Replaced byaddListener(listener, WarningEvent.class)
.<T extends StoreEvent>
booleanfire(T event, Class<T> eventType)
Sends the given event to all listeners registered for the given type or for a super-type.Locale
getLocale()
Returns the locale used by this manager, ornull
if unspecified.Resource
getSource()
Returns the source of events.String
getSourceName()
Returns a short name or label for the source.boolean
hasListeners()
Deprecated.boolean
hasListeners(Class<? extends StoreEvent> eventType)
Returnstrue
if this object or its parent contains at least one listener for the given type of event.<T extends StoreEvent>
voidremoveListener(Class<T> eventType, StoreListener<? super T> listener)
Unregisters a listener previously added for the given type of events.void
removeWarningListener(WarningListener listener)
Deprecated.Replaced byremoveListener(listener, WarningEvent.class)
.void
warning(Exception exception)
Reports a warning described by the given exception.void
warning(String message)
Reports a warning described by the given message.void
warning(String message, Exception exception)
Reports a warning described by the given message and exception.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 description)
Reports a warning described by the given log record.-
Methods inherited from class WarningListeners
getListeners, getLogger
-
-
-
-
Constructor Detail
-
StoreListeners
public StoreListeners(StoreListeners parent, Resource source)
Creates a new instance with the given parent and initially no listener. The parent is typically the listeners of theDataStore
that created a resource.- Parameters:
parent
- the manager to notify in addition to this manager, ornull
if none.source
- the source of events. Can not be null.
-
-
Method Detail
-
getSource
public Resource getSource()
Returns the source of events. This value is specified at construction time.- Overrides:
getSource
in classWarningListeners
- Returns:
- the source of events.
-
getSourceName
public String getSourceName()
Returns a short name or label for the source. It may be the name of the file opened by a data store. The returned name can be useful in warning messages for identifying the problematic source.The default implementation fetches that name from the data store, or returns an arbitrary name if it can get it otherwise.
- Returns:
- a short name of label for the source (never
null
). - See Also:
DataStore.getDisplayName()
-
getLocale
public Locale getLocale()
Returns the locale used by this manager, ornull
if unspecified. That locale is typically inherited from theDataStore
locale and can be used for formatting messages.- Specified by:
getLocale
in interfaceLocalized
- Overrides:
getLocale
in classWarningListeners
- Returns:
- the locale for messages (typically specified by the data store), or
null
if unknown. - See Also:
DataStore.getLocale()
,StoreEvent.getLocale()
-
warning
public void warning(String message)
Reports a warning described by the given message.This method is a shortcut for
warning(Level.WARNING, message, null)
.- Parameters:
message
- the warning message to report.
-
warning
public void warning(Exception exception)
Reports a warning described by the given exception. The exception 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, null, exception)
.- Parameters:
exception
- the exception to report.
-
warning
public void warning(String message, Exception exception)
Reports a warning described by the given message and exception. At least one ofmessage
andexception
arguments 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)
.- Overrides:
warning
in classWarningListeners
- Parameters:
message
- the warning message to report, ornull
if none.exception
- the exception to report, ornull
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 ofmessage
andexception
arguments shall be non-null. If both are non-null, then the exception message will be concatenated after the given message.Stack trace omissionIf there is no registered listener for theWarningEvent
type, then thewarning(LogRecord)
method will send the record to a 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 ofStoreListeners
(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 invokeLogRecord.setThrown(Throwable)
explicitly, or - register a listener which will log the record itself.
- Overrides:
warning
in classWarningListeners
- Parameters:
level
- the warning level.message
- the message to log, ornull
if none.exception
- the exception to log, ornull
if none.
- invoke
-
warning
public void warning(LogRecord description)
Reports a warning described by the given log record. The default implementation forwards the given record to one of the following destinations, in preference order:StoreListener.eventOccured(new WarningEvent(source, record))
on all listeners registered for this kind of event.- Only if above step found no listener, then
Logging.getLogger(record.loggerName).log(record)
whereloggerName
is one of the following:record.getLoggerName()
if that value is non-null.- Otherwise the value of
DataStoreProvider.getLogger()
if the provider is found. - Otherwise the source
DataStore
package name.
- Overrides:
warning
in classWarningListeners
- Parameters:
description
- warning details provided as a log record.
-
fire
public <T extends StoreEvent> boolean fire(T event, Class<T> eventType)
Sends the given event to all listeners registered for the given type or for a super-type. This method first notifies the listeners registered in thisStoreListeners
, then notifies listeners registered in parentStoreListeners
s. Each listener will be notified only once even if it has been registered many times.- Type Parameters:
T
- compile-time value of theeventType
argument.- Parameters:
event
- the event to fire.eventType
- the type of events to be fired.- Returns:
true
if the event has been sent to at least one listener.
-
addListener
public <T extends StoreEvent> void addListener(Class<T> eventType, StoreListener<? super T> listener)
Registers a listener to notify when the specified kind of event occurs. Registering a listener for a giveneventType
also register the listener for all event sub-types. The same listener can be registered many times, but itsStoreListener.eventOccured(StoreEvent)
method will be invoked only once per event. This filtering applies even if the listener is registered on different resources in the same tree, for example a parent and its children.Warning eventsIfeventType
is assignable fromWarningEvent.class
, then registering that listener turns off logging of warning messages for this manager. This side-effect is applied on the assumption that the registered listener will handle warnings in its own way, for example by showing warnings in a widget.- Type Parameters:
T
- compile-time value of theeventType
argument.- Parameters:
eventType
- type ofStoreEvent
to listen (can not benull
).listener
- listener to notify about events.- See Also:
Resource.addListener(Class, StoreListener)
-
removeListener
public <T extends StoreEvent> void removeListener(Class<T> eventType, StoreListener<? super T> listener)
Unregisters a listener previously added for the given type of events. TheeventType
must be the exact same class than the one given to theaddListener(…)
method; this method does not remove listeners registered for subclasses and does not remove listeners registered in parent manager.If the same listener has been registered many times for the same even type, then this method removes only the most recent registration. In other words if
addListener(type, ls)
has been invoked twice, thenremoveListener(type, ls)
needs to be invoked twice in order to remove all instances of that listener. If the given listener is not found, then this method does nothing (no exception is thrown).Warning eventsIfeventType
isWarningEvent.class
and if, after this method invocation, there is no remaining listener for warning events, then thisStoreListeners
will send future warnings to the loggers.- Type Parameters:
T
- compile-time value of theeventType
argument.- Parameters:
eventType
- type ofStoreEvent
which were listened (can not benull
).listener
- listener to stop notifying about events.- See Also:
Resource.removeListener(Class, StoreListener)
-
hasListeners
public boolean hasListeners(Class<? extends StoreEvent> eventType)
Returnstrue
if this object or its parent contains at least one listener for the given type of event.- Parameters:
eventType
- the type of event for which to check listener presence.- Returns:
true
if this object contains at least one listener for given event type,false
otherwise.
-
hasListeners
@Deprecated public boolean hasListeners()
Deprecated.Returnstrue
if this object contains at least one listener.- Overrides:
hasListeners
in classWarningListeners
- Returns:
true
if this object contains at least one listener,false
otherwise.
-
addWarningListener
@Deprecated public void addWarningListener(WarningListener listener)
Deprecated.Replaced byaddListener(listener, WarningEvent.class)
.Description copied from class:WarningListeners
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.
- Overrides:
addWarningListener
in classWarningListeners
- Parameters:
listener
- the listener to add.
- If this object has no warning listener, then the warning is logged at
-
removeWarningListener
@Deprecated public void removeWarningListener(WarningListener listener)
Deprecated.Replaced byremoveListener(listener, WarningEvent.class)
.Description copied from class:WarningListeners
Removes a previously registered listener.- Overrides:
removeWarningListener
in classWarningListeners
- Parameters:
listener
- the listener to remove.
-
-