1. Eclipse Preferences

1.1. Preferences and scopes

The Eclipse platform supports
preferences
for persisting data between application restarts. Preferences are
stored as
key / value
pairs. The key is an
arbitrary
String. The value
can be a
boolean, String, int or
another
primitive type. For
example the
user
key may point to the value
vogella.

The preference support in Eclipse is based on the
Preferences
class from the
org.osgi.service.prefs
package. Eclipse
preferences
are
very
similar to standard Java
Preferences but use the
Eclipse
framework
to save and
retrieve
the
configuration and support
scopes.

The scope defines
how the
preference data is stored and how it is
changeable. The Eclipse runtime defines three scopes. The different
scopes are explained in the following table.

Table 1. Eclipse Preference scope

Scope

Description

Instance scope

If the user runs the same program twice, the
settings
between the
two programs may be different.

Configuration scope

If the user runs the same program twice,
then the settings
between
the two programs are identical.

Default scope

Default values which can not be changed.
Supplied via
configuration files in plug-ins and product
definitions.

1.2. Storage of the preferences

Eclipse stores the preferences in the workspace of your
application in
the
.metadata/.plugins/org.eclipse.core.runtime/.settings/
directory in the
<nodePath>.prefs
file.

The <nodePath>
is by default the Bundle-SymbolicName of the plug-in but can be
specified via the preference API.
The workspace is by default the
directory
in which the
application starts.

You can configure the storage location of the preferences
via the
-data path
launch parameter in Eclipse. To place the preferences in the user
home directory use the
-data @user.home
parameter setting.

1.3. Eclipse preference API

You can create and manipulate preferences directly via
Singletons
provided by the Eclipse runtime. You have the
InstanceScope,
ConfigurationScope
and
DefaultScope
classes which give access to the corresponding instance via the
INSTANCE
field.

Preference values are read and saved by
get()
and
put()
methods. In the
get()
method you specify a default value in case the key can not be
found.
The
clear()
method removes all preferences and the
remove()
method allows you
to delete a selected preference value. Via the
flush()
method you persist the preferences to the file system.

2. Persisting data with dependency injection

The Eclipse platform allows you to use dependency injection for
preferences handling.

Preference values are not stored directly in the
IEclipseContext
but contributed by an
ExtendedObjectSupplier. This implies that
you have to use a special annotation
@Preference
to access them. The
@Preference
must be used together with
@Inject
or one of the other annotations which implies dependency injection,
e.g.
@Execute.

The
@Preference
annotation allows you to specify the
nodePath
and the
value
as optional parameters.

The
nodePath
is the file name
used to save the
preference values to disk.
By default
this is
the
Bundle-SymbolicName of the plug-in. The
value
parameter specifies the preference key for the value which should be
injected.

Eclipse can also inject the
IEclipsePreference
object. You can use this object for storing values. If you use the
value
parameter, Eclipse injects the value directly. Use the
value
parameter for read access, while for storing or changing values, use
the
IEclipsePreference
object.

Warning

For accessing the
IEclipsePreference
object you still have to use the
@Preference
annotation.
@Inject
alone is not sufficient.

The following code snippet demonstrates how to put values into
the preferences store.

The Eclipse platform automatically tracks the values and re-injects
them
into fields and methods if they change.
Eclipse
tracks
changes of
preferences
in the
InstanceScope
and
ConfigurationScope
scope.
Preference values
in the
DefaultScope
are not tracked.

If you use the injected
IEclipseContext
to store new preference values, these
values are stored in the instance
scope.

3. Preference handling in Eclipse 3.x

3.1. Preference Page

To add a page to this preference dialog a
plug-in must provide an
contribution to the
org.eclipse.ui.preferencePages
extension point.

This extension point defines a class which
is
responsible for creating
a user interface and storing the preference values.
This
class must
implement
IWorkbenchPreferencePage
and must have a non-parameter constructor.

