Package com.luciad.lucy.workspace

Class TLcyFileWorkspaceCodec

java.lang.Object
com.luciad.lucy.workspace.ALcyWorkspaceCodec
com.luciad.lucy.workspace.TLcyBlobWorkspaceCodec
com.luciad.lucy.workspace.TLcyFileWorkspaceCodec
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdOutputStreamFactoryCapable, ILcdPropertyChangeSource
public class TLcyFileWorkspaceCodec extends TLcyBlobWorkspaceCodec

Extension of TLcyBlobWorkspaceCodec that can save and load workspaces to/from the file system. This workspace codec assumes that all String instances passed to it (for example in the encodeWorkspace and decodeWorkspace methods) represent file paths. If you want to customize the codec to save to other persistent storage like for example a database, you need to extend from TLcyBlobWorkspaceCodec instead of from this class.

Since this class knows the workspaces are encoded and decoded to/from the file system, it provides the following optimizations:

  • The methods decodePath(String) and encodePath(String) are implemented to interpret the Strings as file names, and to encode/resolve as much paths as possible as relative paths. This allows the workspace file, together with the needed data files, to be copied to another location on disk. Those data files could for example be the files that were loading by the user. The methods setUseRelativePaths(boolean) and setAllowUpRelativePaths(boolean) allow to find tune this behavior.
  • When overwriting an existing workspace, the codec will take a back-up of the existing workspace first. When workspace encoding fails, the back-up will be restored. When workspace encoding is successful, the back-up will be removed. This avoids that you end up with corrupt workspaces when something goes wrong during workspace encoding.
  • A screenshot of the current active GXY or Lightspeed map is saved next to the workspace file (see setSaveScreenshot(boolean)). The Lucy file chooser picks up such images when selecting the workspace file, and shows a preview of the image in the file chooser. This allows users to get a preview of the data contained in the workspace without actually loading it.

  • Field Details

    • FILE_EXTENSION

      public static final String FILE_EXTENSION
      A suggested file extension for workspaces. It is not mandatory to use this extension.
      See Also:

  • Constructor Details

    • TLcyFileWorkspaceCodec

      public TLcyFileWorkspaceCodec(ILcyLucyEnv aLucyEnv, TLcyWorkspaceManager aWorkspaceManager)
      Creates a new TLcyFileWorkspaceCodec.
      Parameters:
      aLucyEnv - The lucy environment.
      aWorkspaceManager - The workspace manager.

  • Method Details

    • canDecodeWorkspace

      public boolean canDecodeWorkspace(String aSourceName, List<String> aReasonsSFCT)
      Description copied from class: ALcyWorkspaceCodec

      Returns true if the given source name can be decoded, false otherwise. The second argument of the method is a list of strings which can be used to pass a description to the caller of this method.
      For example when a workspace cannot be decoded for a certain reason, a description of that reason can be added to the list of strings.

      Overrides:
      canDecodeWorkspace in class TLcyBlobWorkspaceCodec
      Parameters:
      aSourceName - The source name to check
      aReasonsSFCT - A side-effect parameter to which this method may add reasons on why it returned true or false
      Returns:
      true if the given source name can be decoded, false otherwise

    • encodeWorkspace

      public void encodeWorkspace(String aDestinationName) throws IOException, TLcyWorkspaceAbortedException
      Description copied from class: ALcyWorkspaceCodec
      Encodes the workspace. This method must never be invoked by user code, instead TLcyWorkspaceManager.encodeWorkspace(String) must be used.

      Encoding the workspace means all registered ALcyWorkspaceCodecDelegates will be asked to encode their part. When a ALcyWorkspaceCodecDelegate is encoding its part, it might need to store an object reference (e.g. a reference to an ILcdGXYLayer). It can do so using ALcyWorkspaceCodec.encodeReference(Object).

      This method must only be used if ALcyWorkspaceCodec.canEncodeWorkspace(String) for the same aDestinationName returns true.

      Overrides:
      encodeWorkspace in class TLcyBlobWorkspaceCodec
      Parameters:
      aDestinationName - The destination name of the workspace. It is up to subclasses to interpret this string, e.g. as a file name.
      Throws:
      IOException - In case of fatal IO failure.
      TLcyWorkspaceAbortedException - In case the operation is aborted, e.g. because the user canceled it.

    • isUseRelativePaths

      public boolean isUseRelativePaths()
      Returns true if relative paths are used. The default is true.
      Returns:
      True if relative paths are used.
      See Also:

    • setUseRelativePaths

      public void setUseRelativePaths(boolean aUseRelativePaths)
      Sets whether relative paths are used or not. If true, encodePath(String) will encode a path as a path relative to the workspace file name. Other file names are left untouched. If false, file names are left untouched. See also setAllowUpRelativePaths(boolean).
      Parameters:
      aUseRelativePaths - True to use relative paths, false otherwise.

    • isAllowUpRelativePaths

      public boolean isAllowUpRelativePaths()
      Returns true if relative paths that start with .. are allowed. The default is false.

      This property is only applicable if isUseRelativePaths() returns true.

      Returns:
      true if relative paths that start with .. are allowed.
      See Also:

    • setAllowUpRelativePaths

      public void setAllowUpRelativePaths(boolean aAllowUpRelativePaths)
      Sets if relative paths that start with .. are allowed. If false only relative paths are used for files that are 'below' the workspace file. If set to true, relative paths will always be used, regardless if they are 'below' the workspace file or not.

      This property is only applicable if isUseRelativePaths() returns true.

      Parameters:
      aAllowUpRelativePaths - True to use relative paths always, false to only use relative paths that point 'below' the workspace file.
      See Also:

    • isSaveScreenshot

      public final boolean isSaveScreenshot()
      Returns true when this codec saves a screenshot of the map next to the workspace file when saving a workspace.
      Returns:
      true when this codec saves a screenshot of the map next to the workspace file when saving a workspace.
      Since:
      2017.1

    • setSaveScreenshot

      public final void setSaveScreenshot(boolean aSaveScreenshot)
      Sets whether this codec should save a screenshot of the map next to the workspace file when saving a workspace. Images next to a file are shown by the standard Lucy file chooser when selecting the file. This allows the user to see a preview of the workspace without actually loading the workspace.
      Parameters:
      aSaveScreenshot - true when a screenshot of the map should be saved next to the workspace file.
      Since:
      2017.1

    • encodePath

      public String encodePath(String aPath)
      Encodes aPath as a relative path depending on isUseRelativePaths(). If true, this method will encode aPath as a path relative to the workspace file name if the given path is in the same directory as the workspace file or below it. If isAllowUpRelativePaths() returns true, also relative paths above the directory of the workspace file are allowed.

      Other file names are left untouched. If null is provided, null is returned.

      Overrides:
      encodePath in class ALcyWorkspaceCodec
      Parameters:
      aPath - The path to encode.
      Returns:
      The (relative) path.

    • decodePath

      public String decodePath(String aPath)
      Resolves relative paths as relative to the workspace file name. Other paths are left untouched. If null is provided, null is returned.
      Overrides:
      decodePath in class ALcyWorkspaceCodec
      Parameters:
      aPath - The path to resolve.
      Returns:
      The resolved path.
      See Also: