bibliothek.gui.dock.layout
Class DockSituation

java.lang.Object
  bibliothek.gui.dock.layout.DockSituation

Direct Known Subclasses:

PredefinedDockSituation

public class DockSituation
extends Object

A DockSituation is a converter: the relationship of DockStations and Dockables, the position of Dockables and other information are converted into a stream of bytes. The other direction, read a stream and create Dockables and DockStations, is also possible.

Author:

Benjamin Sigg

Field Summary

static Path	ADJACENT_DOCK_FACTORY_EXTENSION Name for an ExtensionName to load additional AdjacentDockFactorys
static Path	DOCK_FACTORY_EXTENSION Name for an ExtensionName to load additional DockFactorys
static String	EXTENSION_PARAM Name of a parameter of an ExtensionName pointing to this

Constructor Summary

DockSituation(DockController controller)
Constructs a new DockSituation.

DockSituation(DockFactory<?,?,?>... factories)
Constructs a new DockSituation and sets some factories which are used to create new DockElements.

Method Summary

void	add(DockFactory<?,?,?> factory) Adds a factory
void	addAdjacent(AdjacentDockFactory<?> factory) Adds an adjacent factory
DockLayoutComposition	convert(DockElement element) Converts the layout of element and all its children into a DockLayoutComposition.
DockElement	convert(DockLayoutComposition composition) Reads the contents of composition and tries to create a DockElement that matches the composition.
String	convertFactoryId(DockFactory<?,?,?> factory) Tells what identifier is used for factory in the DockLayoutComposition. This method just calls getID(DockFactory), but getID(DockFactory) is intended for internal use while this method is intended to be used by clients which read out a DockLayoutComposition.
String	convertFactoryId(String id) Tells what identifier the DockFactory has, for which the identifier id is used within a DockLayoutComposition. This method just calls getFactoryID(String), but while getFactoryID(String) is intended for internal use, this method is intended for clients.
Perspective	createPerspective() Creates a new Perspective that uses the settings made on this DockSituation.
protected void	estimateLocations(DefaultLocationEstimationMap map) Recursively tries to estimate the locations of all DockLayoutInfos that can be found in map. Note: this method does not call DefaultLocationEstimationMap.finish().
void	estimateLocations(DockLayoutComposition composition) Tries to guess the location of the elements stored in the tree below composition.
void	estimateLocations(DockLayoutComposition composition, DockableProperty location) Tries to guess the location of the elements stored in the tree below composition, assuming that composition itself is at location location.
DockLayoutComposition	fillMissing(DockLayoutComposition composition) Using the factories currently known to this DockSituation, this method tries to fill gaps in composition.
protected DockLayoutInfo	fillMissing(DockLayoutInfo info) Called by fillMissing(DockLayoutComposition) only for DockLayoutInfos which contain a DockLayout.
AdjacentDockFactory<?>	getAdjacentFactory(String id) Gets the adjacent factory which has the given id.
protected String	getAdjacentFactoryID(String id) Transforms an id read from a stream to the id of the adjacent factory which would be used.
Map<String,AdjacentDockFactory<?>>	getAdjacentFactorys() Gets all the adjacent factories that are currently registered at this DockSituation, the returned Map is unmodifiable.
protected String	getAdjacentID(AdjacentDockFactory<?> factory) Gets the id of factory.
DockFactory<? extends DockElement,?,?>	getFactory(String id) Gets the factory which has the given id.
protected String	getFactoryID(DockLayoutInfo info) Reads the id of the factory which was used to create info.
protected String	getFactoryID(String id) Transforms an id read from a stream to the id of the factory which would be used.
protected String	getID(DockElement element) Gets the id of the factory which is needed to write (and later read) element
protected String	getID(DockFactory<?,?,?> factory) Gets the id of factory.
protected String	getID(PerspectiveElement element) Gets the id of the factory which is needed to write (and later read) element
String	getIdentifier(DockLayoutComposition composition) Tells what identifier was associated with composition when it was stored by a DockSituation of this type.
DockSituationIgnore	getIgnore() Gets the filter which decides, which elements are stored.
PlaceholderStrategy	getIntermediatePlaceholders() Gets the strategy for deleting invalid placeholders in the intermediate format.
MissingDockFactory	getMissingAdjacentFactory() Gets the factory which is used when another AdjacentDockFactory is missing.
MissingDockFactory	getMissingFactory() Gets the factory which is used when another factory is missing.
protected Path	getPlaceholder(DockElement element) Gets a placeholder for element using the current PlaceholderStrategy.
PlaceholderStrategy	getPlaceholderStrategy() Gets the current strategy for removing invalid placeholders.
protected boolean	ignoreChildren(DockStation station) Tells whether to ignore the children of the station when saving or not.
protected boolean	ignoreElement(DockElement element) Tells whether to ignore this element when saving.
Map<String,DockStation>	read(byte[] data) Reads data as stream and returns the roots of the DockElements which were found.
Map<String,DockStation>	read(DataInputStream in) Reads in and returns the roots of the DockElements which were found.
DockLayoutComposition	readComposition(DataInputStream in) Reads one DockLayoutComposition and all its children.
Map<String,DockLayoutComposition>	readCompositions(DataInputStream in) Reads in and returns the map of DockLayoutCompositions that was stored.
Map<String,DockLayoutComposition>	readCompositionsXML(XElement root) Reads a set of DockLayoutCompositions that were stored earlier.
DockLayoutComposition	readCompositionXML(XElement element) Reads a DockLayoutComposition from an xml element.
Map<String,DockStation>	readXML(XElement root) Reads a set of DockStations that were stored earlier.
void	setIgnore(DockSituationIgnore ignore) Sets a filter which decides, which elements (stations and dockables) are stored.
void	setIntermediatePlaceholders(PlaceholderStrategy intermediatePlaceholders) Sets the strategy for deleting invalid placeholders in the intermediate format
void	setMissingAdjacentFactory(MissingDockFactory missingAdjacent) Sets a factory which is used when a AdjacentDockFactory is missing.
void	setMissingFactory(MissingDockFactory missingFactory) Sets a factory which is used whenever no ordinary DockFactory can be found to read something.
void	setPlaceholderStrategy(PlaceholderStrategy placeholders) Sets a strategy for deleting invalid placeholders.
byte[]	write(Map<String,DockStation> stations) Writes all locations and relationships of the DockStations stations and their children into an array of bytes.
void	write(Map<String,DockStation> stations, DataOutputStream out) Writes all locations and relationships of the DockStations stations and their children into the stream out.
void	writeComposition(DockLayoutComposition composition, DataOutputStream out) Writes the contents of composition and all its children to out.
void	writeCompositions(Map<String,DockLayoutComposition> stations, DataOutputStream out) Writes all information stored in stations to out.
void	writeCompositionsXML(Map<String,DockLayoutComposition> stations, XElement element) Writes the contents of station into element.
void	writeCompositionXML(DockLayoutComposition composition, XElement element) Writes the contents of composition into element without changing the attributes of element.
void	writeXML(Map<String,DockStation> stations, XElement element) Writes all locations and relationships of the DockStations stations and their children as xml.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DOCK_FACTORY_EXTENSION

