org.dellroad.stuff.vaadin7

Class VaadinUtil

java.lang.Object

org.dellroad.stuff.vaadin7.VaadinUtil

public final class VaadinUtil
extends Object

Miscellaneous utility methods.

Method Summary

Modifier and Type	Method and Description
static void	addSessionDestroyListener(VaadinSession session, SessionDestroyListener listener) Register for a notification when the VaadinSession is closed, without creating a memory leak.
static void	assertSession(VaadinSession session) Verify that we are running in the context of the given session and holding the session's lock.
static VaadinRequest	getCurrentRequest() Get the VaadinRequest associated with the current thread.
static VaadinSession	getCurrentSession() Get the VaadinSession associated with the current thread.
static void	invoke(VaadinSession session, Runnable action) Peform some action while holding the given VaadinSession's lock.
static Future<Void>	invokeLater(VaadinSession session, Runnable action) Peform some action while holding the given VaadinSession's lock, but do so asynchronously.
static void	removeSessionDestroyListener(VaadinSession session, SessionDestroyListener listener) Remove a listener added via addSessionDestroyListener().

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

assertSession

public static void assertSession(VaadinSession session)

Verify that we are running in the context of the given session and holding the session's lock. This method can be used by any code that manipulates Vaadin state to assert that the proper Vaadin locking has been performed.

Parameters:

session - session we are supposed to be running with

Throws:

IllegalArgumentException - if session is null

IllegalStateException - if there is no VaadinSession associated with the current thread

IllegalStateException - if the VaadinSession associated with the current thread is not session

IllegalStateException - if the VaadinSession associated with the current thread is not locked

IllegalStateException - if the VaadinSession associated with the current thread is locked by another thread

getCurrentSession

public static VaadinSession getCurrentSession()

Get the VaadinSession associated with the current thread. This is just a wrapper around VaadinSession.getCurrent() that throws an exception instead of returning null when there is no session associated with the current thread.

Returns:

current VaadinSession, never null

Throws:

IllegalStateException - if there is no VaadinSession associated with the current thread

getCurrentRequest

public static VaadinRequest getCurrentRequest()

Get the VaadinRequest associated with the current thread. This is just a wrapper around VaadinService.getCurrentRequest() that throws an exception instead of returning null when there is no request associated with the current thread.

Returns:

current VaadinRequest, never null

Throws:

IllegalStateException - if there is no VaadinRequest associated with the current thread

invoke

public static void invoke(VaadinSession session,
                          Runnable action)

Peform some action while holding the given VaadinSession's lock.

This method now just invokes VaadinSession.accessSynchronously(java.lang.Runnable), a method which didn't exist in earlier versions of Vaadin.

All back-end threads that interact with Vaadin components must use this method (or invokeLater()) to avoid race conditions. Since session locks are re-entrant, it will not cause problems if this method is also used by a "front-end" (i.e., Vaadin HTTP request) thread.

Note: when executing within a Vaadin HTTP request, the current thread's VaadinSession is available via VaadinSession.getCurrent(); consider also using VaadinApplication.invoke(java.lang.Runnable) instead of this method.

Warning: background threads should be careful when invoking this method to ensure they are not already holding an application-specific lock that a separate HTTP request thread could attempt to acquire during its normal processing: because the HTTP request thread will probably already be holding the session lock when it attempts to acquire the application-specific lock, this creates the potential for a lock-ordering reversal deadlock.

Parameters:

session - Vaadin session

action - action to perform

Throws:

IllegalArgumentException - if either parameter is null

See Also:

VaadinApplication.invoke(java.lang.Runnable)

invokeLater

public static Future<Void> invokeLater(VaadinSession session,
                                       Runnable action)

Peform some action while holding the given VaadinSession's lock, but do so asynchronously.

Here the term "asynchronously" means:

• If any thread holds the session lock (including the current thread), this method will return immediately and the action will be performed later, when the session is eventually unlocked.
• If no thread holds the session lock, the session will be locked and the action performed synchronously by the current thread.

This method now just invokes VaadinSession.access(java.lang.Runnable), a method which didn't exist in earlier versions of Vaadin.

Note: when executing within a Vaadin HTTP request, the current thread's VaadinSession is available via VaadinSession.getCurrent(); consider also using VaadinApplication.invokeLater(java.lang.Runnable) instead of this method.

Parameters:

session - Vaadin session

action - action to perform

Returns:

a corresponding Future

Throws:

IllegalArgumentException - if either parameter is null

See Also:

invoke(com.vaadin.server.VaadinSession, java.lang.Runnable), VaadinApplication.invokeLater(java.lang.Runnable)

addSessionDestroyListener

public static void addSessionDestroyListener(VaadinSession session,
                                             SessionDestroyListener listener)

Register for a notification when the VaadinSession is closed, without creating a memory leak. This method is intended to be used by listeners that are themselves part of a Vaadin application.

Explanation: the VaadinSession class does not provide a listener API directly; instead, you must use the VaadinService class. However, registering as a listener on the VaadinService when you are part of a Vaadin application sets you up for a memory leak if you forget to unregister yourself when the notification arrives, because the VaadinService lifetime is longer than the VaadinSession lifetime. This method handles that de-registration for you automatically.

Parameters:

session - Vaadin session

listener - listener for notifications

Throws:

IllegalArgumentException - if either parameter is null

See Also:

VaadinApplication.addSessionDestroyListener(com.vaadin.server.SessionDestroyListener)

removeSessionDestroyListener

public static void removeSessionDestroyListener(VaadinSession session,
                                                SessionDestroyListener listener)

Remove a listener added via addSessionDestroyListener().

Parameters:

session - Vaadin session

listener - listener for notifications

Throws:

IllegalArgumentException - if either parameter is null

See Also:

VaadinApplication.removeSessionDestroyListener(com.vaadin.server.SessionDestroyListener)