The platform and application plug-ins can use Eclipse preferences for storage of configurable information. Examples can include window settings, server locations, and synchronization settings.
Eclipse is an open source community committed to implementation of a universal development platform.
Eclipse preferences are managed in a tree format. The first nodes after the root are called scopes
. The scopes each define a subtree. The default scopes provided by Eclipse are default
, and project
. Under each of the scopes, the preferences tree is typically organized by plug-in identify. Associating preference keys and values with a particular plugin will help to eliminate naming collisions.
The product adds an additional scope called ManagedSettings
. See Configuring managed settings
for more information.
Instance scope is stored per workspace, while the configuration scope is stored in the configuration directory. Because the platform install configuration sets the configuration directory to be a directory in the workspace, instance
scopes are effectively equivalent.
You can search preferences by name, and the scopes can be searched in a particular order. A typical search order would be instance
, then default
How are preferences set?
Preferences are set through the code, often as a result of interactions with preference pages. However, plug-ins can internally use preferences, and not surface those preferences through user interactions.
How are default preference values set?
The following list describes the several ways in which default preference values can be set for a particular plug-in. They are listed in the order in which they are processed. A default preference set at the lowest level (for example, Runtime defaults) is over-ridden by the same preference set at a higher level (for example, Product defaults).
These are specified by code, such as contained in a plug-in class or in a preference initializer supplied as an extension to the org.eclipse.core.runtime.preferences extension pointBundle defaults
Default values specified in preferences.ini files in the plug-in.Product defaults
Default values specified in the customization file supplied by the product.Command line defaults
Default values specified in a plug-in customization file specified on the command line.
Once the developer has created the plug-in, at application assembly time, the assembler might choose to add preferences.ini files to the plug-in to override whatever the developer may have set.
Once plug-ins are deployed to a client system, it is strongly discouraged that the plug-in contents are updated. Therefore, after deployment of the plug-ins, the only applicable way to override preference default values is through the command line plug-in customization file. See Updating the plugin_customization.ini file
For the client platform, the plugin_customization.ini is contained in the <installdir
After the client platform has been deployed, this file can be changed through the following methods:
How are project, instance and configuration preference values set?
Settings in the project
scopes are typically made as a result of user interactions, such as through the preferences dialog. The plug-in code will need to use appropriate methods to search install
scopes prior to using the default values.
Project preference values are typically not used by most platform and application components. Project level preferences are most often associated with code creation or application assembly tools that maintain a concept of projects, such as the Eclipse SDK.
preference values can be queried after deployment using the preferences jobs supplied by the Client Management server. See Getting an inventory of Eclipse preferences
for more information.
You can add, update, or remove project, instance, and configuration preference values using the following mechanisms:
What about user-defined or custom scopes?
Applications can define additional custom scopes for storing preferences. The ManagedSettings scope defined by this product platform is an example of a custom scope. The preferences jobs and policy settings are used by the Eclipse preferences APIs to query and effect changes on the preferences values. The APIs will typically work for other scopes, unless the other scopes are providing additional restrictions. If an application is providing their own custom scope for preferences, the management operations supplied by the Client Management server or the policy settings may not always perform successfully. Refer to the application for more information on how to manage values in its custom scope during deployment and post-deployment operations.
Parent topic: Managing client configurations: XPD621