public interface IPreferencesService
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.
Modifier and Type | Method and Description |
---|---|
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.
|
String get(String key, String defaultValue, Preferences[] nodes)
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.
key
- the preference keydefaultValue
- the default valuenodes
- the list of nodes to search, or null
Preferences
boolean getBoolean(String qualifier, String key, boolean defaultValue, IScopeContext[] contexts)
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:
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")
qualifier
- a namespace qualifier for the preferencekey
- the name of the preference (optionally including its path)defaultValue
- the value to use if the preference is not definedcontexts
- optional context objects to help scopes determine which nodes to search, or null
IScopeContext
,
get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
,
getLookupOrder(java.lang.String, java.lang.String)
,
getDefaultLookupOrder(java.lang.String, java.lang.String)
byte[] getByteArray(String qualifier, String key, byte[] defaultValue, IScopeContext[] contexts)
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:
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")
qualifier
- a namespace qualifier for the preferencekey
- the name of the preference (optionally including its path)defaultValue
- the value to use if the preference is not definedcontexts
- optional context objects to help scopes determine which nodes to search, or null
IScopeContext
,
get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
,
getLookupOrder(java.lang.String, java.lang.String)
,
getDefaultLookupOrder(java.lang.String, java.lang.String)
double getDouble(String qualifier, String key, double defaultValue, IScopeContext[] contexts)
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:
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")
qualifier
- a namespace qualifier for the preferencekey
- the name of the preference (optionally including its path)defaultValue
- the value to use if the preference is not definedcontexts
- optional context objects to help scopes determine which nodes to search, or null
IScopeContext
,
get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
,
getLookupOrder(java.lang.String, java.lang.String)
,
getDefaultLookupOrder(java.lang.String, java.lang.String)
float getFloat(String qualifier, String key, float defaultValue, IScopeContext[] contexts)
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:
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")
qualifier
- a namespace qualifier for the preferencekey
- the name of the preference (optionally including its path)defaultValue
- the value to use if the preference is not definedcontexts
- optional context objects to help scopes determine which nodes to search, or null
IScopeContext
,
get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
,
getLookupOrder(java.lang.String, java.lang.String)
,
getDefaultLookupOrder(java.lang.String, java.lang.String)
int getInt(String qualifier, String key, int defaultValue, IScopeContext[] contexts)
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:
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")
qualifier
- a namespace qualifier for the preferencekey
- the name of the preference (optionally including its path)defaultValue
- the value to use if the preference is not definedcontexts
- optional context objects to help scopes determine which nodes to search, or null
IScopeContext
,
get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
,
getLookupOrder(java.lang.String, java.lang.String)
,
getDefaultLookupOrder(java.lang.String, java.lang.String)
long getLong(String qualifier, String key, long defaultValue, IScopeContext[] contexts)
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:
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")
qualifier
- a namespace qualifier for the preferencekey
- the name of the preference (optionally including its path)defaultValue
- the value to use if the preference is not definedcontexts
- optional context objects to help scopes determine which nodes to search, or null
IScopeContext
,
get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
,
getLookupOrder(java.lang.String, java.lang.String)
,
getDefaultLookupOrder(java.lang.String, java.lang.String)
String getString(String qualifier, String key, String defaultValue, IScopeContext[] contexts)
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:
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")
qualifier
- a namespace qualifier for the preferencekey
- the name of the preference (optionally including its path)defaultValue
- the value to use if the preference is not definedcontexts
- optional context objects to help scopes determine which nodes to search, or null
IScopeContext
,
get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
,
getLookupOrder(java.lang.String, java.lang.String)
,
getDefaultLookupOrder(java.lang.String, java.lang.String)
IEclipsePreferences getRootNode()
IStatus exportPreferences(IEclipsePreferences node, OutputStream output, String[] excludesList) throws CoreException
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 importPreferences(InputStream)
or readPreferences(InputStream)
methods.
node
- the node to treat as the root of the exportoutput
- the stream to write toexcludesList
- a list of path prefixes to exclude from the export, or null
CoreException
- if there was a problem exporting the preferencesIllegalArgumentException
- if the node or stream is null
importPreferences(java.io.InputStream)
,
readPreferences(InputStream)
IStatus importPreferences(InputStream input) throws CoreException
null
and is closed upon return from this method.
This file must have been written by the
exportPreferences(IEclipsePreferences, OutputStream, String[])
method.
This method is equivalent to calling applyPreferences(readPreferences(input));
.
input
- the stream to load the preferences fromCoreException
- if there are problems importing the preferencesIllegalArgumentException
- if the stream is null
exportPreferences(IEclipsePreferences, OutputStream, String[])
IStatus applyPreferences(IExportedPreferences preferences) throws CoreException
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.
preferences
- the preferences to apply globallyIllegalArgumentException
- if the preferences are null
CoreException
- if there are problems applying the preferencesPreferenceModifyListener
IExportedPreferences readPreferences(InputStream input) throws CoreException
null
. The result of this function is suitable
for passing as an argument to applyPreferences(IExportedPreferences)
.
It is assumed the contents of the input stream have been written by
exportPreferences(IEclipsePreferences, OutputStream, String[])
.
input
- the input stream to read fromIllegalArgumentException
- if the given stream is nullCoreException
- if there are problems reading the preferencesexportPreferences(IEclipsePreferences, OutputStream, String[])
,
applyPreferences(IExportedPreferences)
String[] getDefaultLookupOrder(String qualifier, String key)
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
getLookupOrder(String, String)
if they desire this behavior.
qualifier
- the namespace qualifier for the preferencekey
- the preference name or null
null
setDefaultLookupOrder(String, String, String[])
,
getLookupOrder(String, String)
String[] getLookupOrder(String qualifier, String key)
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.
qualifier
- the namespace qualifier for the preferencekey
- the preference name or null
IllegalArgumentException
- if the qualifier is null
getDefaultLookupOrder(String, String)
,
setDefaultLookupOrder(String, String, String[])
void setDefaultLookupOrder(String qualifier, String key, String[] order)
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.
qualifier
- the namespace qualifier for the preferencekey
- the preference name or null
order
- the lookup order or null
IllegalArgumentException
- null
null
(the array itself is
allowed to be null
getDefaultLookupOrder(String, String)
void exportPreferences(IEclipsePreferences node, IPreferenceFilter[] filters, OutputStream output) throws CoreException
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.
node
- the tree to exportfilters
- the list of filters to exportoutput
- the stream to export toCoreException
exportPreferences(IEclipsePreferences, OutputStream, String[])
,
readPreferences(InputStream)
,
applyPreferences(IEclipsePreferences, IPreferenceFilter[])
,
applyPreferences(IExportedPreferences)
,
IPreferenceFilter
IPreferenceFilter[] matches(IEclipsePreferences node, IPreferenceFilter[] filters) throws CoreException
null
, empty, or there
are no matches, then return an empty list.node
- the tree to match againstfilters
- the list of filters to match againstCoreException
IPreferenceFilter
void applyPreferences(IEclipsePreferences node, IPreferenceFilter[] filters) throws CoreException
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.
node
- the tree to consider applyingfilters
- the filters to useCoreException
applyPreferences(IExportedPreferences)
,
readPreferences(InputStream)
,
IPreferenceFilter
,
PreferenceModifyListener
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.