com.luciad.lucy.util.preferences

LuciadLightspeedClass TLcyPreferencesTool

java.lang.Object

com.luciad.lucy.util.ALcyTool

com.luciad.lucy.util.preferences.TLcyPreferencesTool

All Implemented Interfaces:

ILcdPropertyChangeSource

public class TLcyPreferencesTool
extends ALcyTool

Support class for working with preferences. It offers three kinds of preferences, which are stored in the correct preferences store of the Lucy backend at the appropriate times:

• System preferences: usually config files, see TLcyPreferencesManager.getSystemPreferences() for details.
• User preferences: per-user settings that globally apply for the application, for example the window size and location. See TLcyPreferencesManager.getCurrentUserPreferences() for details.
• Workspace preferences: stored in a workspace using e.g. File|Save workspace.

    String longPrefix = "com.yourcompany.YourAddOn."; // only used for TLcyPreferencesManager
    String shortPrefix = "YourAddOn."; // always used
    TLcyPreferencesTool tool = new TLcyPreferencesTool(pathToConfigFile, longPrefix, shortPrefix);
    tool.plugInto(aLucyEnv);

    ALcyProperties compositeWorkspacePreferences = tool.getCompositeWorkspacePreferences();
    // retrieve a preference from the workspace, user, or system preferences (in that order)
    System.out.println(compositeWorkspacePreferences.getString(shortPrefix + "myKey", "a value"));
    // save a preference to the workspace
    compositeWorkspacePreferences.putString(shortPrefix + "myKey", "a different value");

Kinds of preferences

Preferences saved in the workspace preferences of this tool are automatically stored in and restored from the workspace. The keys and String values of the preferences are kept as is, the Object values are converted to Strings using the composite property converter (see below). During workspace decoding, the workspace preferences are restored on the Swing Thread (the Event Dispatch Thread).

Preferences saved in the user- and system preferences of this tool will automatically be saved in the user- and system preferences of the TLcyPreferencesManager. The String values of the preferences are kept as is and the Object values converted to Strings as with the workspace preferences, but the keys are prefixed with the long prefix of this tool.

The workspace preferences are stored in the workspace when the workspace is encoded and decoded, and the user and system preferences are stored when the tool is unplugged from the Lucy backend or when Lucy is shut down. This tool only saves those preferences that are changed with respect to the initial configuration.

Storing Object preferences

The user and system preferences of TLcyPreferencesManager are String based, and for workspaces this TLcyPreferencesTool also saves all workspace preferences as Strings. The user, system and workspace preferences of this TLcyPreferencesTool however are all ALcyProperties instances which can accept any kind of object as value for a preference. When the preferences need to be saved, to the workspace or to the user or system preferences of the TLcyPreferencesManager, this TLcyPreferencesTool uses its TLcyCompositePropertyConverter to convert these values to Strings. If you need to save an Object preference, add an appropriate ILcyPropertyConverter to the composite property converter.

It can also be useful to have access to the ALcyWorkspaceCodec when converting Object properties to String properties, as the ALcyWorkspaceCodec can give a String identifier for some objects when encoding a workspace. The ALcyPreferencesPropertyConverter is an abstract class that can retrieve the ALcyWorkspaceCodec from the TLcyPreferencesTool during workspace decoding. Note that the ALcyWorkspaceCodec is only available when the ALcyPreferencesPropertyConverter is being used to convert an ALcyProperties instance for workspace encoding. In other cases, the ALcyWorkspaceCodec is not available and is null.

Priorities

It is up to you to decide which preferences are system preferences, user preferences or workspace preferences. This tool only makes the distinction between these preferences with regards to priority: the workspace preferences in this tool have a higher priority than the user preferences, which in turn have a higher priority than the system preferences. This means that when a preference with the same key is available in the user preferences and in the workspace preferences, the value of the preference in the workspace preferences should be considered as the correct value.

The TLcyPreferencesTool implements this priority in its composite preferences. getCompositeWorkspacePreferences() returns an ALcyProperties instance that tries to retrieve a value for a given key first in the workspace preferences. When the requested preference is not available in the workspace preferences, only then will it search in the user preferences. Finally, if the preference is not available in the user preferences either, the system preferences are searched. All preferences saved in this composite ALcyProperties are saved in the workspace preferences of tool.

