diff options
Diffstat (limited to 'bundles/org.eclipse.equinox.preferences/src/org/eclipse/core/runtime/preferences/IPreferencesService.java')
| -rw-r--r-- | bundles/org.eclipse.equinox.preferences/src/org/eclipse/core/runtime/preferences/IPreferencesService.java | 618 |
1 files changed, 0 insertions, 618 deletions
diff --git a/bundles/org.eclipse.equinox.preferences/src/org/eclipse/core/runtime/preferences/IPreferencesService.java b/bundles/org.eclipse.equinox.preferences/src/org/eclipse/core/runtime/preferences/IPreferencesService.java deleted file mode 100644 index 142870098..000000000 --- a/bundles/org.eclipse.equinox.preferences/src/org/eclipse/core/runtime/preferences/IPreferencesService.java +++ /dev/null @@ -1,618 +0,0 @@ -/******************************************************************************* - * Copyright (c) 2004, 2005 IBM Corporation and others. - * All rights reserved. This program and the accompanying materials - * are made available under the terms of the Eclipse Public License v1.0 - * which accompanies this distribution, and is available at - * http://www.eclipse.org/legal/epl-v10.html - * - * Contributors: - * IBM Corporation - initial API and implementation - *******************************************************************************/ -package org.eclipse.core.runtime.preferences; - -import java.io.InputStream; -import java.io.OutputStream; -import org.eclipse.core.runtime.CoreException; -import org.eclipse.core.runtime.IStatus; -import org.osgi.service.prefs.Preferences; - -/** - * 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. - * <p> - * The default-default preference search look-up order as defined by the platform - * is: project, instance, configuration, default. - * </p><p> - * This interface is not intended to be implemented by clients. - * </p> - * @since 3.0 - */ -public 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. - * <p> - * Immediately returns the default value if the node list is <code>null</code>. - * If any of the individual entries in the node list are <code>null</code> then - * skip over them and move on to the next node in the list. - * </p> - * @param key the preference key - * @param defaultValue the default value - * @param nodes the list of nodes to search, or <code>null</code> - * @return the stored preference value or the specified default value - * @see org.osgi.service.prefs.Preferences - */ - public String get(String key, String defaultValue, Preferences[] nodes); - - /** - * 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. - * <p> - * The semantics of this method are to calculate the appropriate - * {@link Preferences} nodes in the preference hierarchy to use - * and then call the {@link #get(String, String, Preferences[])} - * method. The order of the nodes is calculated by consulting the default - * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}. - * </p><p> - * 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: - * <ul> - * <li>"a" - look for a value for the property "a" - * <li>"//a" - look for a value for the property "a" - * <li>"///a" - look for a value for the property "/a" - * <li>"//a//b" - look for a value for the property "a//b" - * <li>"a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b//c" - look in the child node "a/b" for the property "c" - * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d" - * </ul> - * </p><p> - * 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. - * </p><p> - * 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") - * </p> - * @param qualifier a namespace qualifier for the preference - * @param key the name of the preference (optionally including its path) - * @param defaultValue the value to use if the preference is not defined - * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code> - * @return the value of the preference or the given default value - * @see IScopeContext - * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]) - * @see #getLookupOrder(java.lang.String, java.lang.String) - * @see #getDefaultLookupOrder(java.lang.String, java.lang.String) - */ - public 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. - * <p> - * The semantics of this method are to calculate the appropriate - * {@link Preferences} nodes in the preference hierarchy to use - * and then call the {@link #get(String, String, Preferences[])} - * method. The order of the nodes is calculated by consulting the default - * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}. - * </p><p> - * 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: - * <ul> - * <li>"a" - look for a value for the property "a" - * <li>"//a" - look for a value for the property "a" - * <li>"///a" - look for a value for the property "/a" - * <li>"//a//b" - look for a value for the property "a//b" - * <li>"a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b//c" - look in the child node "a/b" for the property "c" - * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d" - * </ul> - * </p><p> - * 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. - * </p><p> - * 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") - * </p> - * @param qualifier a namespace qualifier for the preference - * @param key the name of the preference (optionally including its path) - * @param defaultValue the value to use if the preference is not defined - * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code> - * @return the value of the preference or the given default value - * @see IScopeContext - * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]) - * @see #getLookupOrder(java.lang.String, java.lang.String) - * @see #getDefaultLookupOrder(java.lang.String, java.lang.String) - */ - public byte[] getByteArray(String qualifier, String key, byte[] 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. - * <p> - * The semantics of this method are to calculate the appropriate - * {@link Preferences} nodes in the preference hierarchy to use - * and then call the {@link #get(String, String, Preferences[])} - * method. The order of the nodes is calculated by consulting the default - * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}. - * </p><p> - * 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: - * <ul> - * <li>"a" - look for a value for the property "a" - * <li>"//a" - look for a value for the property "a" - * <li>"///a" - look for a value for the property "/a" - * <li>"//a//b" - look for a value for the property "a//b" - * <li>"a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b//c" - look in the child node "a/b" for the property "c" - * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d" - * </ul> - * </p><p> - * 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. - * </p><p> - * 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") - * </p> - * @param qualifier a namespace qualifier for the preference - * @param key the name of the preference (optionally including its path) - * @param defaultValue the value to use if the preference is not defined - * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code> - * @return the value of the preference or the given default value - * @see IScopeContext - * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]) - * @see #getLookupOrder(java.lang.String, java.lang.String) - * @see #getDefaultLookupOrder(java.lang.String, java.lang.String) - */ - public double getDouble(String qualifier, String key, double 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. - * <p> - * The semantics of this method are to calculate the appropriate - * {@link Preferences} nodes in the preference hierarchy to use - * and then call the {@link #get(String, String, Preferences[])} - * method. The order of the nodes is calculated by consulting the default - * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}. - * </p><p> - * 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: - * <ul> - * <li>"a" - look for a value for the property "a" - * <li>"//a" - look for a value for the property "a" - * <li>"///a" - look for a value for the property "/a" - * <li>"//a//b" - look for a value for the property "a//b" - * <li>"a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b//c" - look in the child node "a/b" for the property "c" - * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d" - * </ul> - * </p><p> - * 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. - * </p><p> - * 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") - * </p> - * @param qualifier a namespace qualifier for the preference - * @param key the name of the preference (optionally including its path) - * @param defaultValue the value to use if the preference is not defined - * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code> - * @return the value of the preference or the given default value - * @see IScopeContext - * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]) - * @see #getLookupOrder(java.lang.String, java.lang.String) - * @see #getDefaultLookupOrder(java.lang.String, java.lang.String) - */ - public float getFloat(String qualifier, String key, float 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. - * <p> - * The semantics of this method are to calculate the appropriate - * {@link Preferences} nodes in the preference hierarchy to use - * and then call the {@link #get(String, String, Preferences[])} - * method. The order of the nodes is calculated by consulting the default - * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}. - * </p><p> - * 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: - * <ul> - * <li>"a" - look for a value for the property "a" - * <li>"//a" - look for a value for the property "a" - * <li>"///a" - look for a value for the property "/a" - * <li>"//a//b" - look for a value for the property "a//b" - * <li>"a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b//c" - look in the child node "a/b" for the property "c" - * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d" - * </ul> - * </p><p> - * 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. - * </p><p> - * 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") - * </p> - * @param qualifier a namespace qualifier for the preference - * @param key the name of the preference (optionally including its path) - * @param defaultValue the value to use if the preference is not defined - * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code> - * @return the value of the preference or the given default value - * @see IScopeContext - * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]) - * @see #getLookupOrder(java.lang.String, java.lang.String) - * @see #getDefaultLookupOrder(java.lang.String, java.lang.String) - */ - public int getInt(String qualifier, String key, int 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. - * <p> - * The semantics of this method are to calculate the appropriate - * {@link Preferences} nodes in the preference hierarchy to use - * and then call the {@link #get(String, String, Preferences[])} - * method. The order of the nodes is calculated by consulting the default - * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}. - * </p><p> - * 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: - * <ul> - * <li>"a" - look for a value for the property "a" - * <li>"//a" - look for a value for the property "a" - * <li>"///a" - look for a value for the property "/a" - * <li>"//a//b" - look for a value for the property "a//b" - * <li>"a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b//c" - look in the child node "a/b" for the property "c" - * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d" - * </ul> - * </p><p> - * 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. - * </p><p> - * 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") - * </p> - * @param qualifier a namespace qualifier for the preference - * @param key the name of the preference (optionally including its path) - * @param defaultValue the value to use if the preference is not defined - * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code> - * @return the value of the preference or the given default value - * @see IScopeContext - * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]) - * @see #getLookupOrder(java.lang.String, java.lang.String) - * @see #getDefaultLookupOrder(java.lang.String, java.lang.String) - */ - public long getLong(String qualifier, String key, long 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. - * <p> - * The semantics of this method are to calculate the appropriate - * {@link Preferences} nodes in the preference hierarchy to use - * and then call the {@link #get(String, String, Preferences[])} - * method. The order of the nodes is calculated by consulting the default - * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}. - * </p><p> - * 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: - * <ul> - * <li>"a" - look for a value for the property "a" - * <li>"//a" - look for a value for the property "a" - * <li>"///a" - look for a value for the property "/a" - * <li>"//a//b" - look for a value for the property "a//b" - * <li>"a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b/c" - look in the child node "a/b" for property "c" - * <li>"/a/b//c" - look in the child node "a/b" for the property "c" - * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d" - * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d" - * </ul> - * </p><p> - * 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. - * </p><p> - * 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") - * </p> - * @param qualifier a namespace qualifier for the preference - * @param key the name of the preference (optionally including its path) - * @param defaultValue the value to use if the preference is not defined - * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code> - * @return the value of the preference or the given default value - * @see IScopeContext - * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[]) - * @see #getLookupOrder(java.lang.String, java.lang.String) - * @see #getDefaultLookupOrder(java.lang.String, java.lang.String) - */ - public String getString(String qualifier, String key, String defaultValue, IScopeContext[] contexts); - - /** - * Return the root node of the Eclipse preference hierarchy. - * - * @return the root of the hierarchy - */ - public IEclipsePreferences getRootNode(); - - /** - * 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. - * <p> - * If the given export list is <code>null</code> 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 <em>not</em> accepted in the excludes list as a basic String compare - * is done. The basic algorithm is similar to the following: - * <pre> - * String fullPath = node.absolutePath() + '/' + key; - * if (!fullPath.startsWith(excludesList[i])) - * // export preference - * </pre> - * </p> - * <p> - * The values stored in the resulting stream are suitable for later being read by the - * by {@link #importPreferences(InputStream)} or {@link #readPreferences(InputStream)} methods. - * </p> - * @param node the node to treat as the root of the export - * @param output the stream to write to - * @param excludesList a list of path prefixes to exclude from the export, or <code>null</code> - * @return a status object describing success or detailing failure reasons - * @throws CoreException if there was a problem exporting the preferences - * @throws IllegalArgumentException if the node or stream is <code>null</code> - * @see #importPreferences(java.io.InputStream) - * @see #readPreferences(InputStream) - */ - public IStatus exportPreferences(IEclipsePreferences node, OutputStream output, String[] excludesList) throws CoreException; - - /** - * 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 - * <code>null</code> and is closed upon return from this method. - * <p> - * This file must have been written by the - * {@link #exportPreferences(IEclipsePreferences, OutputStream, String[])} - * method. - * </p> - * <p> - * This method is equivalent to calling <code>applyPreferences(readPreferences(input));</code>. - * </p> - * @param input the stream to load the preferences from - * @return a status object describing success or detailing failure reasons - * @throws CoreException if there are problems importing the preferences - * @throws IllegalArgumentException if the stream is <code>null</code> - * @see #exportPreferences(IEclipsePreferences, OutputStream, String[]) - */ - public IStatus importPreferences(InputStream input) throws CoreException; - - /** - * Take the given preference tree and apply it to the Eclipse - * global preference hierarchy. If a node is an export root, then - * remove it from the global tree before adding any preferences - * contained in it or its children. The given preferences object - * must not be <code>null</code>. - * <p> - * Before the tree is applied to the global preference tree, - * the registered <code>PreferenceModifyListener</code> objects - * are called and given the opportunity to modify the tree. - * </p> - * - * @param preferences the preferences to apply globally - * @return status object indicating success or failure - * @throws IllegalArgumentException if the preferences are <code>null</code> - * @throws CoreException if there are problems applying the preferences - * @see PreferenceModifyListener - */ - public IStatus applyPreferences(IExportedPreferences preferences) throws CoreException; - - /** - * Read from the given input stream and create a node hierarchy - * representing the preferences and their values. The given input stream - * must not be <code>null</code>. The result of this function is suitable - * for passing as an argument to {@link #applyPreferences(IExportedPreferences)}. - * <p> - * It is assumed the contents of the input stream have been written by - * {@link #exportPreferences(IEclipsePreferences, OutputStream, String[])}. - * </p> - * @param input the input stream to read from - * @return the node hierarchy representing the stream contents - * @throws IllegalArgumentException if the given stream is null - * @throws CoreException if there are problems reading the preferences - * @see #exportPreferences(IEclipsePreferences, OutputStream, String[]) - * @see #applyPreferences(IExportedPreferences) - */ - public IExportedPreferences readPreferences(InputStream input) throws CoreException; - - /** - * Return an array with the default lookup order for the preference keyed by the given - * qualifier and simple name. Return <code>null</code> if no default has been set. - * <p> - * 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-<code>null</code> and - * no default lookup order is found, the default lookup order for the qualifier (and a - * <code>null</code> key) is <em>NOT</em> returned. Clients should call - * {@link #getLookupOrder(String, String)} if they desire this behavior. - * </p> - * @param qualifier the namespace qualifier for the preference - * @param key the preference name or <code>null</code> - * @return the scope order or <code>null</code> - * @see #setDefaultLookupOrder(String, String, String[]) - * @see #getLookupOrder(String, String) - */ - public String[] getDefaultLookupOrder(String qualifier, String key); - - /** - * Return an array with the lookup order for the preference keyed by the given - * qualifier and simple name. - * <p> - * 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-<code>null</code> 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. - * </p> - * @param qualifier the namespace qualifier for the preference - * @param key the preference name or <code>null</code> - * @return the scope order - * @throws IllegalArgumentException if the qualifier is <code>null</code> - * @see #getDefaultLookupOrder(String, String) - * @see #setDefaultLookupOrder(String, String, String[]) - */ - public String[] getLookupOrder(String qualifier, String key); - - /** - * Set the default scope lookup order for the preference keyed by the given - * qualifier and simple name. If the given order is <code>null</code> then the set - * ordering (if it exists) is removed. - * <p> - * If the given simple name is <code>null</code> then set the given lookup - * order to be used for all keys with the given qualifier. - * </p><p> - * Note that the default lookup order is not persisted across platform invocations. - * </p> - * @param qualifier the namespace qualifier for the preference - * @param key the preference name or <code>null</code> - * @param order the lookup order or <code>null</code> - * @throws IllegalArgumentException - * <ul> - * <li>if the qualifier is <code>null</code></li> - * <li>if an entry in the order array is <code>null</code> (the array itself is - * allowed to be <code>null</code></li> - * </ul> - * @see #getDefaultLookupOrder(String, String) - */ - public void setDefaultLookupOrder(String qualifier, String key, String[] order); - - /** - * 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. - * <p> - * The given node and output stream must not be <code>null</code>. - * If the list of filters is <code>null</code> or empty then do nothing. - * </p> - * <p> - * It is the responsibility of the client to close the given output stream. - * </p> - * - * @param node the tree to export - * @param filters the list of filters to export - * @param output the stream to export to - * @throws CoreException - * @see #exportPreferences(IEclipsePreferences, OutputStream, String[]) - * @see #readPreferences(InputStream) - * @see #applyPreferences(IEclipsePreferences, IPreferenceFilter[]) - * @see #applyPreferences(IExportedPreferences) - * @see IPreferenceFilter - * @since 3.1 - */ - public void exportPreferences(IEclipsePreferences node, IPreferenceFilter[] filters, OutputStream output) throws CoreException; - - /** - * 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 <code>null</code>, empty, or there - * are no matches, then return an empty list. - * - * @param node the tree to match against - * @param filters the list of filters to match against - * @return the array of matching transfers - * @throws CoreException - * @see IPreferenceFilter - * @since 3.1 - */ - public IPreferenceFilter[] matches(IEclipsePreferences node, IPreferenceFilter[] filters) throws CoreException; - - /** - * 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. - * <p> - * If the list of filters is <code>null</code> or empty then do nothing. - * </p> - * <p> - * Before the tree is applied to the global preference tree, - * the registered <code>PreferenceModifyListener</code> objects - * are called and given the opportunity to modify the tree. - * </p> - * - * @param node the tree to consider applying - * @param filters the filters to use - * @throws CoreException - * @see #applyPreferences(IExportedPreferences) - * @see #readPreferences(InputStream) - * @see IPreferenceFilter - * @see PreferenceModifyListener - * @since 3.1 - */ - public void applyPreferences(IEclipsePreferences node, IPreferenceFilter[] filters) throws CoreException; -} |