com.luciad.lucy.workspace

LuciadLightspeedClass 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 Summary

Fields

Modifier and Type	Field and Description
static String	FILE_EXTENSION A suggested file extension for workspaces.

Constructor Summary

Constructors

Constructor and Description
TLcyFileWorkspaceCodec(ILcyLucyEnv aLucyEnv, TLcyWorkspaceManager aWorkspaceManager) Creates a new TLcyFileWorkspaceCodec.

Method Summary

Modifier and Type	Method and Description
boolean	canDecodeWorkspace(String aSourceName, List<String> aReasonsSFCT) Returns true if the given source name can be decoded, false otherwise.
String	decodePath(String aPath) Resolves relative paths as relative to the workspace file name.
String	encodePath(String aPath) Encodes aPath as a relative path depending on isUseRelativePaths().
void	encodeWorkspace(String aDestinationName) Encodes the workspace.
boolean	isAllowUpRelativePaths() Returns true if relative paths that start with .. are allowed.
boolean	isSaveScreenshot() Returns true when this codec saves a screenshot of the map next to the workspace file when saving a workspace.
boolean	isUseRelativePaths() Returns true if relative paths are used.
void	setAllowUpRelativePaths(boolean aAllowUpRelativePaths) Sets if relative paths that start with .. are allowed.
void	setSaveScreenshot(boolean aSaveScreenshot) Sets whether this codec should save a screenshot of the map next to the workspace file when saving a workspace.
void	setUseRelativePaths(boolean aUseRelativePaths) Sets whether relative paths are used or not.

Methods inherited from class com.luciad.lucy.workspace.TLcyBlobWorkspaceCodec

canDecodeWorkspace, canEncodeWorkspace, decodeWorkspace, decodeWorkspaceDelegateCodecIDs, getInputStreamFactory, getOutputStreamFactory, retrieveInputStream, retrieveOutputStream, setInputStreamFactory, setOutputStreamFactory

Methods inherited from class com.luciad.lucy.workspace.ALcyWorkspaceCodec

addPropertyChangeListener, addPropertyChangeListener, canEncodeReference, canEncodeReference, checkApplicationHeader, createApplicationHeader, decodeFromInputStream, decodeReference, encodeObject, encodeReference, encodeReference, firePropertyChange, flushWorkspaceStorageName, getLogListener, getParentComponent, getStatusListener, getWorkspaceManager, getWorkspaceStorageName, removePropertyChangeListener, removePropertyChangeListener, setLogListener, setParentComponent, setStatusListener

Methods inherited from class java.lang.Object

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

Field Detail

FILE_EXTENSION

public static final String FILE_EXTENSION

A suggested file extension for workspaces. It is not mandatory to use this extension.

See Also:

Constant Field Values

Constructor Detail

TLcyFileWorkspaceCodec

public TLcyFileWorkspaceCodec(ILcyLucyEnv aLucyEnv,
                              TLcyWorkspaceManager aWorkspaceManager)

Creates a new TLcyFileWorkspaceCodec.

Parameters:

aLucyEnv - The lucy environment.

aWorkspaceManager - The workspace manager.

Method Detail

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(boolean)

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(boolean)

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:

isAllowUpRelativePaths()

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:

encodePath(String)