The method getCompositeUserPreferences() is similar, only the returned ALcyProperties starts looking for a preference in the user preferences and never looks in the workspace preferences. All preferences written to these ALcyProperties are stored in the user preferences of this tool.

See Also:

getCompositePropertyConverter(), TLcyPreferencesManager, TLcyWorkspaceManager

Constructor Summary

Constructors

Constructor and Description
TLcyPreferencesTool(ALcyProperties aSystemDefaults, ALcyProperties aUserDefaults, String aConfigSource, String aLongPrefix, String aShortPrefix) Creates a new TLcyPreferencesTool that is initialised with optional (hard coded) defaults for system and user preferences, and that optionally parses a configuration source.
TLcyPreferencesTool(String aConfigSource, Class aClass) Deprecated. Better use the constructor with explicit long and short prefix, to avoid any confusion. Creates a new TLcyPreferencesTool that parses the given configuration source.
TLcyPreferencesTool(String aConfigSource, String aLongPrefix, String aShortPrefix) Creates a new TLcyPreferencesTool that parses the given configuration source.

Method Summary

Modifier and Type	Method and Description
TLcyCompositePropertyConverter	getCompositePropertyConverter() Returns the composite property converter of this tool.
ALcyProperties	getCompositeUserPreferences() Returns a composite of the user and system preferences of this tool.
ALcyProperties	getCompositeWorkspacePreferences() Returns a composite of the user, and system, and workspace preferences of this tool.
ALcyProperties	getSystemPreferences() Returns the system preferences of this tool.
ALcyProperties	getUserPreferences() Returns the user preferences of this tool.
ALcyProperties	getWorkspacePreferences() Returns the workspace preferences of this tool.
boolean	isTraceOn() Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.
void	plugInto(ILcyLucyEnv aLucyEnv) Reads the initial system and user preferences from the configuration source and performs the necessary work to automatically save the different kinds of preferences in the correct preferences stores.
static void	setClassTraceOn(boolean aClassTraceOn) Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.
void	setTraceOn(boolean aTraceOn) Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.
void	setWorkspaceCodec(ALcyWorkspaceCodec aWorkspaceCodec)
void	unplugFrom(ILcyLucyEnv aLucyEnv) Saves the user and system preferences of this tool to the user and system preferences of the TLcyPreferencesManager.

Methods inherited from class com.luciad.lucy.util.ALcyTool

addPropertyChangeListener, addPropertyChangeListener, assertPlugged, firePropertyChange, getLongPrefix, getLongPrefixWithClassName, getLucyEnv, getShortPrefix, removePropertyChangeListener, removePropertyChangeListener

Methods inherited from class java.lang.Object

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

Constructor Detail

TLcyPreferencesTool

@Deprecated
public TLcyPreferencesTool(String aConfigSource,
                                       Class aClass)

Deprecated. Better use the constructor with explicit long and short prefix, to avoid any confusion. Creates a new TLcyPreferencesTool that parses the given configuration source.

Parameters:

aConfigSource - The configuration source to parse the system and user preferences from. Must not be null.

aClass - A representative class for using this ALcyApplicationPaneTool, normally an extension of ALcyAddOn. It is used to retrieve the long and short prefixes using getLongPrefix and getShortPrefix. These prefixes are stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), the given class or its name must never change.

See Also:

TLcyPreferencesManager.getUserPreferencesPropertiesDecoder(), TLcyPreferencesManager.getSystemPreferencesPropertiesDecoder()

TLcyPreferencesTool

public TLcyPreferencesTool(String aConfigSource,
                           String aLongPrefix,
                           String aShortPrefix)

Creates a new TLcyPreferencesTool that parses the given configuration source.

The long prefix must be globally unique, the short prefix is the prefix used in the configuration files. Once chosen, they shouldn't change if backward compatibility is a concern (for example reading old workspace files). The concatenation of the long and short prefix has another constraint: no combination should be a substring of another one. When using for example getLongPrefixWithClassName as the long prefix, this never happens.

