org.eclipse.core.internal.preferences

Class PreferencesService

java.lang.Object

org.eclipse.core.internal.preferences.PreferencesService

All Implemented Interfaces:

IPreferencesService

public class PreferencesService
extends java.lang.Object
implements IPreferencesService

Since:

3.0

Method Summary

Modifier and Type	Method and Description
void	applyPreferences(IEclipsePreferences tree, 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.
java.lang.ref.WeakReference<java.lang.Object>	applyRuntimeDefaults(java.lang.String name, java.lang.ref.WeakReference<java.lang.Object> pluginReference)
IEclipsePreferences	createNode(java.lang.String key)
void	exportPreferences(IEclipsePreferences node, IPreferenceFilter[] filters, java.io.OutputStream stream) Export the preference tree rooted at the given node, to the specified output stream.
IStatus	exportPreferences(IEclipsePreferences node, java.io.OutputStream output, java.lang.String[] excludesList) Exports all preferences for the given preference node and all its children to the specified output stream.
java.lang.String	get(java.lang.String key, java.lang.String defaultValue, Preferences[] nodes) Lookup the given key in the specified preference nodes in the given order.
boolean	getBoolean(java.lang.String qualifier, java.lang.String key, boolean defaultValue, IScopeContext[] scopes) Return the value stored in the preference store for the given key.
byte[]	getByteArray(java.lang.String qualifier, java.lang.String key, byte[] defaultValue, IScopeContext[] scopes) Return the value stored in the preference store for the given key.
static PreferencesService	getDefault()
java.lang.String[]	getDefaultDefaultLookupOrder()
java.lang.String[]	getDefaultLookupOrder(java.lang.String qualifier, java.lang.String key) Return an array with the default lookup order for the preference keyed by the given qualifier and simple name.
double	getDouble(java.lang.String qualifier, java.lang.String key, double defaultValue, IScopeContext[] scopes) Return the value stored in the preference store for the given key.
float	getFloat(java.lang.String qualifier, java.lang.String key, float defaultValue, IScopeContext[] scopes) Return the value stored in the preference store for the given key.
int	getInt(java.lang.String qualifier, java.lang.String key, int defaultValue, IScopeContext[] scopes) Return the value stored in the preference store for the given key.
long	getLong(java.lang.String qualifier, java.lang.String key, long defaultValue, IScopeContext[] scopes) Return the value stored in the preference store for the given key.
java.lang.String[]	getLookupOrder(java.lang.String qualifier, java.lang.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.
java.lang.String	getString(java.lang.String qualifier, java.lang.String key, java.lang.String defaultValue, IScopeContext[] scopes) Return the value stored in the preference store for the given key.
IStatus	importPreferences(java.io.InputStream input) Loads preferences from the given file and stores them in the preferences store.
IPreferenceFilter[]	matches(IEclipsePreferences tree, IPreferenceFilter[] filters) Return a list of filters which match the given tree and is a subset of the given filter list.
IExportedPreferences	readPreferences(java.io.InputStream input) Read from the given input stream and create a node hierarchy representing the preferences and their values.
void	setDefaultDefaultLookupOrder(java.lang.String[] order)
void	setDefaultLookupOrder(java.lang.String qualifier, java.lang.String key, java.lang.String[] order) Set the default scope lookup order for the preference keyed by the given qualifier and simple name.
void	setRegistryHelper(java.lang.Object registryHelper)
IStatus	validateVersions(IPath path)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getDefault

public static PreferencesService getDefault()

applyPreferences

public void applyPreferences(IEclipsePreferences tree,
                             IPreferenceFilter[] filters)
                      throws CoreException

Description copied from interface: IPreferencesService

Apply the preference tree rooted at the given node, to the system's preference tree. The list of preference filters will act as a filter and only preferences in the tree which apply to at least one filter in the list, will be applied.

If the list of filters is null or empty then do nothing.

Before the tree is applied to the global preference tree, the registered PreferenceModifyListener objects are called and given the opportunity to modify the tree.

Specified by:

applyPreferences in interface IPreferencesService

Parameters:

tree - the tree to consider applying

filters - the filters to use

Throws:

CoreException

See Also:

IPreferencesService.applyPreferences(IExportedPreferences), IPreferencesService.readPreferences(InputStream), IPreferenceFilter, PreferenceModifyListener

applyPreferences

public IStatus applyPreferences(IExportedPreferences preferences)
                         throws CoreException

Description copied from interface: IPreferencesService

Take the given preference tree and apply it to the Eclipse global preference hierarchy. If a node is an export root, then treat the operation for that node as an overwrite rather than a merge. That is, remove the node from the global tree before adding any preferences contained in it or its children.

The given preferences object must not be null.

Before the tree is applied to the global preference tree, the registered PreferenceModifyListener objects are called and given the opportunity to modify the tree.

Specified by:

applyPreferences in interface IPreferencesService

Parameters:

preferences - the preferences to apply globally

Returns:

status object indicating success or failure

Throws:

CoreException - if there are problems applying the preferences

See Also:

PreferenceModifyListener

applyRuntimeDefaults

public java.lang.ref.WeakReference<java.lang.Object> applyRuntimeDefaults(java.lang.String name,
                                                                          java.lang.ref.WeakReference<java.lang.Object> pluginReference)

createNode

public IEclipsePreferences createNode(java.lang.String key)

exportPreferences

public void exportPreferences(IEclipsePreferences node,
                              IPreferenceFilter[] filters,
                              java.io.OutputStream stream)
                       throws CoreException

Description copied from interface: IPreferencesService

Export the preference tree rooted at the given node, to the specified output stream. Apply the given list of preference filters, only exporting preference node and keys which are applicable to at least one filter in the list.

The given node and output stream must not be null. If the list of filters is null or empty then do nothing.

It is the responsibility of the client to close the given output stream.

Specified by:

exportPreferences in interface IPreferencesService

Parameters:

node - the tree to export

filters - the list of filters to export

stream - the stream to export to

Throws:

CoreException

See Also:

IPreferencesService.exportPreferences(IEclipsePreferences, OutputStream, String[]), IPreferencesService.readPreferences(InputStream), IPreferencesService.applyPreferences(IEclipsePreferences, IPreferenceFilter[]), IPreferencesService.applyPreferences(IExportedPreferences), IPreferenceFilter

exportPreferences

public IStatus exportPreferences(IEclipsePreferences node,
                                 java.io.OutputStream output,
                                 java.lang.String[] excludesList)
                          throws CoreException

Description copied from interface: IPreferencesService

Exports all preferences for the given preference node and all its children to the specified output stream. It is the responsibility of the client to close the given output stream.

If the given export list is null then all preferences for all sub-nodes of the given node are exported to the given stream. Otherwise the export list is consulted before exporting each preference value. If there is a string match then the preference is not exported. The exclusion can also occur at a per-node level. Wild cards are not accepted in the excludes list as a basic String compare is done. The basic algorithm is similar to the following:

 String fullPath = node.absolutePath() + '/' + key;
 if (!fullPath.startsWith(excludesList[i]))
        // export preference
 

The values stored in the resulting stream are suitable for later being read by the by IPreferencesService.importPreferences(InputStream) or IPreferencesService.readPreferences(InputStream) methods.

Specified by:

exportPreferences in interface IPreferencesService

Parameters:

node - the node to treat as the root of the export

output - the stream to write to

excludesList - a list of path prefixes to exclude from the export, or null

Returns:

a status object describing success or detailing failure reasons

Throws:

CoreException - if there was a problem exporting the preferences

See Also:

IPreferencesService.importPreferences(java.io.InputStream), IPreferencesService.readPreferences(InputStream)

get

public java.lang.String get(java.lang.String key,
                            java.lang.String defaultValue,
                            Preferences[] nodes)

Description copied from interface: IPreferencesService

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.

Specified by:

get in interface IPreferencesService

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

public boolean getBoolean(java.lang.String qualifier,
                          java.lang.String key,
                          boolean defaultValue,
                          IScopeContext[] scopes)

Description copied from interface: IPreferencesService

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 IPreferencesService.get(String, String, Preferences[]) method. The order of the nodes is calculated by consulting the default scope lookup order as set by IPreferencesService.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"

The scope look-up order is determined by the preference service default lookup order, not by the order of the scope contexts that are being passed in. The context objects are only consulted to help determine which nodes to look in, not the order of the nodes.

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.

An example of a qualifier for an Eclipse 2.1 preference is the plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")

Specified by:

getBoolean in interface IPreferencesService

Parameters:

qualifier - a namespace qualifier for the preference

key - the name of the preference (optionally including its path)

defaultValue - the value to use if the preference is not defined

scopes - optional context objects to help scopes determine which nodes to search, or null

Returns:

the value of the preference or the given default value

See Also:

IScopeContext, IPreferencesService.get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]), IPreferencesService.getLookupOrder(java.lang.String, java.lang.String), IPreferencesService.getDefaultLookupOrder(java.lang.String, java.lang.String)

