org.eclipse.rwt.lifecycle
Class UICallBack

java.lang.Object
  org.eclipse.rwt.lifecycle.UICallBack

public final class UICallBack
extends java.lang.Object

A utility class that provides methods to perform tasks related to UI updates from background threads.

Since:

1.0

Method Summary

static void	activate(java.lang.String id) Call this method to enable UI updates from background threads (e.g.
static void	deactivate(java.lang.String id) This method deactivates a previously activated UI callback with the same id.
static void	runNonUIThreadWithFakeContext(Display display, java.lang.Runnable runnable) Sometimes a background thread needs to access values that are stored in the session object that started the thread.

Methods inherited from class java.lang.Object

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

Method Detail

runNonUIThreadWithFakeContext

public static void runNonUIThreadWithFakeContext(Display display,
                                                 java.lang.Runnable runnable)

Sometimes a background thread needs to access values that are stored in the session object that started the thread. In particular these values may be stored in session singletons. Accessing these singletons directly from the background thread would fail. This method fakes the missing request context and allows the runnable code to access those singletons.

Parameters:

display - The display that is bound to the session that contains the data to which the current thread should get access.

runnable - The runnable that contains the critical code that needs to have access to a request context.

See Also:

SessionSingletonBase, org.eclipse.rwt.internal.service.ContextProvider

activate

public static void activate(java.lang.String id)

Call this method to enable UI updates from background threads (e.g. via Display.asyncExec()}. The UI callback must be activated from the UI thread before the background thread starts. Each activation is given a session-unique id to allow reference-counting activation and deactivation.

If not deactivated explicitly, any active UI callbacks are released when the session terminates.

Note: this method must only be called from the UI-Thread of an RWT application.

Example code:

 final String callbackId = "callback id";
 Runnable bgRunnable = new Runnable() {
   public void run() {
   // do some work...
   // schedule the UI update
   display.asyncExec( new Runnable() {
     public void run() {
       if( !widget.isDisposed() ) {
         // update the UI
       }
     }
   } );
   // Deactivate the UI call-back
   UICallBack.runNonUIThreadWithFakeContext( display, new Runnable() {
     public void run() {
       UICallBack.deactivate( callbackId );
     }
   } );
   }
 };
 UICallBack.activate( callbackId );
 Thread bgThread = new Thread( bgRunnable );
 bgThread.setDaemon( true );
 bgThread.start();
 

Parameters:

id - a session unique identifier to trace the activation and deactivation. Must not be null.

Throws:

SWTException -

• ERROR_NULL_ARGUMENT - if the id is null
• ERROR_THREAD_INVALID_ACCESS - if not called from the UI thread

See Also:

Display.syncExec(java.lang.Runnable), Display.asyncExec(java.lang.Runnable), Display.getThread(), Display.wake()

deactivate

public static void deactivate(java.lang.String id)

This method deactivates a previously activated UI callback with the same id. Calling this method with an id that wasn't activated before has no effect.

For each id, the system maintains a reference counter so that multiple activations of the same id must be followed by the same number deactivations in oder to actually stop the UI callback.

Note: this method must only be called from code that is associated with a session. That is, either code running in the UI thread or executed via runNonUIThreadWithFakeContext(Display, Runnable)

Parameters:

id - A session unique identifier to trace the activation and deactivation. Must not be null

Throws:

SWTException -

• ERROR_NULL_ARGUMENT - if the id is null
• ERROR_THREAD_INVALID_ACCESS - if not called from session code

See Also:

Display.syncExec(java.lang.Runnable), Display.asyncExec(java.lang.Runnable), Display.getThread(), Display.wake()