bibliothek.gui.dock.support.mode
Class ModeManager<H,M extends Mode<H>>

java.lang.Object
  extended by bibliothek.gui.dock.support.mode.ModeManager<H,M>
Type Parameters:
H - the kind of properties that are to be stored in this manager
M - the kind of Modes used by this manager
Direct Known Subclasses:
LocationModeManager

public abstract class ModeManager<H,M extends Mode<H>>
extends Object

Associates Dockables with one Mode out of a set of modes. This manager remembers in which order the modes were applied to a Dockable.

Author:
Benjamin Sigg

Constructor Summary
ModeManager(DockController controller)
          Creates a new manager.
 
Method Summary
 void add(String key, Dockable dockable)
          Registers a new Dockable at this manager.
 void addAffected(Iterable<Dockable> dockables)
          Adds all elements of dockables to the current AffectedSet.
 void addEmpty(String key)
          Adds an empty entry to this manager.
 void addModeManagerListener(ModeManagerListener<? super H,? super M> listener)
          Adds a listener to this manager, the listener will be informed about changes in this manager.
 void apply(Dockable dockable, M mode, AffectedSet set, boolean force)
          Alters the mode of dockable to mode.
 void apply(Dockable dockable, M mode, boolean force)
          Alters the mode of dockable to mode.
 void apply(Dockable dockable, M mode, H history, AffectedSet set)
          Alters the mode of dockable to be mode.
 boolean apply(Dockable dockable, Path mode, AffectedSet set, boolean force)
          Alters the mode of dockable to mode.
 boolean apply(Dockable dockable, Path mode, boolean force)
          Alters the mode of dockable to mode.
 boolean apply(Dockable dockable, Path mode, H history, AffectedSet set)
          Alters the mode of dockable to be mode.
protected abstract  void applyDuringRead(String key, Path old, Path current, Dockable dockable)
          Called while reading modes in readSettings(ModeSettings).
protected  boolean createEntryDuringRead(String key)
          Tells whether an entry for a missing Dockable should be created.
<B> ModeSettings<H,B>
createModeSettings(ModeSettingsConverter<H,B> converter)
          Creates the empty set of settings for this ModeManager.
<B> ModeSettings<H,B>
createSettings(ModeSettingsConverter<H,B> converter)
          Creates a new ModeSetting which is configured to transfer data from this ModeManager to persistent storage or the other way.
 void destroy()
          Unregisters listeners which this manager added to the DockController and other components.
protected  void fireAdded(Dockable dockable)
          Calls ModeManagerListener.dockableAdded(ModeManager, Dockable) on all listeners that are currently registered
protected  void fireAdded(M mode)
          Calls ModeManagerListener.modeAdded(ModeManager, Mode) on all listeners that are currently registered.
protected  void fireModeChanged(Dockable dockable, M oldMode, M newMode)
          Calls ModeManagerListener.modeChanged(ModeManager, Dockable, Mode, Mode) on all listeners that are currently registered.
protected  void fireRemoved(Dockable dockable)
          Calls ModeManagerListener.dockableRemoved(ModeManager, Dockable) on all listeners that are currently registered.
protected  void fireRemoved(M mode)
          Calls ModeManagerListener.modeRemoved(ModeManager, Mode) on all listeners that are currently registered.
 DockController getController()
          Gets the controller in whose realm this manager works.
 M getCurrentMode(Dockable dockable)
          Tries to find the mode dockable is currently in.
protected  M getDefaultMode(Dockable dockable)
          Gets the default mode of dockable, the mode dockable is in if nothing else is specified.
 Dockable getDoubleClickTarget(Dockable target)
          Given some Dockable on which an event was registered, searches a registered dockable that is a child of target or target itself.
 Collection<ModeSettingFactory<H>> getFactories()
          Gets a set containing all the ModeSettingFactorys that were added to this manager.