getByteArray

public byte[] getByteArray(java.lang.String qualifier,
                           java.lang.String key,
                           byte[] defaultValue,
                           IScopeContext[] scopes)

Description copied from interface: IPreferencesService

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 IPreferencesService.get(String, String, Preferences[]) method. The order of the nodes is calculated by consulting the default scope lookup order as set by IPreferencesService.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"

The scope look-up order is determined by the preference service default lookup order, not by the order of the scope contexts that are being passed in. The context objects are only consulted to help determine which nodes to look in, not the order of the nodes.

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.

An example of a qualifier for an Eclipse 2.1 preference is the plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")

Specified by:

getByteArray in interface IPreferencesService

Parameters:

qualifier - a namespace qualifier for the preference

key - the name of the preference (optionally including its path)

defaultValue - the value to use if the preference is not defined

scopes - optional context objects to help scopes determine which nodes to search, or null

Returns:

the value of the preference or the given default value

See Also:

IScopeContext, IPreferencesService.get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]), IPreferencesService.getLookupOrder(java.lang.String, java.lang.String), IPreferencesService.getDefaultLookupOrder(java.lang.String, java.lang.String)

getDefaultLookupOrder

public java.lang.String[] getDefaultLookupOrder(java.lang.String qualifier,
                                                java.lang.String key)

