Package com.luciad.lucy.workspace

Class ALcyWorkspaceObjectCodecWrapper

java.lang.Object
com.luciad.lucy.workspace.ALcyWorkspaceObjectCodec
com.luciad.lucy.workspace.ALcyWorkspaceObjectCodecWrapper
public abstract class ALcyWorkspaceObjectCodecWrapper extends ALcyWorkspaceObjectCodec

ALcyWorkspaceObjectCodec wrapper that - in addition to what the wrapped codec writes - can encode and decode some additional information. It takes care so that these two blocks of data can't get mixed up.

An example usage could for example be to overwrite createLayerWorkspaceCodecs and wrap the supers codec to (re)store some additional information about your own type of layer:


 private static class FooWrapperCodec extends ALcyWorkspaceObjectCodecWrapper {
   public FooWrapperCodec(ALcyWorkspaceObjectCodec aDelegate) {
     super(aDelegate);
   }

   protected void encodeObjectExtra(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, OutputStream aOut) throws IOException {
     MyLayer myLayer = (MyLayer) aObject;

     // Using properties here for convenience, the stream could be manipulated directly as well.
     TLcyStringProperties props = new TLcyStringProperties();
     props.putBoolean("foo", myLayer.isFoo());
     new TLcyStringPropertiesCodec().encode(props, aOut);
   }

   protected void decodeObjectExtra(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, InputStream aIn) throws IOException {
     MyLayer myLayer = (MyLayer) aObject;

     ALcyProperties props = new TLcyStringPropertiesCodec().decode(aIn);
     myLayer.setFoo(props.getBoolean("foo", myLayer.isFoo()));
   }
 }

Wrapping a codec is not backwards compatible: when reading workspace files that were written before the wrapper was added, null is returned where previously an object was created. If this is a concern, an additional codec needs to be registered to the ILcyLucyEnv.getWorkspaceManager(). So if you used to do this: 


   ALcyWorkspaceObjectCodec someCodec = ...
   lucyEnv.getWorkspaceManager().addWorkspaceObjectCodec(someCodec);
You should now do this: 

   ALcyWorkspaceObjectCodec someCodec = ...
   ALcyWorkspaceObjectCodecWrapper wrapper = new ALcyWorkspaceObjectCodecWrapper(someCodec){...};

   lucyEnv.getWorkspaceManager().addWorkspaceObjectCodec(wrapper);
   lucyEnv.getWorkspaceManager().addWorkspaceObjectCodec(wrapper.createCompatibilityCodec());
Since:
2012.1

  • Constructor Details

    • ALcyWorkspaceObjectCodecWrapper

      protected ALcyWorkspaceObjectCodecWrapper(ALcyWorkspaceObjectCodec aDelegate)
      Creates a ALcyWorkspaceObjectCodecWrapper.
      Parameters:
      aDelegate - The codec that needs to be wrapped.

  • Method Details

    • createCompatibilityCodec

      public ALcyWorkspaceObjectCodec createCompatibilityCodec()

      Creates a compatibility codec that - when registered together with this wrapper codec - provides backward compatibility with older workspace files. Please refer to the class comment for an example.

      The return value of this method is typically registered to ILcyLucyEnv.getWorkspaceManager().

      It is in fact a read-only wrapper around the codec provided in the constructor. As such, decoding supports both the old and the new workspace format. The old format is supported by the wrapped codec, the new format by the wrapper codec. They can be distinguished because their UID's are different. For encoding, only the wrapper codec is used, as the wrapped codec is read-only (canEncodeObject always returns false).

      Returns:
      The compatibility codec.

    • encodeObjectExtra

      protected abstract void encodeObjectExtra(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, OutputStream aOut) throws IOException

      This method allows to store additional information about aObject in the given stream, similar to how encodeObject would do. The encodeObject method of the wrapped codec is called before this one.

      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.

    • decodeObjectExtra

      protected abstract void decodeObjectExtra(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, InputStream aIn) throws IOException

      This method allows to restore the additional information as it was written by encodeObjectExtra. Similar to how decodeObject relates to encodeObject. The decodeObject method of the wrapped codec is called before this one.

      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.

    • getUID

      public String getUID()
      Description copied from class: ALcyWorkspaceObjectCodec
      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 '%'

      Specified by:
      getUID in class ALcyWorkspaceObjectCodec
      Returns:
      The UID for this ALcyWorkspaceObjectCodec.

    • canEncodeObject

      public boolean canEncodeObject(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent)
      Description copied from class: ALcyWorkspaceObjectCodec
      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.

      Specified by:
      canEncodeObject in class ALcyWorkspaceObjectCodec
      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 final void encodeObject(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, OutputStream aOut) throws IOException
      Description copied from class: ALcyWorkspaceObjectCodec
      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.

      Specified by:
      encodeObject in class ALcyWorkspaceObjectCodec
      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.

    • createObject

      public final Object createObject(ALcyWorkspaceCodec aWSCodec, Object aParent, InputStream aIn) throws IOException
      Description copied from class: ALcyWorkspaceObjectCodec
      This method creates an Object of the proper class. The returned object will then be further initialized by ALcyWorkspaceObjectCodec.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.

      Specified by:
      createObject in class ALcyWorkspaceObjectCodec
      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.

    • decodeObject

      public final void decodeObject(ALcyWorkspaceCodec aWSCodec, Object aObject, Object aParent, InputStream aIn) throws IOException
      Description copied from class: ALcyWorkspaceObjectCodec
      This method decodes the properties of an Object created by ALcyWorkspaceObjectCodec.createObject(ALcyWorkspaceCodec, Object, java.io.InputStream) from the given InputStream. The decision if this codec can read from the InputStream is based on the ALcyWorkspaceObjectCodec.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.

      Overrides:
      decodeObject in class ALcyWorkspaceObjectCodec
      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 ALcyWorkspaceObjectCodec.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.