You can specify the desired values of client setting using the back-end administration system of your choice.
If your back-end administration system is Portal Policy Manager, you can use the Policy Type Editor for Eclipse Preferences to set the values. See Managing Rich Client Preferences using the Policy Type Editor for Eclipse Preferences
for more information. All values from the Portal Policy Manager will be treated as if they were specified as read-only. If your back-end administration system is Domino®, you will specify your settings in the policy subsystem of the Domino Administration client.
Eclipse preferences are accessed using a qualifier (typically plug-in name), and optionally a scope, which determine the storage location of the preference. To have your settings values read by the client applications, they need to be stored in the same place that the client is looking for them. There are two possible ways to determine this information:
- Look in the application's documentation to see if a list of settings has been published or request a list from the application developer.
- Figure out the names of the qualifiers and settings yourself by changing values in the preference panels and other user interface controls provided by the application and examining the resulting changes in the Eclipse Preference store.
The managed settings framework enables administrators to control settings in the following scopes:
- Configuration – Preferences that are stored per installation of the platform. They are shared between workspaces.
- Instance – Preferences that are stored per workspace, or per running instance of the platform.
- It may be possible for custom scopes to be managed as well, depending on their implementation.
ManagedSettingsScope is a custom scope, for use by the managed settings framework and managed settings-aware applications. Its data is obfuscated to discourage end-user tampering. Applications which access their settings using this scope instead of using the standard Eclipse scopes, will be prevented from changing read-only settings. Read-only settings are stored in the managed settings scope as well as the associated standard scope.
A Setting Group is a group of related settings. When the managed settings framework retrieves a setting from a back-end system, the setting group it belongs to is the unit that is retrieved, not the individual setting. The structure of a settings group depends on the back-end system that generates the settings contained by it and the implementation of the provider associated with that back-end system. For example, for the Portal provider, a setting group is equivalent to a policy type.
If you are specifying managed settings in the Portal Policy Manager using the Policy Type Editor for Preferences, there are separate attributes for scope and qualifier that you can set explicitly. For instructions, see Managing Rich Client Preferences using the Policy Type Editor for Eclipse Preferences
. For this provider, a setting group maps to the PreferenceSet, which maps to the policy name. When setting up your preference sets, it is important for deletion tracking that all settings with the same qualifier go in the same preferenceSet. All settings that are retrieved from the Portal Policy Manager will be treated as read-only.
If you are specifying managed settings with the XML File provider, you should make the setting group name match the qualifier (usually plug-in ID). If the scope is not instance scope, you should prepend the name of the scope plus a forward slash character (/) to the name of the setting group.
<settingGroup name="org.eclipse.ui" lastModDate="20060131">
<setting name="showIntro" value="false" isLocked="false"/>
<settingGroup name="configuration/com.isv.my.plugin"" lastModDate="20060131">
<setting name="use_large_icons" value="true" isLocked="true"/>
<setting name="sortOrder" value="descending" isLocked="false"/>
is specified as true, the setting will be treated as read-only. For more information about the XML file provider, see Configuring the XML file provider
If you are using a different back-end administrative settings system and your environment allows you to control the name of the setting groups (which ever the concept of a setting group happens to be for that system), it is most efficient to name the setting group after the qualifier that will be used to access the settings on the client. If the settings need to be stored in a scope other than instance scope, you should prepend the scope name and a forward slash character (/) to the name.
For example, if you specify a setting group name of org.eclipse.help.ui
, the framework stores all the settings for that group in instance scope using a qualifier of org.eclipse.help.ui
. If you specify a setting group name of configuration/org.eclipse.core.internal.preferences.osgi
, the framework stores all the settings for that group in configuration scope using a qualifier of org.eclipse.core.internal.preferences.osgi
If it is not feasible to name the setting group to match the qualifier, you can specify the qualifier by prepending it to each setting name, separating the qualifier and setting name with a forward slash character (/). For example, you could name the setting group, All My Eclipse Preferences
and name one of its settings, org.eclipse.core.help.base/bookmarks
. You could name another setting, org.eclipse.ui/showIntro
. As a result, both settings, bookmarks and showIntro are retrieved together as part of the same setting group, but the former is stored with a qualifier of org.eclipse.core.help.base
and the latter with a qualifier of org.eclipse.ui
- Prepending the scope to the setting group name – The scope applies to all the settings in the setting group. For example: configuration/org.eclipse.core.runtime
- Prepending the scope to the setting name – If you prepend the scope to an individual setting, you must also specify the qualifier for the setting, even if it matches the setting group name. For example: configuration/org.eclipse.core.help.base/bookmarks
The following table contains example values of settings specified by an administrator:
Table 1. Example values
|Setting name||Group/qualifier = com.isv.existing.plugin|
The following resulting locations are created in the standard scopes of the Eclipse Preference store based on the administrator's settings in the table above:
|- use_large_icons = true
|- sort_order = descending
|- color_scheme = ocean
|- max_windows = 5
If this naming scheme for specifying scopes and qualifiers is not feasible in your back-end settings system, for instance, if there is a character limit that is too short, you can write your provider so that it translates between the format that you are able to use and the format that is described above.
Note that any forward slash characters (/) in your setting name other than those that delineate the scope and qualifier will be treated as subnodes of the qualifier. If your intent is to have a literal forward slash characters (/) in the setting name, you need to use two forward slash characters ) instead.
Limitations on qualifiers
The following are the limitations on qualifiers:
- It is very important that a qualifier not exist in more than one setting group.
- Qualifier names can not be "instance", "configuration", "default", "ManagedSettings", or any other names that are used as scope names.
If you remove settings from the setting group, they will remain on the client but any read-only settings will be changed to readable. If you remove a whole setting group, all the settings in that setting group will remain on the client but any read-only settings will be changed to readable.
If you change the value of a non-read-only setting and then end user has modified the setting, your update will not be applied, unless you also change the setting to read-only.
Parent topic: Configuring managed settings: XPD621