Description copied from interface: IPreferencesService

Return an array with the default lookup order for the preference keyed by the given qualifier and simple name. Return null if no default has been set.

The lookup order returned is based on an exact match to the specified qualifier and simple name. For instance, if the given key is non-null and no default lookup order is found, the default lookup order for the qualifier (and a null key) is NOT returned. Clients should call IPreferencesService.getLookupOrder(String, String) if they desire this behavior.

Specified by:

getDefaultLookupOrder in interface IPreferencesService

Parameters:

qualifier - the namespace qualifier for the preference

key - the preference name or null

Returns:

the scope order or null

See Also:

IPreferencesService.setDefaultLookupOrder(String, String, String[]), IPreferencesService.getLookupOrder(String, String)

getDouble

public double getDouble(java.lang.String qualifier,
                        java.lang.String key,
                        double defaultValue,
                        IScopeContext[] scopes)

Description copied from interface: IPreferencesService

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 IPreferencesService.get(String, String, Preferences[]) method. The order of the nodes is calculated by consulting the default scope lookup order as set by IPreferencesService.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"

The scope look-up order is determined by the preference service default lookup order, not by the order of the scope contexts that are being passed in. The context objects are only consulted to help determine which nodes to look in, not the order of the nodes.

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.

An example of a qualifier for an Eclipse 2.1 preference is the plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")

Specified by:

getDouble in interface IPreferencesService

Parameters:

qualifier - a namespace qualifier for the preference

key - the name of the preference (optionally including its path)

defaultValue - the value to use if the preference is not defined

scopes - optional context objects to help scopes determine which nodes to search, or null

Returns:

the value of the preference or the given default value

See Also:

IScopeContext, IPreferencesService.get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]), IPreferencesService.getLookupOrder(java.lang.String, java.lang.String), IPreferencesService.getDefaultLookupOrder(java.lang.String, java.lang.String)

getFloat

public float getFloat(java.lang.String qualifier,
                      java.lang.String key,
                      float defaultValue,
                      IScopeContext[] scopes)

Description copied from interface: IPreferencesService

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 IPreferencesService.get(String, String, Preferences[]) method. The order of the nodes is calculated by consulting the default scope lookup order as set by IPreferencesService.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"

