Eclipse Plug-in Developer Guide (Galileo) - IPreferencesService (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.core.runtime.preferences
Interface IPreferencesService

public interface IPreferencesService

The preference service provides facilities for dealing with the default scope precedence lookup order, querying the preference store for values using this order, accessing the root of the preference store node hierarchy, and importing/exporting preferences.

The default-default preference search look-up order as defined by the platform is: project, instance, configuration, default.

This interface is not intended to be implemented by clients.

Since:: 3.0
Restriction:: This interface is not intended to be implemented by clients.
Restriction:: This interface is not intended to be extended by clients.

Method Summary

void applyPreferences ( IEclipsePreferences node, IPreferenceFilter[] filters)
          Apply the preference tree rooted at the given node, to the system's preference tree.

IStatus applyPreferences ( IExportedPreferences preferences)
          Take the given preference tree and apply it to the Eclipse global preference hierarchy.

void exportPreferences ( IEclipsePreferences node, IPreferenceFilter[] filters, OutputStream output)
          Export the preference tree rooted at the given node, to the specified output stream.

IStatus exportPreferences ( IEclipsePreferences node, OutputStream output, String[] excludesList)
          Exports all preferences for the given preference node and all its children to the specified output stream.

String get ( String key, String defaultValue, Preferences[] nodes)
          Lookup the given key in the specified preference nodes in the given order.

boolean getBoolean ( String qualifier, String key, boolean defaultValue, IScopeContext[] contexts)
          Return the value stored in the preference store for the given key.

byte[] getByteArray ( String qualifier, String key, byte[] defaultValue, IScopeContext[] contexts)
          Return the value stored in the preference store for the given key.

String[] getDefaultLookupOrder ( String qualifier, String key)
          Return an array with the default lookup order for the preference keyed by the given qualifier and simple name.

double getDouble ( String qualifier, String key, double defaultValue, IScopeContext[] contexts)
          Return the value stored in the preference store for the given key.

float getFloat ( String qualifier, String key, float defaultValue, IScopeContext[] contexts)
          Return the value stored in the preference store for the given key.

int getInt ( String qualifier, String key, int defaultValue, IScopeContext[] contexts)
          Return the value stored in the preference store for the given key.

long getLong ( String qualifier, String key, long defaultValue, IScopeContext[] contexts)
          Return the value stored in the preference store for the given key.

String[] getLookupOrder ( String qualifier, String key)
          Return an array with the lookup order for the preference keyed by the given qualifier and simple name.

IEclipsePreferences getRootNode ()
          Return the root node of the Eclipse preference hierarchy.

String getString ( String qualifier, String key, String defaultValue, IScopeContext[] contexts)
          Return the value stored in the preference store for the given key.

IStatus importPreferences ( InputStream input)
          Loads preferences from the given file and stores them in the preferences store.

IPreferenceFilter[] matches ( IEclipsePreferences node, IPreferenceFilter[] filters)
          Return a list of filters which match the given tree and is a subset of the given filter list.

IExportedPreferences readPreferences ( InputStream input)
          Read from the given input stream and create a node hierarchy representing the preferences and their values.

void setDefaultLookupOrder ( String qualifier, String key, String[] order)
          Set the default scope lookup order for the preference keyed by the given qualifier and simple name.

Method Detail

get


String get(
String key,
           
String defaultValue,
           
Preferences[] nodes)

Lookup the given key in the specified preference nodes in the given order. Return the value from the first node the key is found in. If the key is not defined in any of the given nodes, then return the specified default value.

Immediately returns the default value if the node list is null. If any of the individual entries in the node list are null then skip over them and move on to the next node in the list.

Parameters:: key - the preference key; defaultValue - the default value; nodes - the list of nodes to search, or null
Returns:: the stored preference value or the specified default value
See Also:: Preferences

getBoolean

boolean getBoolean(
String qualifier,
                   
String key,
                   boolean defaultValue,
                   
IScopeContext[] contexts)

Return the value stored in the preference store for the given key. If the key is not defined then return the specified default value. Use the canonical scope lookup order for finding the preference value.

The semantics of this method are to calculate the appropriate Preferences nodes in the preference hierarchy to use and then call the get(String, String, Preferences[]) method. The order of the nodes is calculated by consulting the default scope lookup order as set by setDefaultLookupOrder(String, String, String[]).

The specified key may either refer to a simple key or be the concatenation of the path of a child node and key. If the key contains a slash ("/") character, then a double-slash must be used to denote the end of they child path and the beginning of the key. Otherwise it is assumed that the key is the last segment of the path. The following are some examples of keys and their meanings:

"a" - look for a value for the property "a"
"//a" - look for a value for the property "a"
"///a" - look for a value for the property "/a"
"//a//b" - look for a value for the property "a//b"
"a/b/c" - look in the child node "a/b" for property "c"
"/a/b/c" - look in the child node "a/b" for property "c"
"/a/b//c" - look in the child node "a/b" for the property "c"
"a/b//c/d" - look in the child node "a/b" for the property "c/d"
"/a/b//c/d" - look in the child node "a/b" for the property "c/d"
"/a/b//c//d" - look in the child node "a/b" for the property "c//d"

Callers may specify an array of scope context objects to aid in the determination of the correct nodes. For each entry in the lookup order, the array of contexts is consulted and if one matching the scope exists, then it is used to calculate the node. Otherwise a default calculation algorithm is used.