public static final Path DOCK_FACTORY_EXTENSION

Name for an ExtensionName to load additional DockFactorys

ADJACENT_DOCK_FACTORY_EXTENSION

public static final Path ADJACENT_DOCK_FACTORY_EXTENSION

Name for an ExtensionName to load additional AdjacentDockFactorys

EXTENSION_PARAM

public static final String EXTENSION_PARAM

Name of a parameter of an ExtensionName pointing to this

See Also:

Constant Field Values

Constructor Detail

DockSituation

public DockSituation(DockFactory<?,?,?>... factories)

Constructs a new DockSituation and sets some factories which are used to create new DockElements. Please note that this constructor does not add the default factories, hence it should be used with care.

Parameters:

factories - the factories

DockSituation

public DockSituation(DockController controller)

Constructs a new DockSituation. Factories for DefaultDockable, SplitDockStation, StackDockStation and FlapDockStation will be preinstalled.

Parameters:

controller - DockController in whose realm this DockSituation will be used, the controller is used to access the ExtensionManager and load additional factories

Method Detail

createPerspective

public Perspective createPerspective()

Creates a new Perspective that uses the settings made on this DockSituation. Changes on the properties of this DockSituation will be noticed and used by the created Perspective. However changes on the properties of the Perspective will not influence this DockSituation.
Note that subclasses may create Perspectives that need the client to make additional settings before it can be used.