The scope look-up order is determined by the preference service default lookup order, not by the order of the scope contexts that are being passed in. The context objects are only consulted to help determine which nodes to look in, not the order of the nodes.

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.

An example of a qualifier for an Eclipse 2.1 preference is the plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")

Specified by:

getFloat in interface IPreferencesService

Parameters:

qualifier - a namespace qualifier for the preference

key - the name of the preference (optionally including its path)

defaultValue - the value to use if the preference is not defined

scopes - optional context objects to help scopes determine which nodes to search, or null

Returns:

the value of the preference or the given default value

See Also:

IScopeContext, IPreferencesService.get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]), IPreferencesService.getLookupOrder(java.lang.String, java.lang.String), IPreferencesService.getDefaultLookupOrder(java.lang.String, java.lang.String)

getInt

public int getInt(java.lang.String qualifier,
                  java.lang.String key,
                  int defaultValue,
                  IScopeContext[] scopes)

Description copied from interface: IPreferencesService

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 IPreferencesService.get(String, String, Preferences[]) method. The order of the nodes is calculated by consulting the default scope lookup order as set by IPreferencesService.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"

The scope look-up order is determined by the preference service default lookup order, not by the order of the scope contexts that are being passed in. The context objects are only consulted to help determine which nodes to look in, not the order of the nodes.

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.

An example of a qualifier for an Eclipse 2.1 preference is the plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")

Specified by:

getInt in interface IPreferencesService

Parameters:

qualifier - a namespace qualifier for the preference

key - the name of the preference (optionally including its path)

defaultValue - the value to use if the preference is not defined

scopes - optional context objects to help scopes determine which nodes to search, or null

Returns:

the value of the preference or the given default value

See Also:

IScopeContext, IPreferencesService.get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]), IPreferencesService.getLookupOrder(java.lang.String, java.lang.String), IPreferencesService.getDefaultLookupOrder(java.lang.String, java.lang.String)

getLong

public long getLong(java.lang.String qualifier,
                    java.lang.String key,
                    long defaultValue,
                    IScopeContext[] scopes)

Description copied from interface: IPreferencesService

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 IPreferencesService.get(String, String, Preferences[]) method. The order of the nodes is calculated by consulting the default scope lookup order as set by IPreferencesService.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"

The scope look-up order is determined by the preference service default lookup order, not by the order of the scope contexts that are being passed in. The context objects are only consulted to help determine which nodes to look in, not the order of the nodes.

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.

An example of a qualifier for an Eclipse 2.1 preference is the plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")

Specified by:

getLong in interface IPreferencesService

Parameters:

qualifier - a namespace qualifier for the preference

key - the name of the preference (optionally including its path)

defaultValue - the value to use if the preference is not defined

scopes - optional context objects to help scopes determine which nodes to search, or null

Returns:

the value of the preference or the given default value

See Also:

IScopeContext, IPreferencesService.get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]), IPreferencesService.getLookupOrder(java.lang.String, java.lang.String), IPreferencesService.getDefaultLookupOrder(java.lang.String, java.lang.String)

getLookupOrder

public java.lang.String[] getLookupOrder(java.lang.String qualifier,
                                         java.lang.String key)

Description copied from interface: IPreferencesService

Return an array with the lookup order for the preference keyed by the given qualifier and simple name.

First do an exact match lookup with the given qualifier and simple name. If a match is found then return it. Otherwise if the key is non-null then do a lookup based on only the qualifier and return the set value. Return the default-default order as defined by the platform if no order has been set.

Specified by:

getLookupOrder in interface IPreferencesService

Parameters:

qualifier - the namespace qualifier for the preference

key - the preference name or null

Returns:

the scope order

See Also:

IPreferencesService.getDefaultLookupOrder(String, String), IPreferencesService.setDefaultLookupOrder(String, String, String[])

getRootNode

public IEclipsePreferences getRootNode()

Description copied from interface: IPreferencesService

Return the root node of the Eclipse preference hierarchy.

Specified by:

getRootNode in interface IPreferencesService

Returns:

the root of the hierarchy

getString

public java.lang.String getString(java.lang.String qualifier,
                                  java.lang.String key,
                                  java.lang.String defaultValue,
                                  IScopeContext[] scopes)

