bibliothek.gui.dock.station.support
Class PlaceholderList<D,S,P extends PlaceholderListItem<D>>

java.lang.Object
  extended by bibliothek.gui.dock.station.support.PlaceholderList<D,S,P>
Type Parameters:
D - the kind of object that should be treated as Dockable
S - the kind of object that should be treated as DockStation
P - the type of item which represents a Dockable
Direct Known Subclasses:
DockablePlaceholderList, PerspectivePlaceholderList

public abstract class PlaceholderList<D,S,P extends PlaceholderListItem<D>>
extends Object

A list consisting of Dockables and sets of Paths as placeholder. Uses a PlaceholderStrategy to automatically create and dispose of placeholders.
Clients should call bind() and unbind() to manage the lifecycle of this list.
A PlaceholderList is not thread-safe.

Author:
Benjamin Sigg

Nested Class Summary
static interface PlaceholderList.Filter<M>
          A sublist of a PlaceholderList, the elements in this list are filtered by a strategy that is defined by the PlaceholderList.
 class PlaceholderList.Item
          A single item in a PlaceholderList
static class PlaceholderList.Level
          identifiers for the various sublists this list consists of
 
Constructor Summary
PlaceholderList()
          Creates a new and empty list.
PlaceholderList(PlaceholderMap map, PlaceholderListItemConverter<D,P> converter)
          Creates a new list reading all the data that is stored in map.
 
Method Summary
 int baseToLevel(int index, PlaceholderList.Level level)
          Searches the base entry at index and returns its location in sublist level.
 void bind()
          Connects this list with its strategy.
 void clear()
          Clears this list, all entries are removed
 PlaceholderList.Filter<P> dockables()
          Gets a mutable view of all Dockables of this list.
protected abstract  D[] getChildren(S station)
          Gets all the children of station.
 P getDockableAt(Path placeholder)
          Searches the first occurrence of placeholder and returns the Dockable that is stored at that location.
 int getDockableIndex(Path placeholder)
          Emulates the insertion of a Dockable at location placeholder and returns the index that the inserted dockable would have in the dockable-list.
 int getListIndex(Path placeholder)
          Searches the first occurance of placeholder in a placeholder-set and returns the index of that entry on the BASE level.
 PlaceholderMap getMap(Path placeholder)
          Gets the PlaceholderMap that was used for a station at location placeholder.
 PlaceholderMetaMap getMetaMap(Path placeholder)
          Gets the meta-map that is associated with the set of placeholders that include placeholder.
protected abstract  Path getPlaceholder(D dockable)
          Gets the placeholder which matches dockable.
protected abstract  PlaceholderMap getPlaceholders(S station)
          Gets all the placeholders that are used by station.
 PlaceholderStrategy getStrategy()
          Gets the current strategy of this list.
 boolean hasPlaceholder(Path placeholder)
          Tells whether this list contains a reference to placeholder.
 void insertAllPlaceholders()
          Inserts a placeholder for all Dockables that are stored in this list.
 int levelToBase(int index, PlaceholderList.Level level)
          Searches the base entry at index in the sublist level and returns its location in the base list.
 PlaceholderList.Filter<PlaceholderList.Item> list()
          Gets a mutable view of all elements of this list.
 PlaceholderList.Filter<Set<Path>> listPlaceholders()
          Gets a mutable view of all elements of this list.
 PlaceholderList.Filter<Set<Path>> purePlaceholders()
          Gets a mutable view of all pure placeholders of this list.
 int put(Path placeholder, P dockable)
          Searches for the first occurrence of placeholder and replaces it with dockable.
 boolean put(P dockable, Path placeholder)
          Searches for the entry containing dockable and adds placeholder to the placeholder set.
 void read(PlaceholderMap map, PlaceholderListItemConverter<D,P> converter)
          Reads the contents of map and adds them at the end of this list.
protected  void read(PlaceholderMap map, PlaceholderListItemConverter<D,P> converter, boolean simulate)
          Reads the contenst of map.
 Path remove(int index)
          Removes the index'th Dockable from this list were index is an index used in dockables().
 Path remove(P dockable)
          Searches for dockable and replaces it by a placeholder.
 void removeAll(Path placeholder)
          Checks all entries of this list and removes all occurrences of all placeholder.
 void removeAll(Set<Path> placeholders)
          Checks all entries of this list and removes all occurrences of all paths stored in placeholders.
