The Lucy framework provides the
TLcyPreferencesTool support class for add-ons that need to work with preferences.
It offers the add-on a single point of contact with the different kinds of preferences in a Lucy application.
It automatically loads the initial preferences from the configuration source and automatically stores the changed preferences
in the correct preferences stores.
TLcyPreferencesTool offers three kinds of preferences:
Workspace preferences: preferences put in this
ALcyPropertiesinstance are automatically saved in and restored from the workspace.
The system and user preferences are automatically loaded from the configuration source when the tool is plugged in. It uses
ILcyPropertiesDecoder available in the
TLcyPreferencesManager to decode these configuration sources, which by default interprets the configuration sources as files relative to the classpath.
To use the
TLcyPreferencesTool, instantiate it with the right configuration source name and prefixes, and the initial configuration of the user and system
preferences will be loaded from the configuration source. In the default setup of Lucy, this means that the system preferences
are read from the file specified by the configuration source name, "configSourceName.cfg" for example, and the user preferences
from the file specified by the configuration source name with ".userPrefs." inserted before the extension of configuration
file name, "configSourceName.userPrefs.cfg" for example. The preferences can then be accessed with the
It is up to the add-on to decide which preferences are system preferences, user preferences or workspace preferences. The
TLcyPreferencesTool only makes the distinction between these preferences with regards to priority: the workspace preferences in the
TLcyPreferencesTool 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.
TLcyPreferencesTool implements this priority in its composite preferences. The
getCompositeWorkspacePreferences method returns an
ALcyProperties instance that tries to retrieve a value for a given key first in the workspace preferences. It will search in the user preferences
only if the requested preference is not available in the workspace preferences. Finally, if the preference is not available
in the user preferences either, the system preferences are searched. Figure 1, “The "ShortPrefix.stringPref" key is not present in the workspace preferences, so the composite preferences retrieves
it from the user preferences where it is available” shows this schematically. All preferences saved in this
ALcyProperties object are saved in the workspace preferences.
The user and system preferences of
String-based, and for workspaces the
TLcyPreferencesTool also saves all workspace preferences as
String instances. However, the user, system and workspace preferences of the
TLcyPreferencesTool are all
ALcyProperties instances that can accept any kind of object as the value for a preference. When the preferences need to be saved, to the
workspace or to the user or system preferences of the
TLcyPreferencesTool uses its
TLcyCompositePropertyConverter to convert these values to
String instances. An add-on that saves objects in any of the preferences of the
TLcyPreferencesTool should add
ILcyPropertyConverter instances to the composite property converter of the tool.
It can also be useful to have access to the
ALcyWorkspaceCodec when converting
Object properties to
String properties, as the
ALcyWorkspaceCodec can provide 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
The Workspaces documentation contains an example of how to use the preferences in an add-on and how to store state in the workspace.