protected  H getHistory(Dockable dockable, Path modeId)
          Gets the history of dockable in mode modeId.
 HistoryRewriter<H,M> getHistoryRewriter()
          Gets the current HistoryRewriter.
 String getKey(Dockable dockable)
          Gets the unique identifier which is used for dockable.
 M getMode(Path path)
          Searches and returns the mode with given unique identifier path.
 List<M> getModeHistory(Dockable dockable)
          Gets the history which modes dockable used in the past.
 M getPreviousMode(Dockable dockable)
          Reading the history this method tells which mode dockable was in before the current mode.
protected  H getProperties(M mode, Dockable dockable)
          Gets the properties which correspond to dockable and mode.
 List<H> getPropertyHistory(Dockable dockable)
          Gets the history which properties dockable used in the past.
abstract  DockActionSource getSharedActions(DockStation station)
          Gets a list of actions that should be shown on station depending on the current children of station.
 boolean isEmpty(String key)
          Tells whether information about dockable key gets stored indefinitely or not.
 boolean isOnContinuous()
          Tells whether this manager currently runs a continuous transaction.
 boolean isOnTransaction()
          Tells whether this manager is currently changing the Mode of a Dockable.
 boolean isRegistered(Dockable dockable)
          Tells whether this ModeManager knows dockable and can handle a call to any of the apply methods.
 Set<Dockable> listDockables()
          Returns a set containing all Dockables that are currently registered at this manager.
protected  ModeManagerListener<? super H,? super M>[] listeners()
          Gets all the listeners that are currently registered in this manager.
 Iterable<M> modes()
          Returns an iteration of all modes that are stored in this manager.
 void put(String key, Dockable dockable)
          Registers a new Dockable at this manager.
 void putFactory(ModeSettingFactory<H> factory)
          Adds a factory to this ModeManager.
 void putMode(M mode)
          Puts a new mode in this manager.
 void readSettings(ModeSettings<H,?> settings)
          Reads the contents of settings and stores it.
 Runnable readSettings(ModeSettings<H,?> settings, UndoableModeSettings pending)
          Reads the contents of settings, creates new entries if either createEntryDuringRead(String) or if pending allows the setting to be undone if not needed.
protected  void rebuild(Dockable dockable)
          Rebuilds the action sources of dockable.
protected  void rebuildAll()
          Rebuilds the actions sources for all Dockables.
 void reduceToEmpty(Dockable dockable)
          Removes dockable itself, put the properties of dockable remain in the system.
 void refresh()
          Updates the modes of all Dockables that are registered at this ModeManager.
 void refresh(Dockable dockable, boolean recursive)
          Updates the mode of dockable and updates the actions associated with dockable.
 void remove(Dockable dockable)
          Removes the properties that belong to dockable.
 void removeEmpty(String name)
          Removes the entry for name but only if the entry is not associated with any Dockable.
 void removeMode(M mode)
          Removes mode from this manager.
 void removeModeManagerListener(ModeManagerListener<? super H,? super M> listener)
          Removes listener from this manager.
 void runTransaction(AffectingRunnable runnable)
          Runs an algorithm which affects the mode of some Dockables.
 void runTransaction(AffectingRunnable run, boolean continuous)
          Runs an algorithm which affects the mode of some Dockables.
 void runTransaction(Runnable run)
          Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.
 void runTransaction(Runnable run, boolean continuous)
          Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.
 void setHistoryRewriter(HistoryRewriter<H,M> historyRewriter)
          Sets the current HistoryRewriter.
protected  void setProperties(M mode, Dockable dockable, H property)
          Stores a property for dockable if in mode mode.
 void store(Dockable dockable)
          Stores the current location of dockable and all its children in respect to their current Mode.
protected  void store(M mode, Dockable dockable)
          Stores the location of dockable under the key mode.
This method does nothing if isOnContinuous() returns true
 String toString()
           
 void writeSettings(ModeSettings<H,?> setting)
          Writes all the information stored in this ModeManager to setting.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ModeManager

public ModeManager(DockController controller)
Creates a new manager.

Parameters:
controller - the controller in whose realm this manager will work
Method Detail

destroy

public void destroy()
Unregisters listeners which this manager added to the DockController and other components.


getController

public DockController getController()
Gets the controller in whose realm this manager works.

Returns:
the controller

addModeManagerListener

public void addModeManagerListener(ModeManagerListener<? super H,? super M> listener)
Adds a listener to this manager, the listener will be informed about changes in this manager.

