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 are treated as if they are specified as read-only. If your back-end administration system is IBM
®, you specify your settings in the policy subsystem of the Lotus Domino
Eclipse preferences are accessed using a qualifier (typically a 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 documentation of the application to see if a list of settings has been published or to 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 might 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 user tampering. Applications that access their settings using this scope instead of using the standard Eclipse scopes are prevented from changing read-only settings. Read-only settings are stored in the managed settings scope and 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 are treated as read-only.
If you are specifying managed settings with the XML File provider, make the setting group name match the qualifier (typically the plug-in ID). If the scope is not instance scope, add a prefix to 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 is 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 (for whatever 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 is used to access the settings on the client. If the settings need to be stored in a scope other than instance scope,add a prefix to 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 adding a prefix 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
- Adding a prefix to 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
- Adding a prefix to the scope to the setting name – If youadd a prefix to 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 settings in the table:
|- 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.
Any forward slash characters (/) in your setting name other than those characters that delineate the scope and qualifier are 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 important that a qualifier does not exist in more than one setting group.
- Qualifier names cannot be "instance," "configuration," "default," "ManagedSettings," or any other names that are used as scope names.
If you remove settings from the setting group, they remain on the client, but any read-only settings are changed to readable. If you remove a whole setting group, all the settings in that setting group remain on the client, but any read-only settings are changed to readable.
If you change the value of a non-read-only setting and then user has modified the setting, your update is not applied, unless you also change the setting to read-only.
Parent topic: Configuring managed settings