protected abstract  void setPlaceholders(S station, PlaceholderMap map)
          Sets all the placeholders that should be used by station.
 void setStrategy(PlaceholderStrategy strategy)
          Sets the new strategy of this list.
 int size(PlaceholderList.Level level)
          Gets the number of entries in the level level.
 PlaceholderMap toMap(PlaceholderListItemConverter<?,? super P> converter)
          Converts this list into a PlaceholderMap, any remaining Dockable or DockStation will be converted using converter.
protected abstract  S toStation(D dockable)
          Converts dockable to the representation of a DockStation.
 String toString()
           
protected abstract  String toString(D dockable)
          Gets a representation of dockable as string.
 void unbind()
          Disconnects this list from its strategy.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PlaceholderList

public PlaceholderList()
Creates a new and empty list.


PlaceholderList

public PlaceholderList(PlaceholderMap map,
                       PlaceholderListItemConverter<D,P> converter)
Creates a new list reading all the data that is stored in map. This constructor stores all placeholders that are described in map, obsolete placeholders may be deleted as soon as a PlaceholderStrategy is set.

Parameters:
map - the map to read, not null
converter - used to convert items back to dockables, not null
Throws:
IllegalArgumentException - if map was not written by a PlaceholderList
Method Detail

getPlaceholder

protected abstract Path getPlaceholder(D dockable)
Gets the placeholder which matches dockable.

Parameters:
dockable - some random dockable
Returns:
the placeholder for dockable, can be null

toString

protected abstract String toString(D dockable)
Gets a representation of dockable as string.

Parameters:
dockable - some random dockable, not null
Returns:
the text

toStation

protected abstract S toStation(D dockable)
Converts dockable to the representation of a DockStation.

Parameters:
dockable - some random dockable
Returns:
dockable as station, can be null

getPlaceholders

protected abstract PlaceholderMap getPlaceholders(S station)
Gets all the placeholders that are used by station.

Parameters:
station - some random representation of a DockStation
Returns:
the placeholders, can be null

setPlaceholders

protected abstract void setPlaceholders(S station,
                                        PlaceholderMap map)
Sets all the placeholders that should be used by station.

Parameters:
station - a representation of a DockStation
map - the map of placeholders, not null

getChildren

protected abstract D[] getChildren(S station)
Gets all the children of station.

Parameters:
station - some station whose children are searched
Returns:
the children

read

public void read(PlaceholderMap map,
                 PlaceholderListItemConverter<D,P> converter)
Reads the contents of map and adds them at the end of this list.

Parameters:
map - the map to read
converter - used to convert items back to dockables, not null
Throws:
IllegalArgumentException - if the map is in the wrong format

read

protected void read(PlaceholderMap map,
                    PlaceholderListItemConverter<D,P> converter,
                    boolean simulate)
Reads the contenst of map. This method can either add the contents at the end of this list, or just simulate a read. If a read is simulated, then the methods of converter are called just as if this would be an actual read, but in reality no data is changed in this list.

Parameters:
map - the data to read
converter - used to convert items back to dockables, not null
simulate - whether this list should actually be changed or not
Throws:
IllegalArgumentException - if the map is in the wrong format

toMap

public PlaceholderMap toMap(PlaceholderListItemConverter<?,? super P> converter)
Converts this list into a PlaceholderMap, any remaining Dockable or DockStation will be converted using converter.

Parameters:
converter - converter to translate dockables into persistent data, not null
Returns:
the new map, not null

bind

public void bind()
Connects this list with its strategy.


unbind

public void unbind()
Disconnects this list from its strategy.


getStrategy

public PlaceholderStrategy getStrategy()
Gets the current strategy of this list.

Returns:
the current strategy

setStrategy

public void setStrategy(PlaceholderStrategy strategy)
Sets the new strategy of this list. If the strategy is not null, then all current placeholders are checked and the invalid placeholders are removed.

Parameters:
strategy - the new strategy

insertAllPlaceholders

public void insertAllPlaceholders()
Inserts a placeholder for all Dockables that are stored in this list.


dockables

public PlaceholderList.Filter<P> dockables()
Gets a mutable view of all Dockables of this list.

Returns:
the dockables

purePlaceholders

public PlaceholderList.Filter<Set<Path>> purePlaceholders()
Gets a mutable view of all pure placeholders of this list. A pure placeholder is an entry in this list with the dockable set to null.

Returns:
the placeholders

list

public PlaceholderList.Filter<PlaceholderList.Item> list()
Gets a mutable view of all elements of this list.

