bibliothek.gui.dock
Class DockHierarchyLock

java.lang.Object
  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:

• Any token acquired while isConcurrent() returns true will be ignored.
• There is a queue of Runnables, run will be added to the end of that queue. The queue will be executed from the beginning to the end, this order cannot be changed.
• If this is a recursive call, then run will never be executed directly.
• If currently no DockHierarchyLock.Token is acquired, then run is executed immediatelly.
• run is always executed in the EDT, other Threads may be blocked until run is completed

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