Package org.dellroad.stuff.vaadin8

Class VaadinExternalListener<S>

  • Type Parameters:
    S - The type of the event source
    public abstract class VaadinExternalListener<S>
extends Object
    Support superclass customized for use by listeners that are part of a Vaadin application when listening to non-Vaadin ("external") event sources.

    Listeners that are part of a Vaadin application should use this superclass if they are going to be registered with non-Vaadin event sources, and use the methods register() and unregister() to control listener registration. Subclasses implement register(S) and register(S) to perform the actual listener registration/unregister operations.

    Use of this class will ensure two things:

    • Events are delivered in the proper Vaadin application context; and
    • The listener is automatically unregistered from the external event source when the Vaadin application is closed, avoiding a memory leak

    Important: subclass listener methods must use handleEvent() when handling events. This will ensure proper locking to avoid race conditions.

    Note: when listening to event sources that are scoped to specific Vaadin application instances and already originate events within the proper Vaadin application context (i.e., event sources that are not external to the Vaadin application), then the use of this superclass is not necessary (however, it also doesn't hurt to use it anyway).

    • Method Detail

      • isAsynchronous

        public boolean isAsynchronous()
        Determine whether this instance is configured for asynchronous notification. Default false.
        Returns:
        true if this instance will notify asynchronously

      • setAsynchronous

        public void setAsynchronous​(boolean asynchronous)
        Set whether to notify asynchronously. If set, VaadinSession.access() will be used for notifications, so that these occur on a different thread from the original notifying thread.
        Parameters:
        asynchronous - true to notify asynchronously, false for synchronous notifications
        See Also:
        handleEvent()

      • register

        public void register()
        Register as a listener on configured event source.

        This also listens for shutdown of the configured Vaadin application, so that when the application closes we can unregister this instance from the event source to avoid a memory leak.

        Throws:
        IllegalStateException - if this instance is already registered

      • unregister

        public void unregister()
        Un-register as a listener on configured event source.

        This also removes the listener registered by register().

      • getSession

        public final VaadinSession getSession()
        Get the VaadinSession (aka Vaadin application) with which this instance is associated.
        Returns:
        associated session

      • getEventSource

        public final S getEventSource()
        Get the event source with which this instance is (or was) registered as a listener.
        Returns:
        associated event source

      • handleEvent

        protected void handleEvent​(Runnable action)
        Execute the given listener action using the VaadinSession with which this instance is associated.

        Subclass listener methods should handle events by invoking this method to ensure proper locking to avoid race conditions.

        This method delegates to VaadinSession.accessSynchronously(), or VaadinSession.access() if this instance is configured to be asynchronous.

        Parameters:
        action - action to perform

      • register

        protected abstract void register​(S eventSource)
        Register as a listener on the given event source.

        Subclass must implement this to perform the actual listener registration.

        Parameters:
        eventSource - event source, never null; will be same as provided to the constructor

      • unregister

        protected abstract void unregister​(S eventSource)
        Register as a listener from the given event source.

        Subclass must implement this to perform the actual listener registration.

        Parameters:
        eventSource - event source, never null; will be same as provided to the constructor