Returns:
the elements

listPlaceholders

public PlaceholderList.Filter<Set<Path>> listPlaceholders()
Gets a mutable view of all elements of this list.

Returns:
the elements, viewed as placeholders

removeAll

public void removeAll(Set<Path> placeholders)
Checks all entries of this list and removes all occurrences of all paths stored in placeholders. If an entry remains with 0 placeholders and no Dockable it is removed.

Parameters:
placeholders - the placeholders to remove

removeAll

public void removeAll(Path placeholder)
Checks all entries of this list and removes all occurrences of all placeholder. If an entry remains with 0 placeholders and no Dockable it is removed.

Parameters:
placeholder - the placeholder to remove

remove

public Path remove(int index)
Removes the index'th Dockable from this list were index is an index used in dockables().

Parameters:
index - the index of the element to remove
Returns:
the placeholder that replaces the element or null

remove

public Path remove(P dockable)
Searches for dockable and replaces it by a placeholder. If dockable is a DockStation, then its PlaceholderMap is stored.

Parameters:
dockable - the element to remove
Returns:
the placeholder that was inserted, null if the current strategy does not assign a placeholder to dockable or if dockable was not found in this list

put

public int put(Path placeholder,
               P dockable)
Searches for the first occurrence of placeholder and replaces it with dockable. If there is already another dockable stored at that location, then the other dockable is replaced silently. If dockable is a DockStation and a PlaceholderMap is set, then this map is transfered to dockable and removed from this list.
This method also removes all occurrences of placeholder and the placeholder that is assigned by the current PlaceholderStrategy from this list.

Parameters:
placeholder - the placeholder to search, not null
dockable - the element which will replace placeholder, not null
Returns:
the index in dockables() where dockable was inserted or -1 if placeholder was not found

getDockableIndex

public int getDockableIndex(Path placeholder)
Emulates the insertion of a Dockable at location placeholder and returns the index that the inserted dockable would have in the dockable-list.

Parameters:
placeholder - the placeholder of the element to insert
Returns:
the location or -1 if placeholder was not found

getListIndex

public int getListIndex(Path placeholder)
Searches the first occurance of placeholder in a placeholder-set and returns the index of that entry on the BASE level.

Parameters:
placeholder - the placeholder to search
Returns:
its location or -1 if not found

hasPlaceholder

public boolean hasPlaceholder(Path placeholder)
Tells whether this list contains a reference to placeholder.

Parameters:
placeholder - the placeholder to search
Returns:
whether the placeholder was found

put

public boolean put(P dockable,
                   Path placeholder)
Searches for the entry containing dockable and adds placeholder to the placeholder set. This method removes placeholder from all the other entries.

Parameters:
dockable - the key
placeholder - the placeholder to insert
Returns:
true if dockable was found, false otherwise

getDockableAt

public P getDockableAt(Path placeholder)
Searches the first occurrence of placeholder and returns the Dockable that is stored at that location.

Parameters:
placeholder - the placeholder to search
Returns:
either the dockable or null if there is no dockable stored or placeholder is not found

getMetaMap

public PlaceholderMetaMap getMetaMap(Path placeholder)
Gets the meta-map that is associated with the set of placeholders that include placeholder.

Parameters:
placeholder - some placeholder to search
Returns:
the meta map of the group containing placeholder, can be null

getMap

public PlaceholderMap getMap(Path placeholder)
Gets the PlaceholderMap that was used for a station at location placeholder.

Parameters:
placeholder - some placeholder to search
Returns:
the PlaceholderMap that was stored at the place where placeholder was found, can be null

size

public int size(PlaceholderList.Level level)
Gets the number of entries in the level level.

Parameters:
level - some level to count
Returns:
the size of that level

baseToLevel

public int baseToLevel(int index,
                       PlaceholderList.Level level)
Searches the base entry at index and returns its location in sublist level.

Parameters:
index - the index of some entry
level - the sublist
Returns:
the index in the sublist or -1 if the entry is not part of level
Throws:
IndexOutOfBoundsException - if index is illegal

levelToBase

public int levelToBase(int index,
                       PlaceholderList.Level level)
Searches the base entry at index in the sublist level and returns its location in the base list.

Parameters:
index - the index of some entry
level - the sublist
Returns:
the index in the base list
Throws:
IndexOutOfBoundsException - if index is illegal

clear

public void clear()
Clears this list, all entries are removed


toString

public String toString()
Overrides:
toString in class Object