com.luciad.lucy.workspace

LuciadLightspeedClass ALcyWorkspaceObjectCodec

java.lang.Object

com.luciad.lucy.workspace.ALcyWorkspaceObjectCodec

Direct Known Subclasses:

ALcyWorkspaceObjectCodecWrapper, TLcyGXYAsynchronousCustomizerPanelWorkspaceCodec, TLcyGXYAsynchronousLayerWorkspaceCodec

public abstract class ALcyWorkspaceObjectCodec
extends Object

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

First 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

First 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 ILcyApplicationPanes, ILcyMapComponents, ILcdGXYViews, ILcdGXYLayers, ILcdModels, domain objects of ILcdModels (e.g. polylines, points, ...)

Instances of ALcyWorkspaceObjectCodec must be registered with ALcyWorkspaceCodec.

If an ALcyWorkspaceCodecDelegates 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

Constructors

Constructor and Description
ALcyWorkspaceObjectCodec()

Method Summary

Modifier and Type	Method and Description
abstract boolean	canEncodeObject(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent) This method returns true if the given Object can be encoded, false otherwise.
abstract Object	createObject(ALcyWorkspaceCodec aWSCodec, Object aParent, InputStream aIn) This method creates an Object of the proper class.
void	decodeObject(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, InputStream aIn) This method decodes the properties of an Object created by createObject(ALcyWorkspaceCodec, Object, java.io.InputStream) from the given InputStream.
abstract void	encodeObject(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, OutputStream aOut) This method writes the given Object to the given OutputStream.
abstract String	getUID() A unique identifier for this ALcyWorkspaceObjectCodec.

Methods inherited from class java.lang.Object

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

Constructor Detail

ALcyWorkspaceObjectCodec

public ALcyWorkspaceObjectCodec()

Method Detail

getUID

public abstract String getUID()

A unique identifier for this ALcyWorkspaceObjectCodec.

The UID will be used to make sure that a workspace part that is encoded by a ALcyWorkspaceObjectCodec with some UID can only be decoded by a ALcyWorkspaceObjectCodec 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 the TLcyWorkspaceManager.

Unique means that at any time no two ALcyWorkspaceObjectCodecs or ALcyWorkspaceCodecDelegates with the same getUID() must be registered with the same TLcyWorkspaceManager. Therefore it is suggested to use a package name prefix for the UID's. The UID's of all ALcyWorkspaceCodecDelegates 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 given Object can be encoded, false otherwise.

This method should only be invoked by an ALcyWorkspaceCodec, never by user code. Instead user code must use ALcyWorkspaceCodec.canEncodeReference(Object, Object) when an object reference needs to be restored.

Parameters:

aWSCodec - The ALcyWorkspaceCodec, 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 the ILcdModel that contains the domain object. The exact value of the parent is defined by the ALcyWorkspaceObjectCodec 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 given Object to the given OutputStream.

This method should only be invoked by an ALcyWorkspaceCodec, never by user code. Instead user code must use ALcyWorkspaceCodec.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 - The ALcyWorkspaceCodec, 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 the ILcdModel that contains the domain object. The exact value of the parent is defined by the ALcyWorkspaceObjectCodec 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 - The OutputStream 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 an Object of the proper class. The returned object will then be further initialized by decodeObject(ALcyWorkspaceCodec, Object, Object, java.io.InputStream).

The decoding of an object is split into createObject and decodeObject to be able to deal with circular references. During createObject ALcyWorkspaceCodec.decodeReference(String) must not be used to resolve circular references. Actually it is advised not to use ALcyWorkspaceCodec.decodeReference(String) at all from this method.

This method should only be invoked by an ALcyWorkspaceCodec, never by user code. Instead user code must use ALcyWorkspaceCodec.decodeReference(String) when an object reference needs to be restored.

Parameters:

aWSCodec - The ALcyWorkspaceCodec.

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 the ILcdModel that must contain the domain object. The exact value of the parent is defined by the ALcyWorkspaceObjectCodec 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 - The InputStream. 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 an Object created by createObject(ALcyWorkspaceCodec, Object, java.io.InputStream) from the given InputStream. The decision if this codec can read from the InputStream is based on the getUID() of this codec. If the Object was written by a codec with the same UID as this codec, it is assumed that this codec can read from the InputStream.

The decoding of an object is split into createObject and decodeObject to be able to deal with circular references. Preferably object references should be restored from this method. (by using ALcyWorkspaceCodec.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 an ALcyWorkspaceCodec, never by user code. Instead user code must use ALcyWorkspaceCodec.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 - The ALcyWorkspaceCodec, provided in case object references need to be restored.

aObject - The object to decode the properties of. It was created using createObject(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 the ILcdModel that must contain the domain object. The exact value of the parent is defined by the ALcyWorkspaceObjectCodec 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 - The InputStream to read from.

Throws:

IOException - In case of IO failure.

TLcyWorkspaceAbortedException - In case the user aborted (e.g. canceled) the operation.