Description copied from interface: IPreferencesService

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 IPreferencesService.get(String, String, Preferences[]) method. The order of the nodes is calculated by consulting the default scope lookup order as set by IPreferencesService.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"

The scope look-up order is determined by the preference service default lookup order, not by the order of the scope contexts that are being passed in. The context objects are only consulted to help determine which nodes to look in, not the order of the nodes.

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.

An example of a qualifier for an Eclipse 2.1 preference is the plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")

Specified by:

getString in interface IPreferencesService

Parameters:

qualifier - a namespace qualifier for the preference

key - the name of the preference (optionally including its path)

defaultValue - the value to use if the preference is not defined

scopes - optional context objects to help scopes determine which nodes to search, or null

Returns:

the value of the preference or the given default value

See Also:

IScopeContext, IPreferencesService.get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]), IPreferencesService.getLookupOrder(java.lang.String, java.lang.String), IPreferencesService.getDefaultLookupOrder(java.lang.String, java.lang.String)

importPreferences

public IStatus importPreferences(java.io.InputStream input)
                          throws CoreException

Description copied from interface: IPreferencesService

Loads preferences from the given file and stores them in the preferences store. Existing values are over-ridden by those from the stream. The stream must not be null and is closed upon return from this method.

This file must have been written by the IPreferencesService.exportPreferences(IEclipsePreferences, OutputStream, String[]) method.

This method is equivalent to calling applyPreferences(readPreferences(input));.

Specified by:

importPreferences in interface IPreferencesService

Parameters:

input - the stream to load the preferences from

Returns:

a status object describing success or detailing failure reasons

Throws:

CoreException - if there are problems importing the preferences

See Also:

IPreferencesService.exportPreferences(IEclipsePreferences, OutputStream, String[])

matches

public IPreferenceFilter[] matches(IEclipsePreferences tree,
                                   IPreferenceFilter[] filters)
                            throws CoreException

Description copied from interface: IPreferencesService

Return a list of filters which match the given tree and is a subset of the given filter list. If the specified list of filters is null, empty, or there are no matches, then return an empty list.

Specified by:

matches in interface IPreferencesService

Parameters:

tree - the tree to match against

filters - the list of filters to match against

Returns:

the array of matching transfers

Throws:

CoreException

See Also:

IPreferenceFilter

readPreferences

public IExportedPreferences readPreferences(java.io.InputStream input)
                                     throws CoreException

Description copied from interface: IPreferencesService

Read from the given input stream and create a node hierarchy representing the preferences and their values. The given input stream must not be null. The result of this function is suitable for passing as an argument to IPreferencesService.applyPreferences(IExportedPreferences).

It is assumed the contents of the input stream have been written by IPreferencesService.exportPreferences(IEclipsePreferences, OutputStream, String[]).

Specified by:

readPreferences in interface IPreferencesService

Parameters:

input - the input stream to read from

Returns:

the node hierarchy representing the stream contents

Throws:

CoreException - if there are problems reading the preferences

See Also:

IPreferencesService.exportPreferences(IEclipsePreferences, OutputStream, String[]), IPreferencesService.applyPreferences(IExportedPreferences)

setDefaultLookupOrder

public void setDefaultLookupOrder(java.lang.String qualifier,
                                  java.lang.String key,
                                  java.lang.String[] order)

Description copied from interface: IPreferencesService

Set the default scope lookup order for the preference keyed by the given qualifier and simple name. If the given order is null then the set ordering (if it exists) is removed.

If the given simple name is null then set the given lookup order to be used for all keys with the given qualifier.

Note that the default lookup order is not persisted across platform invocations.

Specified by:

setDefaultLookupOrder in interface IPreferencesService

Parameters:

qualifier - the namespace qualifier for the preference

key - the preference name or null

order - the lookup order or null

See Also:

IPreferencesService.getDefaultLookupOrder(String, String)

setRegistryHelper

public void setRegistryHelper(java.lang.Object registryHelper)

validateVersions

public IStatus validateVersions(IPath path)

getDefaultDefaultLookupOrder

public java.lang.String[] getDefaultDefaultLookupOrder()

setDefaultDefaultLookupOrder

public void setDefaultDefaultLookupOrder(java.lang.String[] order)