Returns:

the new perspective

setIgnore

public void setIgnore(DockSituationIgnore ignore)

Sets a filter which decides, which elements (stations and dockables) are stored.

Parameters:

ignore - the filter or null

getIgnore

public DockSituationIgnore getIgnore()

Gets the filter which decides, which elements are stored.

Returns:

the filter or null

setPlaceholderStrategy

public void setPlaceholderStrategy(PlaceholderStrategy placeholders)

Sets a strategy for deleting invalid placeholders.

Parameters:

placeholders - the strategy, null for keeping all placeholders

getPlaceholderStrategy

public PlaceholderStrategy getPlaceholderStrategy()

Gets the current strategy for removing invalid placeholders.

Returns:

the strategy, may be null

setIntermediatePlaceholders

public void setIntermediatePlaceholders(PlaceholderStrategy intermediatePlaceholders)

Sets the strategy for deleting invalid placeholders in the intermediate format

Parameters:

intermediatePlaceholders - the strategy, can be null

getIntermediatePlaceholders

public PlaceholderStrategy getIntermediatePlaceholders()

Gets the strategy for deleting invalid placeholders in the intermediate format.

Returns:

the intermediate strategy, can be null

getPlaceholder

protected Path getPlaceholder(DockElement element)

Gets a placeholder for element using the current PlaceholderStrategy.

Parameters:

element - some element, not null

Returns:

the placeholder, can be null

add

public void add(DockFactory<?,?,?> factory)

Adds a factory

Parameters:

factory - the additional factory

addAdjacent

public void addAdjacent(AdjacentDockFactory<?> factory)

Adds an adjacent factory

Parameters:

factory - the new factory

setMissingFactory

public void setMissingFactory(MissingDockFactory missingFactory)

Sets a factory which is used whenever no ordinary DockFactory can be found to read something. The missingFactory can convert the input to any Object it likes, but if a missing factory is later added to this situation, then that object needs to be casted into the object used by the original factory. So when working with a MissingDockFactory handling different types of layout-data needs to be done very carefully. Note that this factory is only used to convert byte-stream or xml data to the intermediate format. It cannot create any Dockable or DockElement nor store any data.

Parameters:

missingFactory - the factory, can be null

getMissingFactory

public MissingDockFactory getMissingFactory()

Gets the factory which is used when another factory is missing.

Returns:

the factory replacing missing factories, can be null

See Also:

setMissingFactory(MissingDockFactory)

setMissingAdjacentFactory

public void setMissingAdjacentFactory(MissingDockFactory missingAdjacent)

Sets a factory which is used when a AdjacentDockFactory is missing. There are the same issues with this factory than with the one used by setMissingFactory(MissingDockFactory).

Parameters:

missingAdjacent - the new factory, can be null

See Also:

setMissingFactory(MissingDockFactory)

getMissingAdjacentFactory

public MissingDockFactory getMissingAdjacentFactory()

Gets the factory which is used when another AdjacentDockFactory is missing.

Returns:

the factory, can be null