Parameters:

aConfigSource - The configuration source to parse the system and user preferences from. Must not be null.

aLongPrefix - The long prefix. This prefix must be globally unique. It is stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), this prefix must never change. Use for example ALcyTool.getLongPrefixWithClassName(Class).

aShortPrefix - The short prefix. This prefix is used to prefix the keys that are retrieved from the given properties (see class comment). It might be stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), this prefix must never change. Lucy add-ons normally use ALcyTool.getShortPrefix(Class).

See Also:

TLcyPreferencesManager.getUserPreferencesPropertiesDecoder(), TLcyPreferencesManager.getSystemPreferencesPropertiesDecoder()

TLcyPreferencesTool

public TLcyPreferencesTool(ALcyProperties aSystemDefaults,
                           ALcyProperties aUserDefaults,
                           String aConfigSource,
                           String aLongPrefix,
                           String aShortPrefix)

Creates a new TLcyPreferencesTool that is initialised with optional (hard coded) defaults for system and user preferences, and that optionally parses a configuration source.

When using the system and user defaults and config file 'sourceName.cfg', the order of all preferences involved is listed below, as returned by getCompositeWorkspacePreferences(). The entry at the top has the highest priority, and the one at the bottom the lowest

• Workspace preferences
• sourceName.userPrefs.cfg
• aUserDefaults
• sourceName.cfg
• aSystemDefaults

This means you can specify some hard-coded values in say aSystemDefaults and be sure they are always available, or even use code to generate them.

The long prefix must be globally unique, the short prefix is the prefix used in the configuration files. Once chosen, they shouldn't change if backward compatibility is a concern (for example reading old workspace files). The concatenation of the long and short prefix has another constraint: no combination should be a substring of another one. When using for example getLongPrefixWithClassName as the long prefix, this never happens.

Parameters:

aSystemDefaults - The (hard coded) defaults for the system preferences. Can be null.

aUserDefaults - The (hard coded) defaults for the user preferences. Can be null.

aConfigSource - The configuration source to parse the system and user preferences from. If left null, no parsing is performed.

aLongPrefix - The long prefix. This prefix must be globally unique. It is stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), this prefix must never change. Use for example ALcyTool.getLongPrefixWithClassName(Class).

aShortPrefix - The short prefix. This prefix is used to prefix the keys that are retrieved from the given properties (see class comment). It might be stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), this prefix must never change. Lucy add-ons normally use ALcyTool.getShortPrefix(Class).

See Also:

TLcyPreferencesManager.getUserPreferencesPropertiesDecoder(), TLcyPreferencesManager.getSystemPreferencesPropertiesDecoder()

Method Detail

getCompositeWorkspacePreferences

public ALcyProperties getCompositeWorkspacePreferences()

Returns a composite of the user, and system, and workspace preferences of this tool. Property keys must be prefixed with the short prefix passed in the constructor of this class.

When accessing properties (get methods), they are first read from the workspace preferences, if not present, an attempt is made to read them from the user preferences, and if not present they are read from the system preferences. Modifications (put methods) only affect the workspace preferences.

This method can only be called after plugInto has been called.

Returns:

combination of system, user and workspace preferences. Never null.

Throws:

IllegalStateException - When plugInto has not been called yet.

getCompositeUserPreferences

public ALcyProperties getCompositeUserPreferences()

Returns a composite of the user and system preferences of this tool. Property keys must be prefixed with the short prefix passed in the constructor of this class.

When accessing properties (get methods), they are first read from the user preferences, if not present, they are read from the system preferences. Modifications (put methods) only affect the user preferences.

This method can only be called after plugInto has been called.

Returns:

combination of system and user preferences. Never null.

Throws:

IllegalStateException - When plugInto has not been called yet.

getSystemPreferences

public ALcyProperties getSystemPreferences()

Returns the system preferences of this tool. Property keys must be prefixed with the short prefix passed in the constructor of this class.

Preference changes are automatically saved in the system preferences of the TLcyPreferencesManager. When saving these, keys are prefixed with the long prefix of this tool (in addition to the short prefix), and all values are converted to Strings with the composite property converter.

