Package org.dellroad.stuff.vaadin24.util

Class VaadinExternalListener<S>

java.lang.Object
org.dellroad.stuff.vaadin24.util.VaadinExternalListener<S>
Type Parameters:
S - The type of the event source
public abstract class VaadinExternalListener<S> extends Object
Support superclass for listeners in a Vaadin session who need to listen 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, where "non-Vaadin" means not operating in the context of a VaadinSession and not holding the corresponding lock.

Use the methods register() and unregister() from within a VaadinSession to control listener registration.

Subclasses must then implement registerExternal(S) and unregisterExternal(S) to perform the actual external registration/unregister operations, and then when notified by the external source, must use handleEvent() to relay the notification back to the caller with the VaadinSession safely locked.

Use of this class will prevent these bugs from happening:

  • Notifications being delivered without the VaadinSession being locked;
  • Race conditions between unregistering a listener and receiving a listener notification; and
  • Memory leaks that occur if the Vaadin application is closed while listeners are still registered

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

  • Constructor Details

  • Method Details

    • register

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

      This method may be invoked from any context.

      Throws:
      IllegalStateException - if this instance is already registered

    • unregister

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

      This method may be invoked from any context.

    • getSession

      public final VaadinSession getSession()
      Get the VaadinSession 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 while the VaadinSession with which this instance is associated is locked.

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

      This method delegates to VaadinUtil.accessSession() to actually handle the event.

      Parameters:
      action - action to perform
      Throws:
      IllegalArgumentException - if action is null

    • handleException

      protected void handleException(RuntimeException e)
      Handle a RuntimeException thrown by the handleEvent callback.

      The implementation in VaadinExternalListener logs an error and then re-throws the exception.

      Parameters:
      e - exception thrown

    • registerExternal

      protected abstract void registerExternal(S eventSource)
      Register as a listener on the given external 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

    • unregisterExternal

      protected abstract void unregisterExternal(S eventSource)
      Register as a listener from the given external 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