Package org.apache.sis.storage.event

Class StoreListeners

  • All Implemented Interfaces:
    Localized
    public class StoreListeners
extends WarningListeners
implements Localized
    Holds a list of Store­Listener instances and provides convenience methods for sending events. This is a helper class for Data­Store and Resource 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 events
    All warnings are given to the listeners as Log­Record instances (this allows localizable messages and additional information like stack trace, timestamp, etc.). This Store­Listeners class provides convenience methods like warning(String, Exception), which build Log­Record from an exception or from a string. But all those warning(…) methods ultimately delegate to warning(Log­Record), thus providing a single point that subclasses can override. When a warning is emitted, the default behavior is:
    • Notify all listeners registered for Warning­Event type in this Store­Listeners and in the parent managers.
    • If previous step found no listener registered for Warning­Event, then log the warning in the first logger found in following choices:
      1. The logger specified by Log­Record​.get­Logger­Name() if non-null.
      2. Otherwise the logger specified by Data­Store­Provider​.get­Logger() if the provider can be found.
      3. Otherwise a logger whose name is the source Data­Store package name.
    Thread safety
    The same Store­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:
    1.0

    Defined in the sis-storage module

    • 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 the Data­Store that created a resource.
        Parameters:
        parent - the manager to notify in addition to this manager, or null 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:
        get­Source in class Warning­Listeners
        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:
        Data­Store​.get­Display­Name()

      • 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 of message and exception 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 class Warning­Listeners
        Parameters:
        message - the warning message to report, or null if none.
        exception - the exception to report, 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 arguments 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 for the Warning­Event type, then the warning(Log­Record) 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 of Store­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) explicitly, or
        • register a listener which will log the record itself.
        Overrides:
        warning in class Warning­Listeners
        Parameters:
        level - the warning level.
        message - the message to log, or null if none.
        exception - the exception to log, or null if none.

      • 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 this Store­Listeners, then notifies listeners registered in parent Store­Listenerss. Each listener will be notified only once even if it has been registered many times.
        Type Parameters:
        T - compile-time value of the event­Type argument.
        Parameters:
        event - the event to fire.
        event­Type - 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 given event­Type also register the listener for all event sub-types. The same listener can be registered many times, but its Store­Listener​.event­Occured(Store­Event) 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 events
        If event­Type is assignable from Warning­Event.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 the event­Type argument.
        Parameters:
        event­Type - type of Store­Event to listen (can not be null).
        listener - listener to notify about events.
        See Also:
        Resource​.add­Listener(Class, Store­Listener)

      • 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. The event­Type must be the exact same class than the one given to the add­Listener(…) 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 add­Listener(type, ls) has been invoked twice, then remove­Listener(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 events
        If event­Type is Warning­Event.class and if, after this method invocation, there is no remaining listener for warning events, then this Store­Listeners will send future warnings to the loggers.
        Type Parameters:
        T - compile-time value of the event­Type argument.
        Parameters:
        event­Type - type of Store­Event which were listened (can not be null).
        listener - listener to stop notifying about events.
        See Also:
        Resource​.remove­Listener(Class, Store­Listener)

      • hasListeners

        public boolean hasListeners​(Class<? extends StoreEvent> eventType)
        Returns true if this object or its parent contains at least one listener for the given type of event.
        Parameters:
        event­Type - 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.
        Returns true if this object contains at least one listener.
        Overrides:
        has­Listeners in class Warning­Listeners
        Returns:
        true if this object contains at least one listener, false otherwise.

      • addWarningListener

        @Deprecated
public void addWarningListener​(WarningListener listener)
        Deprecated.
        Replaced by add­Listener(listener, Warning­Event​.class).
        Description copied from class: Warning­Listeners
        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:
        add­Warning­Listener in class Warning­Listeners
        Parameters:
        listener - the listener to add.