Parameters:
listener - the new listener, not null

removeModeManagerListener

public void removeModeManagerListener(ModeManagerListener<? super H,? super M> listener)
Removes listener from this manager.

Parameters:
listener - the listener to remove

putMode

public void putMode(M mode)
Puts a new mode in this manager. If there is already a mode with the same id registered, then the old mode gets replaced by the new one.

Parameters:
mode - the new mode

putFactory

public void putFactory(ModeSettingFactory<H> factory)
Adds a factory to this ModeManager. The factory will be used by the ModeSettings to read and write data of the mode with the same identifier as factory persistently.
Note: A Mode might also provide a ModeSettingFactory, if there is a collision of unique identifiers the factory of the mode is used.

Parameters:
factory - the new factory

getFactories

public Collection<ModeSettingFactory<H>> getFactories()
Gets a set containing all the ModeSettingFactorys that were added to this manager.

Returns:
the factories

removeMode

public void removeMode(M mode)
Removes mode from this manager. Note that history information about the mode remains.

Parameters:
mode - the mode to remove

getMode

public M getMode(Path path)
Searches and returns the mode with given unique identifier path.

Parameters:
path - some unique identifier
Returns:
the mode with that identifier or null

setHistoryRewriter

public void setHistoryRewriter(HistoryRewriter<H,M> historyRewriter)
Sets the current HistoryRewriter. The rewriter is invoked every time before the apply method of a Mode is called. The rewriter can then change the history of one Dockable, e.g. to apply additional checks whether an old state is still valid.
A history rewriter does not change the history permanently. It creates a new history object before the apply method is called, but that new history object will not be stored by the ModeManager.

Parameters:
historyRewriter - the new rewriter, can be null

getHistoryRewriter

public HistoryRewriter<H,M> getHistoryRewriter()
Gets the current HistoryRewriter.

Returns:
the rewriter, can be null
See Also:
setHistoryRewriter(HistoryRewriter)

listeners

protected ModeManagerListener<? super H,? super M>[] listeners()
Gets all the listeners that are currently registered in this manager.

Returns:
the list of registered listeners

fireAdded

protected void fireAdded(Dockable dockable)
Calls ModeManagerListener.dockableAdded(ModeManager, Dockable) on all listeners that are currently registered

Parameters:
dockable - the new element

fireRemoved

protected void fireRemoved(Dockable dockable)
Calls ModeManagerListener.dockableRemoved(ModeManager, Dockable) on all listeners that are currently registered.

Parameters:
dockable - the removed element

fireModeChanged

protected void fireModeChanged(Dockable dockable,
                               M oldMode,
                               M newMode)
Calls ModeManagerListener.modeChanged(ModeManager, Dockable, Mode, Mode) on all listeners that are currently registered.

Parameters:
dockable - the element whose mode changed
oldMode - its old mode
newMode - its new mode

fireAdded

protected void fireAdded(M mode)
Calls ModeManagerListener.modeAdded(ModeManager, Mode) on all listeners that are currently registered.

Parameters:
mode - the added mode

fireRemoved

protected void fireRemoved(M mode)
Calls ModeManagerListener.modeRemoved(ModeManager, Mode) on all listeners that are currently registered.

Parameters:
mode - the removed mode

add

public void add(String key,
                Dockable dockable)
Registers a new Dockable at this manager. If there is already mode-information for key present, then dockable inherits this information.

Parameters:
key - the unique key of dockable
dockable - the new element
Throws:
NullPointerException - if either key or dockable is null
IllegalArgumentException - if there is already a dockable registered with key

put

public void put(String key,
                Dockable dockable)
Registers a new Dockable at this manager. This method works like add(String, Dockable) but does not throw an exception if another Dockable is already registered with key. Instead the other Dockable is unregistered and docakble inherits its mode-information.

Parameters:
key - the unique identifier of dockable
dockable - some new element
Throws:
NullPointerException - if either key or dockable is null

getKey

public String getKey(Dockable dockable)
Gets the unique identifier which is used for dockable.

Parameters:
dockable - some element
Returns:
the unique identifier or null if dockable is not registered

