Package com.luciad.lucy.workspace
Class ALcyWorkspaceObjectCodec
java.lang.Object
com.luciad.lucy.workspace.ALcyWorkspaceObjectCodec
- Direct Known Subclasses:
ALcyWorkspaceObjectCodecWrapper
,TLcyGXYAsynchronousCustomizerPanelWorkspaceCodec
,TLcyGXYAsynchronousLayerWorkspaceCodec
An
ALcyWorkspaceObjectCodec
is responsible for encoding/decoding a specific type of
object. If references need to be stored to an object, an ALcyWorkspaceObjectCodec
for that type of object is required.
E.g. if an addon (e.g. tote) refers some ILcdModel
that was created by some other
addon (e.g. shp decoder addon), and the tote addon wants to store a reference to the
ILcdModel
in the workspace, then the shp decoder addon must have provided a
ALcyWorkspaceObjectCodec
for that type of ILcdModel
, so that the
reference to the model can correctly be (re)stored.
Encoding an object is composed out of two steps:
canEncodeObject
encodeObject
canEncodeObject
is used to check if this ALcyWorkspaceObjectCodec
can encode the given object. Afterwards, encodeObject
is used to do the actual
encoding. These methods should only be invoked by an ALcyWorkspaceCodec
, never
by user code.
Decoding an object is composed out of these two steps:
createObject
decodeObject
createObject
is used to create an instance, afterwards
decodeObject
is used to initialize that object. The decoding of an object is split
into these two methods to be able to deal with circular references. These methods should only be
invoked by an ALcyWorkspaceCodec
, never by user code.
The typical objects for which an ALcyWorkspaceObjectCodec
must be available include
ILcyApplicationPane
s, ILcyMapComponent
s,
ILcdGXYView
s, ILcdGXYLayer
s,
ILcdModel
s, domain objects of ILcdModel
s (e.g. polylines, points, ...)
Instances of ALcyWorkspaceObjectCodec
must be registered with
ALcyWorkspaceCodec
.
If an ALcyWorkspaceCodecDelegate
s needs to encode a path, it is advised to use
ALcyWorkspaceCodec.encodePath(String)
. This, for example, allows implementations of
ALcyWorkspaceCodec
to store paths relative to the location of the workspace file.-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract boolean
canEncodeObject
(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent) This method returns true if the givenObject
can be encoded, false otherwise.abstract Object
createObject
(ALcyWorkspaceCodec aWSCodec, Object aParent, InputStream aIn) This method creates anObject
of the proper class.void
decodeObject
(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, InputStream aIn) This method decodes the properties of anObject
created bycreateObject(ALcyWorkspaceCodec, Object, java.io.InputStream)
from the givenInputStream
.abstract void
encodeObject
(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, OutputStream aOut) This method writes the givenObject
to the givenOutputStream
.abstract String
getUID()
A unique identifier for thisALcyWorkspaceObjectCodec
.
-
Constructor Details
-
ALcyWorkspaceObjectCodec
public ALcyWorkspaceObjectCodec()
-
-
Method Details
-
getUID
A unique identifier for thisALcyWorkspaceObjectCodec
. The UID will be used to make sure that a workspace part that is encoded by aALcyWorkspaceObjectCodec
with some UID can only be decoded by aALcyWorkspaceObjectCodec
with the same UID. For this purpose it is mandatory that, whenever the application is restarted,ALcyWorkspaceObjectCodec
's with the same UID's are registered with theTLcyWorkspaceManager
. Unique means that at any time no twoALcyWorkspaceObjectCodec
s orALcyWorkspaceCodecDelegate
s with the samegetUID()
must be registered with the sameTLcyWorkspaceManager
. Therefore it is suggested to use a package name prefix for the UID's. The UID's of allALcyWorkspaceCodecDelegate
s added by Lucy itself start with "com.luciad". The UID must not be 'null', must not be the empty string "", must not contain spaces and must not start with '%'- Returns:
- The UID for this
ALcyWorkspaceObjectCodec
.
-
canEncodeObject
public abstract boolean canEncodeObject(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent) This method returns true if the givenObject
can be encoded, false otherwise. This method should only be invoked by anALcyWorkspaceCodec
, never by user code. Instead user code must useALcyWorkspaceCodec.canEncodeReference(Object, Object)
when an object reference needs to be restored.- Parameters:
aWSCodec
- TheALcyWorkspaceCodec
, provided in case object references need to be stored.aObject
- The object to encode.aParent
- The parent of the object to encode. The parent will often be null, or for example when a domain objects needs to be saved (e.g. a polyline), the parent will normally be theILcdModel
that contains the domain object. The exact value of the parent is defined by theALcyWorkspaceObjectCodec
that will encode the object. Please check the javadoc of the addon responsible for the object to encode or refer to the Lucy Developer Guide for more information.- Returns:
- True if the given
Object
can be encoded, false otherwise.
-
encodeObject
public abstract void encodeObject(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, OutputStream aOut) throws IOException, TLcyWorkspaceAbortedException This method writes the givenObject
to the givenOutputStream
. This method should only be invoked by anALcyWorkspaceCodec
, never by user code. Instead user code must useALcyWorkspaceCodec.encodeReference(Object, Object)
when an object reference needs to be stored. Note that this method must, in general, be re-entrant: this method can be invoked by a thread before the previous call on that same thread is terminated. This happens when this method stores references (ALcyWorkspaceCodec.encodeReference(Object, Object)
) to objects that are encoded by this codec as well. Or if it stores references to objects that (indirectly) refer objects that are encoded by this codec.- Parameters:
aWSCodec
- TheALcyWorkspaceCodec
, provided in case object references need to be stored.aObject
- The object to encode.aParent
- The parent of the object to encode. The parent will often be null, or for example when a domain objects needs to be saved (e.g. a polyline), the parent will normally be theILcdModel
that contains the domain object. The exact value of the parent is defined by theALcyWorkspaceObjectCodec
that will encode the object. Please check the javadoc of the addon responsible for the object to encode or refer to the Lucy Developer Guide for more information.aOut
- TheOutputStream
to write to.- Throws:
IOException
- In case of IO failure.TLcyWorkspaceAbortedException
- In case the user aborted (e.g. canceled) the operation.
-
createObject
public abstract Object createObject(ALcyWorkspaceCodec aWSCodec, Object aParent, InputStream aIn) throws IOException, TLcyWorkspaceAbortedException This method creates anObject
of the proper class. The returned object will then be further initialized bydecodeObject(ALcyWorkspaceCodec, Object, Object, java.io.InputStream)
. The decoding of an object is split intocreateObject
anddecodeObject
to be able to deal with circular references. DuringcreateObject
ALcyWorkspaceCodec.decodeReference(String)
must not be used to resolve circular references. Actually it is advised not to useALcyWorkspaceCodec.decodeReference(String)
at all from this method. This method should only be invoked by anALcyWorkspaceCodec
, never by user code. Instead user code must useALcyWorkspaceCodec.decodeReference(String)
when an object reference needs to be restored.- Parameters:
aWSCodec
- TheALcyWorkspaceCodec
.aParent
- The parent of the object to decode. The parent will often be null, or for example when a domain objects needs to be restored (e.g. a polyline), the parent will normally be theILcdModel
that must contain the domain object. The exact value of the parent is defined by theALcyWorkspaceObjectCodec
that will decode the object. Please check the javadoc of the addon responsible for the object to decode or refer to the Lucy Developer Guide for more information.aIn
- TheInputStream
. Normally this method will not read from the input stream!- Returns:
- The created object.
- Throws:
IOException
- In case of IO failure.TLcyWorkspaceAbortedException
- In case the user aborted (e.g. canceled) the operation.
-
decodeObject
public void decodeObject(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, InputStream aIn) throws IOException, TLcyWorkspaceAbortedException This method decodes the properties of anObject
created bycreateObject(ALcyWorkspaceCodec, Object, java.io.InputStream)
from the givenInputStream
. The decision if this codec can read from theInputStream
is based on thegetUID()
of this codec. If theObject
was written by a codec with the same UID as this codec, it is assumed that this codec can read from theInputStream
. The decoding of an object is split intocreateObject
anddecodeObject
to be able to deal with circular references. Preferably object references should be restored from this method. (by usingALcyWorkspaceCodec.decodeReference(String)
). There are however a lot of codecs which don't need to do anything in this method. Therefore this method is not abstract, and the default implementation does nothing. This method should only be invoked by anALcyWorkspaceCodec
, never by user code. Instead user code must useALcyWorkspaceCodec.decodeReference(String)
when an object reference needs to be restored. Note that this method must, in general, be re-entrant: this method can be invoked by a thread before the previous call on that same thread is terminated. This happens when this method restores references (ALcyWorkspaceCodec.decodeReference(String)
) to objects that are decoded by this codec as well. Or if it restores references to objects that (indirectly) refer objects that are decoded by this codec.- Parameters:
aWSCodec
- TheALcyWorkspaceCodec
, provided in case object references need to be restored.aObject
- The object to decode the properties of. It was created usingcreateObject(ALcyWorkspaceCodec, Object, java.io.InputStream)
.aParent
- The parent of the object to decode. The parent will often be null, or for example when a domain objects needs to be restored (e.g. a polyline), the parent will normally be theILcdModel
that must contain the domain object. The exact value of the parent is defined by theALcyWorkspaceObjectCodec
that will decode the object. Please check the javadoc of the addon responsible for the object to decode or refer to the Lucy Developer Guide for more information.aIn
- TheInputStream
to read from.- Throws:
IOException
- In case of IO failure.TLcyWorkspaceAbortedException
- In case the user aborted (e.g. canceled) the operation.
-