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

java.lang.Object
  extended by bibliothek.gui.dock.station.support.PlaceholderList<D>
Type Parameters:
D - the type which represents a Dockable

public class PlaceholderList<D extends PlaceholderListItem>
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)
          Creates a new list reading all the data that is stored in map.
PlaceholderList(PlaceholderMap map, PlaceholderListItemConverter<D> 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.
 PlaceholderList.Filter<D> dockables()
          Gets a mutable view of all Dockables of this list.
 D 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.
 PlaceholderMetaMap getMetaMap(Path placeholder)
          Gets the meta-map that is associated with the set of placeholders that include placeholder.
 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.
 boolean put(D dockable, Path placeholder)
          Searches for the entry containing dockable and adds placeholder to the placeholder set.
 int put(Path placeholder, D dockable)
          Searches for the first occurrence of placeholder and replaces it with dockable.
 void read(PlaceholderMap map, PlaceholderListItemConverter<D> converter)
          Reads the contents of map and adds them at the end of this list.
 Path remove(D dockable)
          Searches for dockable and replaces it by a placeholder.
 Path remove(int index)
          Removes the index'th Dockable from this list were index is an index used in dockables().
 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.
 void setStrategy(PlaceholderStrategy strategy)
          Sets the new strategy of this list.
static
<D extends PlaceholderListItem>
void
simulatedRead(PlaceholderMap map, PlaceholderListItemConverter<D> converter)
          Simulates a call to read(PlaceholderMap, PlaceholderListItemConverter) and makes all calls to converter that would be made in a real read as well.
 PlaceholderMap toMap()
          Converts this list into a PlaceholderMap, any remaining Dockable or DockStation will be converted into its placeholder using the currently installed PlaceholderStrategy.
 PlaceholderMap toMap(PlaceholderListItemConverter<? super D> converter)
          Converts this list into a PlaceholderMap, any remaining Dockable or DockStation will be converted using converter.
 String toString()
           
 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)
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
Throws:
IllegalArgumentException - if map was not written by a PlaceholderList

PlaceholderList

public PlaceholderList(PlaceholderMap map,
                       PlaceholderListItemConverter<D> 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

simulatedRead

public static <D extends PlaceholderListItem> void simulatedRead(PlaceholderMap map,
                                                                 PlaceholderListItemConverter<D> converter)
Simulates a call to read(PlaceholderMap, PlaceholderListItemConverter) and makes all calls to converter that would be made in a real read as well.

Type Parameters:
D - the kind of data converter handles
Parameters:
map - the map to read
converter - used to convert items back to dockables, not null

read

public void read(PlaceholderMap map,
                 PlaceholderListItemConverter<D> 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

toMap

public PlaceholderMap toMap()
Converts this list into a PlaceholderMap, any remaining Dockable or DockStation will be converted into its placeholder using the currently installed PlaceholderStrategy.

Returns:
the new map, not null

toMap

public PlaceholderMap toMap(PlaceholderListItemConverter<? super D> 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<D> 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(D 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,
               D 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

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(D 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 D 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

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

toString

public String toString()
Overrides:
toString in class Object