isRegistered

public boolean isRegistered(Dockable dockable)
Tells whether this ModeManager knows dockable and can handle a call to any of the apply methods.

Parameters:
dockable - the element to check
Returns:
true if the element is known, false otherwise

listDockables

public Set<Dockable> listDockables()
Returns a set containing all Dockables that are currently registered at this manager.

Returns:
the set of dockables

runTransaction

public void runTransaction(AffectingRunnable runnable)
Runs an algorithm which affects the mode of some Dockables.

Parameters:
runnable - the algorithm, null will be ignored

runTransaction

public void runTransaction(AffectingRunnable run,
                           boolean continuous)
Runs an algorithm which affects the mode of some Dockables.

Parameters:
run - the algorithm, null will be ignored
continuous - if set to true the transaction should run without changing the internal cache storing the position of all Dockables. This can be important if an operation runs an apply method and additional work will change the position of some elements again. Clients should call store(Dockable) afterwards.

runTransaction

public void runTransaction(Runnable run)
Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.

Parameters:
run - the runnable to execute

runTransaction

public void runTransaction(Runnable run,
                           boolean continuous)
Runs run as transaction, the DockRegister is stalled and isOnTransaction() returns true while run runs.

Parameters:
run - the runnable to execute
continuous - if set to true the transaction should run without changing the internal cache storing the position of all Dockables. This can be important if an operation runs an apply method and additional work will change the position of some elements again. Clients should call store(Dockable) afterwards.

apply

public boolean apply(Dockable dockable,
                     Path mode,
                     boolean force)
Alters the mode of dockable to mode. This method just calls apply(Dockable, Mode, boolean).

Parameters:
dockable - the element whose mode is going to be changed
mode - the new mode
force - if true dockable is relocated even if the current mode already is mode
Returns:
true if mode was found, false otherwise
Throws:
IllegalArgumentException - if dockable is null, mode is null or dockable is not registered.

apply

public void apply(Dockable dockable,
                  M mode,
                  boolean force)
Alters the mode of dockable to mode. This method just calls apply(Dockable, Mode, AffectedSet, boolean).

Parameters:
dockable - the element whose mode is going to be changed
mode - the new mode
force - if true dockable is relocated even if the current mode already is mode
Throws:
IllegalArgumentException - if dockable is null, mode is null or dockable is not registered.

apply

public boolean apply(Dockable dockable,
                     Path mode,
                     AffectedSet set,
                     boolean force)
Alters the mode of dockable to mode. This method just calls apply(Dockable, Mode, AffectedSet, boolean).

Parameters:
dockable - the element whose mode is going to be changed
mode - the new mode
set - to store all dockables whose mode might have been changed
force - if true dockable is relocated even if the current mode already is mode
Returns:
true if mode was found, false otherwise
Throws:
IllegalArgumentException - if dockable is null, mode is null, set is null, or dockable is not registered.

apply

public void apply(Dockable dockable,
                  M mode,
                  AffectedSet set,
                  boolean force)
Alters the mode of dockable to mode. This method does nothing if the current mode of dockable already is mode.
After initial checks and reading the history, this method calls apply(Dockable, Mode, Object, AffectedSet).

Parameters:
dockable - the element whose mode is going to be changed
mode - the new mode
set - to store all dockables whose mode might have been changed
force - if true dockable is relocated even if the current mode already is mode
Throws:
IllegalArgumentException - if dockable is null, mode is null, set is null, or dockable is not registered.

getHistory

protected H getHistory(Dockable dockable,
                       Path modeId)
Gets the history of dockable in mode modeId.

Parameters:
dockable - the element whose history is searched
modeId - the identifier of the mode
Returns:
the history information or null if not found

apply

public boolean apply(Dockable dockable,
                     Path mode,
                     H history,
                     AffectedSet set)
Alters the mode of dockable to be mode. This method just calls apply(Dockable, Mode, Object, AffectedSet).

Parameters:
dockable - the element whose mode is changed
mode - the new mode of dockable
history - history information for Mode.apply(Dockable, Object, AffectedSet), can be null
set - to store elements that have changed
Returns:
true if mode was found, false otherwise
Throws:
IllegalArgumentException - if either dockable, mode or set is null

