bibliothek.gui.dock
Class DockHierarchyLock

java.lang.Object
  extended by bibliothek.gui.dock.DockHierarchyLock

public class DockHierarchyLock
extends Object

The DockHierarchyLock allows DockStations to defend themselfs against concurrent modifications of the hierarchy. At any time only one DockStation or a class working with DockStations in the realm of a DockController can acquire the lock.

Author:
Benjamin Sigg

Nested Class Summary
static class DockHierarchyLock.Token
          Is acquired from a DockHierarchyLock and releases the lock.
 
Constructor Summary
DockHierarchyLock()
           
 
Method Summary
 DockHierarchyLock.Token acquire(DockStation station)
          Acquires a lock describing the entire contents of station.
static DockHierarchyLock.Token acquireFake()
          Acquires a fake token which does not lock anything.
 DockHierarchyLock.Token acquireLink(DockStation station, Dockable dockable)
          Allows station to become the new parent of dockable.
static DockHierarchyLock.Token acquireLinking(DockStation station, Dockable dockable)
          The same as calling acquireLink(DockStation, Dockable) with the DockHierarchyLock of the DockController of station.
 DockHierarchyLock.Token acquireUnlink(DockStation station, Dockable dockable)
          Allows station to remove itself as parent from dockable.
static DockHierarchyLock.Token acquireUnlinking(DockStation station, Dockable dockable)
          The same as calling acquireUnlink(DockStation, Dockable) with the DockHierarchyLock of the DockController of station.
static DockHierarchyLock.Token acquiring(DockStation station)
          The same as calling acquire(DockStation) with the DockHierarchyLock of the DockController of station.
 boolean isConcurrent()
          Whether this lock throws exceptions or is silent.
 boolean isHardExceptions()
          Tells whether hard exceptions should be thrown or only printed.
 void onRelease(Runnable run)
          Executes run once no DockHierarchyLock.Token is acquired anymore.
 void setConcurrent(boolean concurrent)
          Tells this lock whether concurrent modifications are allowed or not.
 void setHardExceptions(boolean hardExceptions)
          Sets whether exceptions should be thrown or only printed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DockHierarchyLock

public DockHierarchyLock()
Method Detail

setHardExceptions

public void setHardExceptions(boolean hardExceptions)
Sets whether exceptions should be thrown or only printed.

Parameters:
hardExceptions - true if the exceptions should be thrown

isHardExceptions

public boolean isHardExceptions()
Tells whether hard exceptions should be thrown or only printed.

Returns:
true if exceptions should be thrown
See Also:
setHardExceptions(boolean)

setConcurrent

public void setConcurrent(boolean concurrent)
Tells this lock whether concurrent modifications are allowed or not. If allowed no exception will be thrown due to a lock being acquired while a lock is already held.

Parameters:
concurrent - whether to allow concurrent modification or not

isConcurrent

public boolean isConcurrent()
Whether this lock throws exceptions or is silent.

Returns:
if true, then this lock is silent
See Also:
isConcurrent()

onRelease

public void onRelease(Runnable run)
Executes run once no DockHierarchyLock.Token is acquired anymore. The exact order of how and when the Runnables are executed is:

Parameters:
run - the Runnable to executed, not null
Throws:
IllegalArgumentException - if run is null
IllegalStateException - if an InterruptedException is caought

acquireLinking

public static DockHierarchyLock.Token acquireLinking(DockStation station,
                                                     Dockable dockable)
The same as calling acquireLink(DockStation, Dockable) with the DockHierarchyLock of the DockController of station. Returns a fake DockHierarchyLock.Token if station has no DockController.

Parameters:
station - the station which wants to be the new parent of dockable
dockable - a dockable with no parent
Returns:
the acquired token to release the lock
Throws:
IllegalStateException - if dockable has a parent or station thinks that dockable is one of its children

acquireUnlinking

public static DockHierarchyLock.Token acquireUnlinking(DockStation station,
                                                       Dockable dockable)
The same as calling acquireUnlink(DockStation, Dockable) with the DockHierarchyLock of the DockController of station. Returns a fake DockHierarchyLock.Token if station has no DockController.

Parameters:
station - the current parent of dockable
dockable - a dockable with station as parent
Returns:
the acquired token to release the lock
Throws:
IllegalStateException - if dockable is not a child of station

acquiring

public static DockHierarchyLock.Token acquiring(DockStation station)
The same as calling acquire(DockStation) with the DockHierarchyLock of the DockController of station. Returns a fake DockHierarchyLock.Token if station has no DockController.

Parameters:
station - the station to lock
Returns:
the acquired token to release the lock
Throws:
IllegalStateException - if a lock has already been acquired

acquireFake

public static DockHierarchyLock.Token acquireFake()
Acquires a fake token which does not lock anything. This method never throws an exception.

Returns:
the fake token

acquireLink

public DockHierarchyLock.Token acquireLink(DockStation station,
                                           Dockable dockable)
Allows station to become the new parent of dockable.

Parameters:
station - the station which wants to be the new parent of dockable
dockable - a dockable with no parent
Returns:
the acquired token to release the lock
Throws:
IllegalStateException - if dockable has a parent or station thinks that dockable is one of its children

acquireUnlink

public DockHierarchyLock.Token acquireUnlink(DockStation station,
                                             Dockable dockable)
Allows station to remove itself as parent from dockable.

Parameters:
station - the current parent of dockable
dockable - a dockable with station as parent
Returns:
the acquired token to release the lock
Throws:
IllegalStateException - if dockable is not a child of station

acquire

public DockHierarchyLock.Token acquire(DockStation station)
Acquires a lock describing the entire contents of station. This method is intended in situations where the layout of station gets modified and this modification must not be interrupted.

Parameters:
station - the station for which a lock is requested
Returns:
the acquired token to release the lock
Throws:
IllegalStateException - if the lock is already acquired