Eclipse Rich Ajax Platform

## 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()`

Eclipse Rich Ajax Platform

Copyright (c) EclipseSource and others 2002, 2012. All rights reserved.