apply

public void apply(Dockable dockable,
                  M mode,
                  H history,
                  AffectedSet set)
Alters the mode of dockable to be mode. This method does not alter the modes of other dockables, notice however that the methods Mode.apply(Dockable, Object, AffectedSet) may trigger additional mode-changes.

Parameters:
dockable - the element whose mode is changed
mode - the new mode of dockable
history - history information for Mode.apply(Dockable, Object, AffectedSet), can be null
set - to store elements that have changed
Throws:
IllegalArgumentException - if either dockable, mode or set is null

setProperties

protected void setProperties(M mode,
                             Dockable dockable,
                             H property)
Stores a property for dockable if in mode mode. This method does not trigger any version of the apply methods.

Parameters:
mode - the mode which is affected
dockable - the dockables whose property is changed
property - the new property, can be null

getProperties

protected H getProperties(M mode,
                          Dockable dockable)
Gets the properties which correspond to dockable and mode.

Parameters:
mode - the first part of the key
dockable - the second part of the key
Returns:
the properties or null

isOnTransaction

public boolean isOnTransaction()
Tells whether this manager is currently changing the Mode of a Dockable.

Returns:
true if a mode is currently working

isOnContinuous

public boolean isOnContinuous()
Tells whether this manager currently runs a continuous transaction. As long as a continuous transaction is running the internal states of this manager do not change.

Returns:
whether a continuous transaction is running

refresh

public void refresh()
Updates the modes of all Dockables that are registered at this ModeManager.


refresh

public void refresh(Dockable dockable,
                    boolean recursive)
Updates the mode of dockable and updates the actions associated with dockable. This method is intended to be called by any code that changes the mode in a way that is not automatically registered by this ModeManager.

Parameters:
dockable - the element whose mode might have changed
recursive - if set, then the children of dockable are refreshed as well.

remove

public void remove(Dockable dockable)
Removes the properties that belong to dockable.

Parameters:
dockable - the element to remove

reduceToEmpty

public void reduceToEmpty(Dockable dockable)
Removes dockable itself, put the properties of dockable remain in the system.

Parameters:
dockable - the element to reduce

applyDuringRead

protected abstract void applyDuringRead(String key,
                                        Path old,
                                        Path current,
                                        Dockable dockable)
Called while reading modes in readSettings(ModeSettings). Subclasses might change the mode according to newMode.

Parameters:
key - the identifier of dockable
old - the mode dockable is currently in
current - the mode dockable is going to be
dockable - the element that changes its mode, might be null

createEntryDuringRead

protected boolean createEntryDuringRead(String key)
Tells whether an entry for a missing Dockable should be created. This will result in a call to addEmpty(String) during readSettings(ModeSettings). The default implementation returns always false.

Parameters:
key - the key for which to create a new entry
Returns:
true if an entry should be created

addEmpty

public void addEmpty(String key)
Adds an empty entry to this manager. The empty entry can be used to store information for a Dockable that has not yet been created. It is helpful if the client intends to load first its properties and create only those Dockables which are visible.
Also an empty entry gets never deleted unless removeEmpty(String) is called.

Parameters:
key - the name of the empty entry
Throws:
NullPointerException - if key is null

removeEmpty

public void removeEmpty(String name)
Removes the entry for name but only if the entry is not associated with any Dockable.

Parameters:
name - the name of the entry which might be empty
Throws:
NullPointerException - if key is null

isEmpty

public boolean isEmpty(String key)
Tells whether information about dockable key gets stored indefinitely or not.

Parameters:
key - the key to check
Returns:
true if the key is never removed automatically false otherwise

getDoubleClickTarget

public Dockable getDoubleClickTarget(Dockable target)
Given some Dockable on which an event was registered, searches a registered dockable that is a child of target or target itself.

Parameters:
target - the target whose registered child is searched
Returns:
target, a child of target, or null

getDefaultMode

protected M getDefaultMode(Dockable dockable)
Gets the default mode of dockable, the mode dockable is in if nothing else is specified. This method checks Mode.isDefaultMode(Dockable) and returns the first Mode where the answer was true.