This method can only be called after plugInto has been called.

Returns:

An ALcyProperties instance holding the system preferences of this tool. Never null.

Throws:

IllegalStateException - When plugInto has not been called yet.

See Also:

getCompositePropertyConverter(), TLcyPreferencesManager.getSystemPreferences()

getUserPreferences

public ALcyProperties getUserPreferences()

Returns the user preferences of this tool. Property keys must be prefixed with the short prefix passed in the constructor of this class.

Preference changes are automatically saved in the user preferences of the TLcyPreferencesManager. When saving these, keys are prefixed with the long prefix of this tool (in addition to the short prefix), and all values are converted to Strings with the composite property converter.

This method can only be called after plugInto has been called.

Returns:

An ALcyProperties instance holding the user preferences of this tool. Never null.

Throws:

IllegalStateException - When plugInto has not been called yet.

See Also:

getCompositePropertyConverter(), TLcyPreferencesManager.getCurrentUserPreferences()

getWorkspacePreferences

public ALcyProperties getWorkspacePreferences()

Returns the workspace preferences of this tool. Property keys must be prefixed with the short prefix passed in the constructor of this class.

Preference changes are automatically saved in the workspace. When saving these, all values are converted to Strings with the composite property converter.

This method can only be called after plugInto has been called.

Warning: don't rely on the key order.

This method can only be called after plugInto has been called.

Returns:

An ALcyProperties instance holding the workspace preferences of this tool. Never null.

Throws:

IllegalStateException - When plugInto has not been called yet.

See Also:

getCompositePropertyConverter(), ALcyWorkspaceCodec

getCompositePropertyConverter

public TLcyCompositePropertyConverter getCompositePropertyConverter()

Returns the composite property converter of this tool. This converter is used to transform all values in the different preferences to Strings when saving them to the preferences stores.

Addons using this tool are expected to register ILcyPropertyConverter instances if they save any kind of Object in any of the preferences for which no default put... method is available. This means that for Color, String arrays, etc. no ILcyPropertyConverter needs to be registered.

This method may be called before the plugInto method has been called.

Returns:

The TLcyCompositePropertyConverter used to convert all values to Strings. Never null.

plugInto

public void plugInto(ILcyLucyEnv aLucyEnv)

Reads the initial system and user preferences from the configuration source and performs the necessary work to automatically save the different kinds of preferences in the correct preferences stores.

Plugs this tool. This method is usually called from ALcyAddOn#plugInto.

Overrides:

plugInto in class ALcyTool

Parameters:

aLucyEnv - The environment to plug into.

See Also:

TLcyPreferencesManager.getUserPreferencesPropertiesDecoder(), TLcyPreferencesManager.getSystemPreferencesPropertiesDecoder()

unplugFrom

public void unplugFrom(ILcyLucyEnv aLucyEnv)

Saves the user and system preferences of this tool to the user and system preferences of the TLcyPreferencesManager.

Unplugs this tool. This method is usually called from ALcyAddOn#unplugFrom.

Overrides:

unplugFrom in class ALcyTool

Parameters:

aLucyEnv - The environment to unplug from, must be identical to the environment given to plugInto.

setWorkspaceCodec

public void setWorkspaceCodec(ALcyWorkspaceCodec aWorkspaceCodec)

setClassTraceOn

@Deprecated
public static void setClassTraceOn(boolean aClassTraceOn)

Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.

Enables tracing for all instances of this class. If the argument is true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.

Parameters:

aClassTraceOn - if true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.

setTraceOn

@Deprecated
public void setTraceOn(boolean aTraceOn)

Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.

Enables tracing for this class instance. Calling this method with either true or false as argument automatically turns off tracing for all other class instances for which setTraceOn has not been called. If the argument is false then only the informative, warning and error log messages are recorded.

Parameters:

aTraceOn - if true then all log messages are recorded for this instance. If false, then only the informative, warning and error log messages are recorded.

isTraceOn

@Deprecated
public boolean isTraceOn()

Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.

Returns true if tracing is enabled for this class.

Returns:

true if tracing is enabled for this class, false otherwise.