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.

The TLcyPreferencesTool offers three kinds of preferences:

The system and user preferences are automatically loaded from the configuration source when the tool is plugged in. It uses the central ILcyPropertiesDecoder available in the TLcyPreferencesManager to decode these configuration sources, which by default interprets the configuration sources as files relative to the classpath.

For more detail on TLcyPreferencesManager and its different kinds of preferences, see The Preferences mechanism. Workspaces are discussed in detail in the Workspaces documentation.

Usage

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 getSystemPreferences, getUserPreferences and getWorkspacePreferences methods.

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.

The 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.

preferences workspace composite
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

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.

Persisting preferences

The user and system preferences of TLcyPreferencesManager are 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 TLcyPreferencesManager, 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 null.

The Workspaces documentation contains an example of how to use the preferences in an add-on and how to store state in the workspace.