Parameters:
dockable - some dockable, not null
Returns:
its default mode, must be registered at this ModeManager and not be null

getCurrentMode

public M getCurrentMode(Dockable dockable)
Tries to find the mode dockable is currently in. This method calls Mode.isCurrentMode(Dockable) and returns the first Mode where the answer was true.

Parameters:
dockable - some dockable, not null
Returns:
the current mode or null if not found

getPreviousMode

public M getPreviousMode(Dockable dockable)
Reading the history this method tells which mode dockable was in before the current mode.

Parameters:
dockable - some element
Returns:
the previous mode or null if this information is not available

getModeHistory

public List<M> getModeHistory(Dockable dockable)
Gets the history which modes dockable used in the past. The older entries are at the beginning of the list. The current mode may or may not be included in the list.

Parameters:
dockable - the element whose history is asked
Returns:
the history or an empty list if no history is available

getPropertyHistory

public List<H> getPropertyHistory(Dockable dockable)
Gets the history which properties dockable used in the past. Entries of value null are ignored. The older entries are at the beginning of the list.

Parameters:
dockable - the element whose history is asked
Returns:
the history or an empty list if no history is available

store

public void store(Dockable dockable)
Stores the current location of dockable and all its children in respect to their current Mode. Dockables that are not registered at this manager are ignored.
This method does nothing if isOnContinuous() returns true

Parameters:
dockable - a root of a tree

store

protected void store(M mode,
                     Dockable dockable)
Stores the location of dockable under the key mode.
This method does nothing if isOnContinuous() returns true

Parameters:
mode - the mode dockable is currently in
dockable - the element whose location will be stored

modes

public Iterable<M> modes()
Returns an iteration of all modes that are stored in this manager.

Returns:
the iteration

rebuildAll

protected void rebuildAll()
Rebuilds the actions sources for all Dockables.


rebuild

protected void rebuild(Dockable dockable)
Rebuilds the action sources of dockable.

Parameters:
dockable - the element whose actions are to be updated

getSharedActions

public abstract DockActionSource getSharedActions(DockStation station)
Gets a list of actions that should be shown on station depending on the current children of station. This method is called everytime when either a child is added, removed or selected on station.

Parameters:
station - the station whose actions are asked
Returns:
the actions, can be null

createSettings

public <B> ModeSettings<H,B> createSettings(ModeSettingsConverter<H,B> converter)
Creates a new ModeSetting which is configured to transfer data from this ModeManager to persistent storage or the other way. The new setting contains all the ModeSettingFactorys which are currently known to this manager.

Type Parameters:
B - the intermediate format
Parameters:
converter - conversion tool from this managers meta-data format to the intermediate format.
Returns:
the new empty settings

createModeSettings

public <B> ModeSettings<H,B> createModeSettings(ModeSettingsConverter<H,B> converter)
Creates the empty set of settings for this ModeManager. Subclasses may override this method to use another set of settings. This method does not need to call ModeSettings.addFactory(ModeSettingFactory).

Type Parameters:
B - the intermediate format
Parameters:
converter - converstion tool from this managers meta-data format to the intermediate format.
Returns:
the new empty settings

writeSettings

public void writeSettings(ModeSettings<H,?> setting)
Writes all the information stored in this ModeManager to setting.

Parameters:
setting - the settings to fill

readSettings

public void readSettings(ModeSettings<H,?> settings)
Reads the contents of settings and stores it.

Parameters:
settings - the settings to read

readSettings

public Runnable readSettings(ModeSettings<H,?> settings,
                             UndoableModeSettings pending)
Reads the contents of settings, creates new entries if either createEntryDuringRead(String) or if pending allows the setting to be undone if not needed.

Parameters:
settings - the settings to read
pending - undoable settings, can be null
Returns:
an algorithm that will remove any entry that was created because pending did advise so, null if pending was null

addAffected

public void addAffected(Iterable<Dockable> dockables)
Adds all elements of dockables to the current AffectedSet.

Parameters:
dockables - the elements to add

toString

public String toString()
Overrides:
toString in class Object