Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com
Answertopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 


Eclipse Platform
Release 3.5

org.eclipse.core.databinding.observable
Class Realm


java.lang.Object
  extended by 
org.eclipse.core.databinding.observable.Realm

public abstract class Realm
extends Object

A realm defines a context from which objects implementing IObservable must be accessed, and on which these objects will notify their listeners. To bridge between observables from different realms, subclasses of Binding can be used.

A block of code is said to be executing within a realm if calling isCurrent() from that block returns true. Code reached by calling methods from that block will execute within the same realm, with the exception of methods on this class that can be used to execute code within a specific realm. Clients can use syncExec(Runnable), asyncExec(Runnable), or exec(Runnable) to execute a runnable within this realm. Note that using syncExec(Runnable) can lead to deadlocks and should be avoided if the current thread holds any locks.

It is instructive to think about possible implementations of Realm: It can be based on executing on a designated thread such as a UI thread, or based on holding a lock. In the former case, calling syncExec on a realm that is not the current realm will execute the given runnable on a different thread (the designated thread). In the latter case, calling syncExec may execute the given runnable on the calling thread, but calling asyncExec(Runnable) will execute the given runnable on a different thread. Therefore, no assumptions can be made about the thread that will execute arguments to asyncExec(Runnable), syncExec(Runnable), or exec(Runnable).

It is possible that a block of code is executing within more than one realm. This can happen for implementations of Realm that are based on holding a lock but don't use a separate thread to run runnables given to syncExec(Runnable). Realm implementations of this kind should be appropriately documented because it increases the opportunity for deadlock.

Some implementations of IObservable provide constructors which do not take a Realm argument and are specified to create the observable instance with the current default realm. The default realm can be set for the currently executing thread by using runWithDefault(Realm, Runnable). Note that the default realm does not have to be the current realm.

Subclasses must override at least one of asyncExec()/syncExec(). For realms based on a designated thread, it may be easier to implement asyncExec and keep the default implementation of syncExec. For realms based on holding a lock, it may be easier to implement syncExec and keep the default implementation of asyncExec.

Since:
1.0
See Also:
IObservable

Constructor Summary
Realm ()
           
 
Method Summary
 void asyncExec ( Runnable runnable)
          Causes the run() method of the runnable to be invoked from within this realm at the next reasonable opportunity.
 void exec ( Runnable runnable)
          Causes the run() method of the runnable to be invoked from within this realm.
static  Realm getDefault ()
          Returns the default realm for the calling thread, or null if no default realm has been set.
abstract  boolean isCurrent ()
           
static void runWithDefault ( Realm realm, Runnable runnable)
          Sets the provided realm as the default for the duration of Runnable.run() and resets the previous realm after completion.
protected static void safeRun ( Runnable runnable)
          Runs the given runnable.
protected static  Realm setDefault ( Realm realm)
          Sets the default realm for the calling thread, returning the current default thread.
protected  void syncExec ( Runnable runnable)
          Causes the run() method of the runnable to be invoked from within this realm at the next reasonable opportunity.
 void timerExec (int milliseconds, Runnable runnable)
          Causes the run() method of the runnable to be invoked from within this realm after the specified number of milliseconds have elapsed.
 
Methods inherited from class java.lang. Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Realm

public Realm()
Method Detail

getDefault

public static 
Realm getDefault()
Returns the default realm for the calling thread, or null if no default realm has been set.

Returns:
the default realm, or null

setDefault

protected static 
Realm setDefault(
Realm realm)
Sets the default realm for the calling thread, returning the current default thread. This method is inherently unsafe, it is recommended to use runWithDefault(Realm, Runnable) instead. This method is exposed to subclasses to facilitate testing.

Parameters:
realm - the new default realm, or null
Returns:
the previous default realm, or null

isCurrent

public abstract boolean isCurrent()
Returns:
true if the caller is executing in this realm. This method must not have side-effects (such as, for example, implicitly placing the caller in this realm).

safeRun

protected static void safeRun(
Runnable runnable)
Runs the given runnable. If an exception occurs within the runnable, it is logged and not re-thrown. If the runnable implements ISafeRunnable, the exception is passed to its handleException method.

Parameters:
runnable -

exec

public void exec(
Runnable runnable)
Causes the run() method of the runnable to be invoked from within this realm. If the caller is executing in this realm, the runnable's run method is invoked directly, otherwise it is run at the next reasonable opportunity using asyncExec.

If the given runnable is an instance of ISafeRunnable, its exception handler method will be called if any exceptions occur while running it. Otherwise, the exception will be logged.

Parameters:
runnable -

asyncExec

public void asyncExec(
Runnable runnable)
Causes the run() method of the runnable to be invoked from within this realm at the next reasonable opportunity. The caller of this method continues to run in parallel, and is not notified when the runnable has completed.

If the given runnable is an instance of ISafeRunnable, its exception handler method will be called if any exceptions occur while running it. Otherwise, the exception will be logged.

Subclasses should use safeRun(Runnable) to run the runnable.

Parameters:
runnable -

timerExec

public void timerExec(int milliseconds,
                      
Runnable runnable)
Causes the run() method of the runnable to be invoked from within this realm after the specified number of milliseconds have elapsed. If milliseconds is less than zero, the runnable is not executed. The caller of this method continues to run in parallel, and is not notified when the runnable has completed.

If the given runnable is an instance of ISafeRunnable, its exception handler method will be called if any exceptions occur while running it. Otherwise, the exception will be logged.

Subclasses should use safeRun(Runnable) to run the runnable.

Parameters:
milliseconds -
runnable -
Since:
1.2

syncExec

protected void syncExec(
Runnable runnable)
Causes the run() method of the runnable to be invoked from within this realm at the next reasonable opportunity. This method is blocking the caller until the runnable completes.

If the given runnable is an instance of ISafeRunnable, its exception handler method will be called if any exceptions occur while running it. Otherwise, the exception will be logged.

Subclasses should use safeRun(Runnable) to run the runnable.

Note: This class is not meant to be called by clients and therefore has only protected access.

Parameters:
runnable -

runWithDefault

public static void runWithDefault(
Realm realm,
                                  
Runnable runnable)
Sets the provided realm as the default for the duration of Runnable.run() and resets the previous realm after completion. Note that this will not set the given realm as the current realm.

Parameters:
realm -
runnable -

Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire