public class DockSituation
extends java.lang.Object
DockSituation
is a converter: the relationship of DockStation
s and Dockable
s,
the position of Dockable
s and other information are converted into a
stream of bytes. The other direction, read a stream and create Dockable
s and DockStation
s, is also possible.Modifier and Type | Field and Description |
---|---|
static Path |
ADJACENT_DOCK_FACTORY_EXTENSION
Name for an
ExtensionName to load additional AdjacentDockFactory s |
static Path |
DOCK_FACTORY_EXTENSION
Name for an
ExtensionName to load additional DockFactory s |
static java.lang.String |
EXTENSION_PARAM
Name of a parameter of an
ExtensionName pointing to this |
Constructor and Description |
---|
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 . |
Modifier and Type | Method and Description |
---|---|
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. |
java.lang.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 . |
java.lang.String |
convertFactoryId(java.lang.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
DockLayoutInfo s 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)
|
AdjacentDockFactory<?> |
getAdjacentFactory(java.lang.String id)
Gets the adjacent factory which has the given
id . |
protected java.lang.String |
getAdjacentFactoryID(java.lang.String id)
Transforms an id read from a stream to the id of the adjacent factory which
would be used.
|
java.util.Map<java.lang.String,AdjacentDockFactory<?>> |
getAdjacentFactorys()
Gets all the adjacent factories that are currently registered at this
DockSituation ,
the returned Map is unmodifiable. |
protected java.lang.String |
getAdjacentID(AdjacentDockFactory<?> factory)
Gets the id of
factory . |
DockFactory<? extends DockElement,?,?> |
getFactory(java.lang.String id)
Gets the factory which has the given
id . |
protected java.lang.String |
getFactoryID(DockLayoutInfo info)
Reads the id of the factory which was used to create
info . |
protected java.lang.String |
getFactoryID(java.lang.String id)
Transforms an id read from a stream to the id of the factory which
would be used.
|
protected java.lang.String |
getID(DockElement element)
Gets the id of the factory which is needed to write (and later
read)
element |
protected java.lang.String |
getID(DockFactory<?,?,?> factory)
Gets the id of
factory . |
protected java.lang.String |
getID(PerspectiveElement element)
Gets the id of the factory which is needed to write (and later
read)
element |
java.lang.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.
|
java.util.Map<java.lang.String,DockStation> |
read(byte[] data)
Reads
data as stream and returns the roots of the
DockElements which were found. |
java.util.Map<java.lang.String,DockStation> |
read(java.io.DataInputStream in)
Reads
in and returns the roots of the
DockElements which were found. |
DockLayoutComposition |
readComposition(java.io.DataInputStream in)
Reads one
DockLayoutComposition and all its children. |
java.util.Map<java.lang.String,DockLayoutComposition> |
readCompositions(java.io.DataInputStream in)
Reads
in and returns the map of DockLayoutComposition s that was
stored. |
java.util.Map<java.lang.String,DockLayoutComposition> |
readCompositionsXML(XElement root)
Reads a set of
DockLayoutComposition s that were stored earlier. |
DockLayoutComposition |
readCompositionXML(XElement element)
Reads a
DockLayoutComposition from an xml element. |
java.util.Map<java.lang.String,DockStation> |
readXML(XElement root)
Reads a set of
DockStation s 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(java.util.Map<java.lang.String,DockStation> stations)
Writes all locations and relationships of the
DockStations
stations and their children into an array of bytes. |
void |
write(java.util.Map<java.lang.String,DockStation> stations,
java.io.DataOutputStream out)
Writes all locations and relationships of the
DockStations
stations and their children into the stream out . |
void |
writeComposition(DockLayoutComposition composition,
java.io.DataOutputStream out)
Writes the contents of
composition and all its children
to out . |
void |
writeCompositions(java.util.Map<java.lang.String,DockLayoutComposition> stations,
java.io.DataOutputStream out)
Writes all information stored in
stations to out . |
void |
writeCompositionsXML(java.util.Map<java.lang.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(java.util.Map<java.lang.String,DockStation> stations,
XElement element)
Writes all locations and relationships of the
DockStation s
stations and their children as xml. |
public static final Path DOCK_FACTORY_EXTENSION
ExtensionName
to load additional DockFactory
spublic static final Path ADJACENT_DOCK_FACTORY_EXTENSION
ExtensionName
to load additional AdjacentDockFactory
spublic static final java.lang.String EXTENSION_PARAM
ExtensionName
pointing to this
public DockSituation(DockFactory<?,?,?>... factories)
DockElements
. Please note that this
constructor does not add the default factories, hence it should be used with care.factories
- the factoriespublic DockSituation(DockController controller)
DefaultDockable
,
SplitDockStation
, StackDockStation
and
FlapDockStation
will be preinstalled.controller
- DockController
in whose realm this DockSituation
will be used, the
controller is used to access the ExtensionManager
and load additional factoriespublic Perspective createPerspective()
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
.Perspective
s that need the client to make additional settings before
it can be used.public void setIgnore(DockSituationIgnore ignore)
ignore
- the filter or null
public DockSituationIgnore getIgnore()
null
public void setPlaceholderStrategy(PlaceholderStrategy placeholders)
placeholders
- the strategy, null
for keeping all placeholderspublic PlaceholderStrategy getPlaceholderStrategy()
null
public void setIntermediatePlaceholders(PlaceholderStrategy intermediatePlaceholders)
intermediatePlaceholders
- the strategy, can be null
public PlaceholderStrategy getIntermediatePlaceholders()
null
protected Path getPlaceholder(DockElement element)
element
using the current PlaceholderStrategy
.element
- some element, not null
null
public void add(DockFactory<?,?,?> factory)
factory
- the additional factorypublic void addAdjacent(AdjacentDockFactory<?> factory)
factory
- the new factorypublic void setMissingFactory(MissingDockFactory missingFactory)
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.missingFactory
- the factory, can be null
public MissingDockFactory getMissingFactory()
null
setMissingFactory(MissingDockFactory)
public void setMissingAdjacentFactory(MissingDockFactory missingAdjacent)
AdjacentDockFactory
is missing.
There are the same issues with this factory than with the one used
by setMissingFactory(MissingDockFactory)
.missingAdjacent
- the new factory, can be null
setMissingFactory(MissingDockFactory)
public MissingDockFactory getMissingAdjacentFactory()
AdjacentDockFactory
is missing.null
setMissingAdjacentFactory(MissingDockFactory)
public DockLayoutComposition convert(DockElement element)
element
and all its children into a
DockLayoutComposition
.element
- the element to convertnull
if the element is ignoredjava.lang.IllegalArgumentException
- if one element has an unknown id of
a DockFactory
.java.lang.ClassCastException
- if an element does not specify the correct
DockFactory
.public DockElement convert(DockLayoutComposition composition)
composition
and tries to create a
DockElement
that matches the composition.composition
- the composition to analyzeDockElement
if the factory for composition
was not foundpublic void writeComposition(DockLayoutComposition composition, java.io.DataOutputStream out) throws java.io.IOException
composition
and all its children
to out
.composition
- the composition to write, should be created by
this
DockSituation
or a DockSituation
with
similar properties.out
- the stream to write intojava.io.IOException
- if an I/O-error occurspublic DockLayoutComposition readComposition(java.io.DataInputStream in) throws java.io.IOException
DockLayoutComposition
and all its children.in
- the stream to read fromnull
if the factory was missingjava.io.IOException
- if an I/O-error occurspublic byte[] write(java.util.Map<java.lang.String,DockStation> stations) throws java.io.IOException
DockStations
stations
and their children into an array of bytes.stations
- The stations to store, a call to read(byte[])
would return the same map. Only the roots are needed.java.io.IOException
- if the information can't be writtenpublic void write(java.util.Map<java.lang.String,DockStation> stations, java.io.DataOutputStream out) throws java.io.IOException
DockStations
stations
and their children into the stream out
.stations
- The stations to store, only the roots are needed.out
- the stream to write injava.io.IOException
- if the stream throws an exceptionpublic void writeCompositions(java.util.Map<java.lang.String,DockLayoutComposition> stations, java.io.DataOutputStream out) throws java.io.IOException
stations
to out
.stations
- Representations of the root-stations.out
- the stream to write injava.io.IOException
- if the stream throws an exceptionpublic java.util.Map<java.lang.String,DockStation> read(byte[] data) throws java.io.IOException
data
as stream and returns the roots of the
DockElements
which were found.data
- the array to readjava.io.IOException
- if data
can't be readpublic java.util.Map<java.lang.String,DockStation> read(java.io.DataInputStream in) throws java.io.IOException
in
and returns the roots of the
DockElements
which were found.in
- the stream to readjava.io.IOException
- if the stream can't be readpublic java.util.Map<java.lang.String,DockLayoutComposition> readCompositions(java.io.DataInputStream in) throws java.io.IOException
in
and returns the map of DockLayoutComposition
s that was
stored.in
- the stream to read fromjava.io.IOException
- if an I/O-error occurspublic void writeCompositionXML(DockLayoutComposition composition, XElement element)
composition
into element
without
changing the attributes of element
.composition
- the composition to writeelement
- the element to write intojava.lang.IllegalArgumentException
- if a factory is missingpublic DockLayoutComposition readCompositionXML(XElement element)
DockLayoutComposition
from an xml element.element
- the element to readXException
- if something is missing or malformed in element
public void writeXML(java.util.Map<java.lang.String,DockStation> stations, XElement element)
DockStation
s
stations
and their children as xml.stations
- The stations to store, only the roots are needed.element
- the element to write into, attributes of element
will
not be changedpublic void writeCompositionsXML(java.util.Map<java.lang.String,DockLayoutComposition> stations, XElement element)
station
into element
.stations
- the items to writeelement
- the element to write into, the attributes of element
will not be changedpublic java.util.Map<java.lang.String,DockStation> readXML(XElement root)
DockStation
s that were stored earlier.root
- the xml element from which to readpublic java.util.Map<java.lang.String,DockLayoutComposition> readCompositionsXML(XElement root)
DockLayoutComposition
s that were stored earlier.root
- the xml element from which to readpublic DockLayoutComposition fillMissing(DockLayoutComposition composition) throws java.io.IOException, XException
DockSituation
, this
method tries to fill gaps in composition
. It checks
all the DockLayoutInfo
s, 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.composition
- the composition to readcomposition
or a new composition if this
method changed somethingjava.io.IOException
- if some stream was opened but cannot be readXException
- if some xml element was found but cannot be readprotected DockLayoutInfo fillMissing(DockLayoutInfo info)
fillMissing(DockLayoutComposition)
only for
DockLayoutInfo
s which contain a DockLayout
. This method
can apply further updates to info
if necessary. The default
implementation just returns info
.DockFactory
s
and use a DockLayout
even for incomplete data.info
- the info to updateinfo
if nothing changed or a new
DockLayoutInfo
if additional information could be retrievedpublic void estimateLocations(DockLayoutComposition composition)
composition
. Invoking this method is the same as calling
guessLocation( composition, composition.getLayout().getLocation() );
.composition
- the composition whose location will be determinedpublic void estimateLocations(DockLayoutComposition composition, DockableProperty location)
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.composition
does not have childrencomposition
does not carry a DockLayout
DockFactory
registered for the factory-id found
in composition
fillMissing(DockLayoutComposition)
before invoking this method.composition
- the composition whose children should be analyzedlocation
- the location of composition
, can be null
protected void estimateLocations(DefaultLocationEstimationMap map)
DockLayoutInfo
s that can
be found in map
.DefaultLocationEstimationMap.finish()
.map
- the root of the tree for which locations need to be estimatedprotected boolean ignoreElement(DockElement element)
DockSituationIgnore
of this situation.element
- the element which might not be savedtrue
if the element should not be savedprotected boolean ignoreChildren(DockStation station)
DockSituationIgnore
of this situation.station
- the station whose children might be ignoredtrue
if the station is saved as having no childrenprotected java.lang.String getID(PerspectiveElement element)
element
element
- the element to readgetID(DockFactory)
,
getFactory(String)
protected java.lang.String getID(DockElement element)
element
element
- the element to readgetID(DockFactory)
,
getFactory(String)
protected java.lang.String getID(DockFactory<?,?,?> factory)
factory
. The default behavior is just to
return DockConverter.getID()
. Note that this method should be
a bijection to getFactory(String)
.factory
- the factory whose id is neededprotected java.lang.String getFactoryID(DockLayoutInfo info)
info
.
This returns the id of the factory as it is used internally by this
DockSituation
.info
- the info to checknull
if info does not contain
datajava.lang.IllegalArgumentException
- if the data of info
is in the wrong formatXException
- if the data of info
is in the wrong formatpublic java.lang.String convertFactoryId(DockFactory<?,?,?> factory)
factory
in the
DockLayoutComposition
.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
.factory
- the factory which might be usedgetID(DockFactory)
public java.lang.String convertFactoryId(java.lang.String id)
DockFactory
has, for which the
identifier id
is used within a DockLayoutComposition
.getFactoryID(String)
, but while
getFactoryID(String)
is intended for internal use, this method
is intended for clients.id
- an identifier found in a DockLayoutComposition
DockFactory
protected java.lang.String getFactoryID(java.lang.String id)
DockFactory factory = ...
factory.getID().equals( getFactoryID( getID( factory )));
id
- the id read from a streamprotected java.lang.String getAdjacentID(AdjacentDockFactory<?> factory)
factory
. The default behavior is just to
return DockConverter.getID()
. Note that this method should be
a bijection to getAdjacentFactory(String)
.factory
- the factory whose id is neededprotected java.lang.String getAdjacentFactoryID(java.lang.String id)
AdjacentDockFactory factory = ...
factory.getID().equals( getFactoryID( getAdjacentID( factory )));
id
- the id read from a stream@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(java.lang.String id)
id
. Note that this
method should be a bijection to getID(DockFactory)
. The
default behavior compares id
with the
getID(DockFactory)
.id
- the name of the factorynull
if no factory has this idpublic AdjacentDockFactory<?> getAdjacentFactory(java.lang.String id)
id
. Note that this
method should be a bijection to getID(DockFactory)
. The
default behavior compares id
with the
getID(DockFactory)
.id
- the name of the factorynull
if no factory has this idpublic java.util.Map<java.lang.String,AdjacentDockFactory<?>> getAdjacentFactorys()
DockSituation
,
the returned Map
is unmodifiable.AdjacentDockFactory
s.public java.lang.String getIdentifier(DockLayoutComposition composition)
composition
when it was
stored by a DockSituation
of this type. The default implementation always
returns null
.composition
- some element that was created by this or a similar DockSituation
composition