[platform-ui-dev] new plug-in preferences mechanim

[Jim_des_Rivieres@xxxxxxx]

The 20020411 build contains a new mechanism for maintaining preferences
(or other configuration parameter settings) with each plug-in. All plug-in
developers should be aware of this new mechanism, and should consider 
whether
they should write (or change) their plug-in to use it.

A similar mechanism in org.eclipse.ui.AbstractUIPlugin has existed since
Eclipse 1.0 for UI plug-ins. Since this mechanism was generally useful,
we have pushed it down into the Core runtime. This entailed copying and
renaming the interesting code to maintain the proper layering of UI atop 
Core.

A new API class, called Preferences, has been added to 
org.eclipse.core.runtime.
This concrete class, based on 
org.eclipse.jface.preference.PreferenceStore,
provides the basic 2-level mechanism for maintaining both current values 
and
default values for an arbitrary set of named properties. The underlying
implementation is based on java.io.Properties.

Two new public API methods have been added to Plugin:

        getPluginPreferences() returns the preferences for the plug-in
        savePluginPreferences() saved modified preferences to disk

Each plug-in has its own preference store and gets an opportunity to
establish default values for its preferences by overriding the protected
API method

        initializeDefaultPluginPreferences() sets defaults preference 
values

A couple of notes:

(1) The preference object is only created and initialized if someone 
requests
it by calling getPluginPreferences(). Plug-ins that do not access their
preferences incur no overhead.

(2) Modified preferences are not saved automatically on plug-in shutdown.
Recommended practice is to explicitly call savePluginPreferences() soon
after making changes, rather than wait until plug-in shutdown. This 
ensures
that changed preference setting are stored on disk immediately and will be
retained even in the event of an Eclipse platform crash.

(3) The platform has other mechanisms that allow default settings for
a plug-in's preferences to be set from outside the plug-in (either by the
primary feature or from the command line). The externally supplied 
defaults
are applied after the plug-in's initializeDefaultPluginPreferences() has
been called, and therefore overrides any default settings established
in initializeDefaultPluginPreferences(). The idea is to allow a primary
feature (i.e., an end-product) to customize any plug-in's default settings
to tailor it appropriately for the operating environment.

(4) Take "preferences" with a grain of salt: there is no requirement
that these properties be surfaced to end users, either via workbench
preference pages or command line options. The mechanism is intended to be
used for internal plug-in configuration parameters as well. (They are
called "preferences" mainly for historical reasons; "properties" would 
have
risked confusion with resource properties and with java.io.Properties).

(5) Existing subclasses of AbstractUIPlugin continue to work as before.
It is recommended that all UI plug-ins switch to using the new Core 
preferences
mechanism at some point, since there is likely no compelling reason or 
advantage to sticking with the older JFace preferences mechanism.

Each plug-in writer should decide whether their plug-in will have any 
preferences, and document the names and significance of any of its 
preferences
(treat as API) so the default values could be customized externally.

Like a plug-in's extension points, externally available preferences should 
be
documented in the HTML doc for the plug-in itself (e.g., in 
doc/com_example_myplugin.html in the directory for the 
com.example.myplugin
plug-in).