See Also:

setMissingAdjacentFactory(MissingDockFactory)

convert

public DockLayoutComposition convert(DockElement element)

Converts the layout of element and all its children into a DockLayoutComposition.

Parameters:

element - the element to convert

Returns:

the composition or null if the element is ignored

Throws:

IllegalArgumentException - if one element has an unknown id of a DockFactory.

ClassCastException - if an element does not specify the correct DockFactory.

convert

public DockElement convert(DockLayoutComposition composition)

Reads the contents of composition and tries to create a DockElement that matches the composition.

Parameters:

composition - the composition to analyze

Returns:

the new element, can be something else then a DockElement if the factory for composition was not found

writeComposition

public void writeComposition(DockLayoutComposition composition,
                             DataOutputStream out)
                      throws IOException

Writes the contents of composition and all its children to out.

Parameters:

composition - the composition to write, should be created by this DockSituation or a DockSituation with similar properties.

out - the stream to write into

Throws:

IOException - if an I/O-error occurs

readComposition

public DockLayoutComposition readComposition(DataInputStream in)
                                      throws IOException

Reads one DockLayoutComposition and all its children.

Parameters:

in - the stream to read from

Returns:

the new composition or null if the factory was missing

Throws:

IOException - if an I/O-error occurs

write

public byte[] write(Map<String,DockStation> stations)
             throws IOException

Writes all locations and relationships of the DockStations stations and their children into an array of bytes.

Parameters:

stations - The stations to store, a call to read(byte[]) would return the same map. Only the roots are needed.

Returns:

the information as an array of bytes

Throws:

IOException - if the information can't be written

write

public void write(Map<String,DockStation> stations,
                  DataOutputStream out)
           throws IOException

Writes all locations and relationships of the DockStations stations and their children into the stream out.

Parameters:

stations - The stations to store, only the roots are needed.

out - the stream to write in

Throws:

IOException - if the stream throws an exception

writeCompositions

public void writeCompositions(Map<String,DockLayoutComposition> stations,
                              DataOutputStream out)
                       throws IOException

Writes all information stored in stations to out.

Parameters:

stations - Representations of the root-stations.

out - the stream to write in

Throws:

IOException - if the stream throws an exception

read

public Map<String,DockStation> read(byte[] data)
                             throws IOException

Reads data as stream and returns the roots of the DockElements which were found.

Parameters:

data - the array to read

Returns:

the root stations which were found

Throws:

IOException - if data can't be read

read

public Map<String,DockStation> read(DataInputStream in)
                             throws IOException

Reads in and returns the roots of the DockElements which were found.

Parameters:

in - the stream to read

Returns:

the roots of all elements that were found

Throws:

IOException - if the stream can't be read

readCompositions

public Map<String,DockLayoutComposition> readCompositions(DataInputStream in)
                                                   throws IOException

Reads in and returns the map of DockLayoutCompositions that was stored.

Parameters:

in - the stream to read from

Returns:

the roots of the layout

Throws:

IOException - if an I/O-error occurs

writeCompositionXML

public void writeCompositionXML(DockLayoutComposition composition,
                                XElement element)

Writes the contents of composition into element without changing the attributes of element.

Parameters:

composition - the composition to write

element - the element to write into

Throws:

IllegalArgumentException - if a factory is missing

readCompositionXML

public DockLayoutComposition readCompositionXML(XElement element)

Reads a DockLayoutComposition from an xml element.

Parameters:

element - the element to read

Returns:

the composition that was read

Throws:

XException - if something is missing or malformed in element

writeXML

public void writeXML(Map<String,DockStation> stations,
                     XElement element)

Writes all locations and relationships of the DockStations stations and their children as xml.

Parameters:

stations - The stations to store, only the roots are needed.

element - the element to write into, attributes of element will not be changed

writeCompositionsXML

public void writeCompositionsXML(Map<String,DockLayoutComposition> stations,
                                 XElement element)

