com.luciad.lucy.addons.preferences

LuciadLightspeedClass TLcyPersistentPreferencesAddOn

java.lang.Object

com.luciad.lucy.addons.ALcyAddOn

com.luciad.lucy.addons.preferences.TLcyPersistentPreferencesAddOn

public class TLcyPersistentPreferencesAddOn
extends ALcyAddOn

This addon makes the user and system preferences of Lucy persistent. The Lucy user preferences can be retrieved using ILcyLucyEnv.getPreferencesManager().getCurrentUserPreferences(). The Lucy system preferences are retrieved using ILcyLucyEnv.getPreferencesManager().getSystemPreferences(). When the addon is plugged, it reads the preferences from the persistent store. For user properties that are not available in the persistent store, the properties in the property file defined in the config file of this addon is used as a fallback (default_preferences.cfg). Only properties that have values that differ from these defaults are stored persistently. There are no default for system properties.

Preferences are stored per version. This means that each version of Lucy has its own distinct set of preferences. Patch versions (like 8.2.1) don't get their own set of preferences but reuse those of the main version (i.e. 8.2). When Lucy starts, it checks if there already exist preferences for the current version. If not, the preferences from the newest Lucy version that can be found and that is older than the current one are imported and copied to the current version.

Where the preferences are stored depends on your operating system. On Windows, they are stored in the registry

• User preferences: stored under HKEY_CURRENT_USER/Software/JavaSoft/Prefs
• System preferences: stored under HKEY_LOCAL_MACHINE/Software/JavaSoft/Prefs

On other operating systems, they are stored in a file

• User preferences are stored in the home dir: for Linux ~/.java and for Mac ~/Library/Preferences
• System preferences are stored in a system dir: for Linux /etc/.java and for Mac /Library/Preferences

The TLcyPreferencesManager.getCurrentUserPreferences() object is stored using the Java 1.4 java.util.prefs.Preferences API. This also brings the limitations of that API:

• Maximum key length of 80 characters (hierarchical keys have 80 characters per level)
• Maximum value length of 8192 characters

Note that in the java.util.prefs.Preferences API hierarchical keys are split by a slash (/), but for consistency with other applications of the TLcyStringProperties object within Lucy, we've chosen to use dot (.) as a separator. Therefore dots and slashes are swapped before the keys are stored in the java.util.prefs.Preferences API.

For convenience, these methods are offered to manipulate the persistent store:

• clearUserPreferences()
• encodeUserPreferences()
• decodeUserPreferences()
• clearSystemPreferences()
• encodeSystemPreferences()
• decodeSystemPreferences()

For debugging purposes, it might be very useful to enable trace support on the class setClassTraceOn(boolean). It prints out which properties are loaded and stored, when they are loaded and stored, ...

If a custom application is built on top of Lucy, it could be useful to avoid that the standard Lucy application interacts with the preferences of the custom application. Therefore a prefix is used to store all preferences. This prefix can be configured by modifying the property 'TLcyPersistentPreferencesAddOn.storagePrefix' in the configuration file of this addon.

If needed, this addon can be replaced by a custom addon that makes the preferences persistent using some other mechanism. For example one could write an addon that saves the preferences to a server.

Constructor Summary

Constructors

Constructor and Description
TLcyPersistentPreferencesAddOn()

Method Summary

Modifier and Type	Method and Description
void	clearSystemPreferences() Clears all system preferences.
void	clearUserPreferences() Clears all user preferences for the current user.
void	decodeSystemPreferences() Decodes the system preferences from the persistent store into TLcyPreferencesManager.getSystemPreferences().
void	decodeUserPreferences() Decodes the user preferences from the persistent store into TLcyPreferencesManager.getCurrentUserPreferences().
void	encodeSystemPreferences() Encodes the system preferences (TLcyPreferencesManager.getSystemPreferences()) to the persistent store.
void	encodeUserPreferences() Encodes the user preferences (TLcyPreferencesManager.getCurrentUserPreferences()) to the persistent store.
boolean	isTraceOn() Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.
void	plugInto(ILcyLucyEnv aLucyEnv) Plugs this addon into the given lucy environment.
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	unplugFrom(ILcyLucyEnv aLucyEnv) Unplugs this addon from the given Lucy environment.

Methods inherited from class com.luciad.lucy.addons.ALcyAddOn

getConfigSourceName, getDisplayName, setConfigSourceName, setDisplayName

Methods inherited from class java.lang.Object

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

Constructor Detail

TLcyPersistentPreferencesAddOn

public TLcyPersistentPreferencesAddOn()

Method Detail

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.

plugInto

public void plugInto(ILcyLucyEnv aLucyEnv)

Description copied from class: ALcyAddOn

Plugs this addon into the given lucy environment. It is in the implementation of this method that the addon adds its functionality to the Lucy backend.

Specified by:

plugInto in class ALcyAddOn

Parameters:

aLucyEnv - The lucy environment to plug into.

See Also:

ALcyAddOn.unplugFrom(com.luciad.lucy.ILcyLucyEnv)

unplugFrom

public void unplugFrom(ILcyLucyEnv aLucyEnv)

Description copied from class: ALcyAddOn

Unplugs this addon from the given Lucy environment. It removes the functionality previously added to the Lucy backend.

Specified by:

unplugFrom in class ALcyAddOn

Parameters:

aLucyEnv - The lucy environment to unplug from.

See Also:

ALcyAddOn.plugInto(com.luciad.lucy.ILcyLucyEnv)

clearUserPreferences

public void clearUserPreferences()

Clears all user preferences for the current user.

clearSystemPreferences

public void clearSystemPreferences()

Clears all system preferences.

encodeUserPreferences

public void encodeUserPreferences()

Encodes the user preferences (TLcyPreferencesManager.getCurrentUserPreferences()) to the persistent store. This method is automatically invoked when Lucy is exited.

encodeSystemPreferences

public void encodeSystemPreferences()

Encodes the system preferences (TLcyPreferencesManager.getSystemPreferences()) to the persistent store. This method is automatically invoked when Lucy is exited.

decodeSystemPreferences

public void decodeSystemPreferences()

Decodes the system preferences from the persistent store into TLcyPreferencesManager.getSystemPreferences(). This method is automatically invoked when the addon is plugged.

decodeUserPreferences

public void decodeUserPreferences()

Decodes the user preferences from the persistent store into TLcyPreferencesManager.getCurrentUserPreferences(). This method is automatically invoked when the addon is plugged.