The
PreferencePage
class or one of its subclasses can get extended; a good
template is
usually
FieldEditorPreferencePage.

To open the Preference dialog, you can use the
org.eclipse.ui.window.preferences
command.

3.2. Secure storage of preferences

The key / value pairs will be stored in the
secure.storage
file in
the
.eclipse/org.eclipse.equinox.security
folder of the users home
directory.
Eclipse uses a class of type
PasswordProvider
for encrypting the preferences and has a default class registered.

Via the
org.eclipse.equinox.security.secureStorage
extension point
you can register your
own
PasswordProvider.

3.3. Access Preferences in different plug-ins

You can access preferences in other plug-ins via the
PreferenceService
service.

For example, to access the "MySTRING1" preference in the
"de.vogella.preferences.page" plug-in, you can use the
following:

4. Persistence of part state

Eclipse provides the
@PersistState
annotation. This annotation can be applied to a method in a class
referred to by a part.

Such an annotated method can be used to store the instance state of
the part.
The Eclipse
framework calls such a method whenever the part or
the application
closes. The
stored information can be used in the
method
annotated with the
@PostConstruct
annotation. A typical use case for such a method would be to store the
state of
a checkbox.

The usage of this annotation is demonstrated in the following
example code.

6. Setting preferences via plugin_customization.ini

You
can use a file to set the default values of preferences. The file
which
contains these defaults is typically named
plugin_customization.ini.

Such a file needs
to
be registered via the
preferenceCustomization
property on the product extension point in the
plugin.xml
file. This is demonstrated in the following screenshot.

The format to use is
<plugin id>/<setting>=<value>,
e.g.
com.example.e4.rcp.todo/user=vogella.

Tip

To find the correct keys, just start your Eclipse application,
switch
to the
.metadata
directory in your workspace directory (by
default the directory your
application is starting in) and search for
files ending with
.pref.

7. Tutorial: Preferences via code

You can create, store and retrieve preference values directly via
your
coding. The following gives an example for this. Create an Eclipse
composite with three buttons. Use this composite in one of your parts
(View or Editor).

The first
Button
will set the preference values. The next will display the values and
the last will clear the preference values.

8. Exercise: Contribute preference page to the Eclipse IDE

In the following exercise you create a plug-in with a preference
pages
which
allows the user to maintain certain settings. This exercise
assumes that you are already familiar with Eclipse plug-in
development
for the Eclipse IDE.

Create a new plug-in project called
de.vogella.preferences.page. Make sure you flag the "Generate an
activator..." during the project
creation. Use no template.

Go to the
plugin.xml
file and add the extension
org.eclipse.ui.preferencePages
with the following settings.

Enter the following code for your class
MyPreferencePage1.
Method
init()
sets
the preferences store and the method
createFieldEditors()
registers pre-defined editors for
values.
checkState()
allows to perform a validations. To get notified about
value changes
you need to override the propertyChange method.

Start a runtime Eclipse IDE with your plug-in and ensure that
you see your preference page in the preference settings of the Eclipse
IDE.
Validate that maintained values are stored even if
you restart
your
application.

Add a command
showPreferenceValues
with the following
handler
to the menu. This command demonstrates how to
access preferences
values from
the
preferencePage.

To set the default values for preferences use the extension
point
org.eclipse.core.runtime.preferences. Create a new
initializer with the following class
de.vogella.preferences.page.preferencepage.MyInitializer.

10. About this website

10.1. Donate to support free tutorials

Please consider a contribution
if this article helped you. It will help to maintain our content and our Open Source activities.

10.2. Questions and discussion

Writing and updating these tutorials is a lot of work.
If this
free community service was helpful,
you can support the cause by
giving
a tip
as well as reporting typos and factual errors.

If you find errors in this tutorial, please notify me
(see the
top of the page).
Please note that due to the high volume of feedback I
receive, I
cannot answer questions to your implementation. Ensure you
have read
the
vogella FAQ
as
I don't respond to questions already answered there.