Writes the contents of station into element.

Parameters:

stations - the items to write

element - the element to write into, the attributes of element will not be changed

readXML

public Map<String,DockStation> readXML(XElement root)

Reads a set of DockStations that were stored earlier.

Parameters:

root - the xml element from which to read

Returns:

the set of station

readCompositionsXML

public Map<String,DockLayoutComposition> readCompositionsXML(XElement root)

Reads a set of DockLayoutCompositions that were stored earlier.

Parameters:

root - the xml element from which to read

Returns:

the set of compositions

fillMissing

public DockLayoutComposition fillMissing(DockLayoutComposition composition)
                                  throws IOException,
                                         XException

Using the factories currently known to this DockSituation, this method tries to fill gaps in composition. It checks all the DockLayoutInfos, if an info contains a byte array or an XElement, then this method tries to use a factory to read the element. If a missing factory is present, then this factory is used as well.

Parameters:

composition - the composition to read

Returns:

either composition or a new composition if this method changed something

Throws:

IOException - if some stream was opened but cannot be read

XException - if some xml element was found but cannot be read

fillMissing

protected DockLayoutInfo fillMissing(DockLayoutInfo info)

Called by fillMissing(DockLayoutComposition) only for DockLayoutInfos which contain a DockLayout. This method can apply further updates to info if necessary. The default implementation just returns info.
This method is intended for subclasses which wrap DockFactorys and use a DockLayout even for incomplete data.

Parameters:

info - the info to update

Returns:

either info if nothing changed or a new DockLayoutInfo if additional information could be retrieved

estimateLocations

public void estimateLocations(DockLayoutComposition composition)

Tries to guess the location of the elements stored in the tree below composition. Invoking this method is the same as calling guessLocation( composition, composition.getLayout().getLocation() );.

Parameters:

composition - the composition whose location will be determined

estimateLocations

public void estimateLocations(DockLayoutComposition composition,
                              DockableProperty location)

Tries to guess the location of the elements stored in the tree below composition, assuming that composition itself is at location location. This method reads out the DockLayoutInfo through DockLayoutComposition.getLayout() and then calls DockLayoutInfo.setLocation(DockableProperty), so composition gets modified by this method. This method stops its recursion if the location of a child of composition was not found.
This method returns immediately if one of:

• composition does not have children
• composition does not carry a DockLayout
• There is no DockFactory registered for the factory-id found in composition

Note: if the number of factories changed, then it might be a good idea to call fillMissing(DockLayoutComposition) before invoking this method.

Parameters:

composition - the composition whose children should be analyzed

location - the location of composition, can be null

estimateLocations

protected void estimateLocations(DefaultLocationEstimationMap map)

Recursively tries to estimate the locations of all DockLayoutInfos that can be found in map.
Note: this method does not call DefaultLocationEstimationMap.finish().

Parameters:

map - the root of the tree for which locations need to be estimated

ignoreElement

protected boolean ignoreElement(DockElement element)

Tells whether to ignore this element when saving. If an element is ignored, no factory is needed for it. This implementation forwards the call to the DockSituationIgnore of this situation.

Parameters:

element - the element which might not be saved

Returns:

true if the element should not be saved

ignoreChildren

protected boolean ignoreChildren(DockStation station)

Tells whether to ignore the children of the station when saving or not. If the children are ignored, no factories are needed for them. This implementation forwards the call to the DockSituationIgnore of this situation.

Parameters:

station - the station whose children might be ignored

Returns:

true if the station is saved as having no children

getID

protected String getID(PerspectiveElement element)

Gets the id of the factory which is needed to write (and later read) element

Parameters:

element - the element to read

Returns:

the id of the factory

See Also:

getID(DockFactory), getFactory(String)

getID

protected String getID(DockElement element)

Gets the id of the factory which is needed to write (and later read) element

Parameters:

