HierarchicalPreferences

= Hierarchical Preferences =

PageOutline

Eclipse has a preference system that allows each plugin to provide default settings. The builder of a "product" can then add site-specific settings, and finally the user might be able to adjust them. This describes the suggested use for CSS.

Note that the following is a technical view of preference settings: How they are originally defined and then adjusted on several levels, i.e. the information that CSS developers need. As an end user, you might want to read this from the back, jumping right away to the "End User Settings" section. As somebody who downloaded some generic version of CSS and wants to provide all the settings for his/her site, you would follow the "Slight Tweaks to the Site Defaults" section.

== Plugin Defaults ==

Each plugin with configurable settings has a file "preferences.ini" that

1. Defines those settings, i.e. their name
2. Documents their meaning, supported values
3. Establishes the default

{{{

Example preferences.ini for plugin org.csstudio.demo

Enable the super feature.

Set to 'on', 'off' or 'automatic' which enables it whenever possible

enable_super=automatic

URL of server where the super feature connects

url=http://localhost/superdata }}}

The Eclipse preference service for a plugin will automatically use this file.

Note that Eclipse offers more ways to establish defaults, which are discouraged for CSS:

1. Defaults hardcoded in calls to the preference service. These are difficult to find in the code.
2. Preference Initializer defined in plugin.xml. This again hides the preference tags and their default values in the code.

Putting the defaults into preferences.ini seems the best way to define and document them.

== Product (Site) Defaults == When bundling plugins into a site-specific product, a file "plugin_customization.ini" in the product plugin is automatically used by Eclipse to override settings.

{{{

Example plugin_customization.ini

Override defaults of plugin org.csstudio.demo:

URL of our super feature server

org.csstudio.demo/url=http://my.site.org/mysuperdata }}}

This way, "your" product has the settings for "your" site built-in.

If you wonder about the names of preference settings supported by each plugin, consult the preferences.ini of the respective plugin.

== Slight Tweaks to the Site Defaults == If a select installation at a site requires a few extra changes, for example a test network installation needs settings that differ from your main campus network, put those into a file with the same format as "plugin_customization.ini", for example "testnet.ini", and run the product with a command-line option

{{{ my_product -pluginCustomization /path/to/testnet.ini }}}

== End User Settings == Finally, the GUI code can offer Preference Pages via which the end user can change the settings. Typically, these end-user settings are saved in the [wiki:Workspaces user's workspace], i.e. they persist for the user but don't change the settings of other users or even the site-wide defaults. Details depend on the preference store that the code uses when creating the preference page.

---

== Note: Passwords == The CSS !SecureStorage and !PasswordFieldEditor allow to keep preferences for passwords encrypted. It is for example used to store passwords for accessing the relational database of the SNS alarm and archive system. The typical use case is like this:

• System administrator installs CSS
• System administrator starts CSS and enters the passwords once in the preference GUI Since the !SecureStorage and !PasswordFieldEditor store the passwords in an encrypted file in the CSS install location, these passwords now apply to all instances of CSS. Contrary to the default way of storing preference settings from the GUI, they are not held in the user's workspace, so there is no need for each user to know and enter the passwords again.