VaadinExternalListener (DellRoad Stuff Vaadin 7.x Classes 2.1.0 API)

java.lang.Object
- org.dellroad.stuff.vaadin7.VaadinExternalListener<S>

Type Parameters:

S - The type of the event source

Direct Known Subclasses:

VaadinApplicationListener
```
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).
See Also:

VaadinUtil.invoke(com.vaadin.server.VaadinSession, java.lang.Runnable), VaadinApplicationScope, VaadinApplicationListener, SpringVaadinSessionListener

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`VaadinExternalListener(S eventSource)` Convenience constructor.
`protected`	`VaadinExternalListener(S eventSource, VaadinApplication application)` Convenience constructor.
`protected`	`VaadinExternalListener(S eventSource, VaadinSession session)` Primary constructor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`S`	`getEventSource()` Get the event source with which this instance is (or was) registered as a listener.
`VaadinSession`	`getSession()` Get the `VaadinSession` (aka Vaadin application) with which this instance is associated.
`protected void`	`handleEvent(Runnable action)` Execute the given listener action using the `VaadinSession` with which this instance is associated.
`boolean`	`isAsynchronous()` Determine whether this instance is configured for asynchronous notification.
`void`	`register()` Register as a listener on configured event source.
`protected abstract void`	`register(S eventSource)` Register as a listener on the given event source.
`void`	`setAsynchronous(boolean asynchronous)` Set whether to notify asynchronously.
`void`	`unregister()` Un-register as a listener on configured event source.
`protected abstract void`	`unregister(S eventSource)` Register as a listener from the given event source.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - VaadinExternalListener
```
protected VaadinExternalListener(S eventSource)
```
    Convenience constructor. Equivalent to:
    VaadinExternalListener(eventSource, VaadinUtil.getCurrentSession())
    
    Parameters:
    
    eventSource - the event source on which this listener will register
    
    Throws:
    
    IllegalArgumentException - if eventSource is null
    
    IllegalStateException - if there is no VaadinSession associated with the current thread
  - VaadinExternalListener
```
protected VaadinExternalListener(S eventSource,
                                 VaadinApplication application)
```
    Convenience constructor. Equivalent to:
    VaadinExternalListener(eventSource, application.getSession())
    
    Parameters:
    
    eventSource - the event source on which this listener will register
    
    application - the VaadinApplication that this listener is part of
    
    Throws:
    
    IllegalArgumentException - if eventSource is null
    
    NullPointerException - if application is null
  - VaadinExternalListener
```
protected VaadinExternalListener(S eventSource,
                                 VaadinSession session)
```
    Primary constructor.
    
    Parameters:
    
    eventSource - the event source on which this listener will register when register() is invoked
    
    session - the associated Vaadin application's session
    
    Throws:
    
    IllegalArgumentException - if either parameter is null
- 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, VaadinUtil.invokeLater() 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 registers a SessionDestroyListener on the configured Vaadin application, so that when the application closes we can unregister this instance from the event source to avoid a memory leak.
  - unregister
```
public void unregister()
```
    Un-register as a listener on configured event source.
    This also unregisters the SessionDestroyListener 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 VaadinUtil.invoke(), or VaadinUtil.invokeLater() if this instance is configured to be asynchronous.
    
    Parameters:
    
    action - action to perform
    
    See Also:
    
    VaadinUtil.invoke(com.vaadin.server.VaadinSession, java.lang.Runnable)
  - 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

Class VaadinExternalListener<S>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

VaadinExternalListener

VaadinExternalListener

VaadinExternalListener

Method Detail

isAsynchronous

setAsynchronous

register

unregister

getSession

getEventSource

handleEvent

register

unregister