element - the element to read

Returns:

the id of the factory

See Also:

getID(DockFactory), getFactory(String)

getID

protected String getID(DockFactory<?,?,?> factory)

Gets the id of factory. The default behavior is just to return DockConverter.getID(). Note that this method should be a bijection to getFactory(String).

Parameters:

factory - the factory whose id is needed

Returns:

the id of the factory

getFactoryID

protected String getFactoryID(DockLayoutInfo info)

Reads the id of the factory which was used to create info. This returns the id of the factory as it is used internally by this DockSituation.

Parameters:

info - the info to check

Returns:

the id of a factory or null if info does not contain data

Throws:

IllegalArgumentException - if the data of info is in the wrong format

XException - if the data of info is in the wrong format

convertFactoryId

public String convertFactoryId(DockFactory<?,?,?> factory)

Tells what identifier is used for factory in the DockLayoutComposition.
This method just calls getID(DockFactory), but getID(DockFactory) is intended for internal use while this method is intended to be used by clients which read out a DockLayoutComposition.

Parameters:

factory - the factory which might be used

Returns:

the identifier

See Also:

getID(DockFactory)

convertFactoryId

public String convertFactoryId(String id)

Tells what identifier the DockFactory has, for which the identifier id is used within a DockLayoutComposition.
This method just calls getFactoryID(String), but while getFactoryID(String) is intended for internal use, this method is intended for clients.

Parameters:

id - an identifier found in a DockLayoutComposition

Returns:

the identifer of a DockFactory

getFactoryID

protected String getFactoryID(String id)

Transforms an id read from a stream to the id of the factory which would be used. This method must fulfill one contract: DockFactory factory = ... factory.getID().equals( getFactoryID( getID( factory )));

Parameters:

id - the id read from a stream

Returns:

the id of the original factory

getAdjacentID

protected String getAdjacentID(AdjacentDockFactory<?> factory)

Gets the id of factory. The default behavior is just to return DockConverter.getID(). Note that this method should be a bijection to getAdjacentFactory(String).

Parameters:

factory - the factory whose id is needed

Returns:

the id of the factory

getAdjacentFactoryID

protected String getAdjacentFactoryID(String id)

Transforms an id read from a stream to the id of the adjacent factory which would be used. This method must fulfill one contract: AdjacentDockFactory factory = ... factory.getID().equals( getFactoryID( getAdjacentID( factory )));

Parameters:

id - the id read from a stream

Returns:

the id of the original factory

getFactory

@Todo(compatibility=BREAK_MINOR,
      priority=MAJOR,
      target=VERSION_1_1_3,
      description="remove the legacy code that filters out identifiers that look like \'secure ...\'. Instead \'result\' can be returned directly.")
public DockFactory<? extends DockElement,?,?> getFactory(String id)

Gets the factory which has the given id. Note that this method should be a bijection to getID(DockFactory). The default behavior compares id with the getID(DockFactory).

Parameters:

id - the name of the factory

Returns:

the factory or null if no factory has this id

getAdjacentFactory

public AdjacentDockFactory<?> getAdjacentFactory(String id)

Gets the adjacent factory which has the given id. Note that this method should be a bijection to getID(DockFactory). The default behavior compares id with the getID(DockFactory).

Parameters:

id - the name of the factory

Returns:

the factory or null if no factory has this id

getAdjacentFactorys

public Map<String,AdjacentDockFactory<?>> getAdjacentFactorys()

Gets all the adjacent factories that are currently registered at this DockSituation, the returned Map is unmodifiable.

Returns:

an unmodifiable map containing all AdjacentDockFactorys.

getIdentifier

public String getIdentifier(DockLayoutComposition composition)

Tells what identifier was associated with composition when it was stored by a DockSituation of this type. The default implementation always returns null.

Parameters:

composition - some element that was created by this or a similar DockSituation

Returns:

the identifier that was associated with composition