IPreferencesService


1   /*******************************************************************************
2    * Copyright (c) 2004, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    * 
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.runtime.preferences;
12  
13  import java.io.InputStream  ;
14  import java.io.OutputStream  ;
15  import org.eclipse.core.runtime.CoreException;
16  import org.eclipse.core.runtime.IStatus;
17  import org.osgi.service.prefs.Preferences;
18  
19  /**
20   * The preference service provides facilities for dealing with the default scope
21   * precedence lookup order, querying the preference store for values using this order,
22   * accessing the root of the preference store node hierarchy, and importing/exporting
23   * preferences.
24   * <p>
25   * The default-default preference search look-up order as defined by the platform
26   * is: project, instance, configuration, default.
27   * </p><p>
28   * This interface is not intended to be implemented by clients.
29   * </p>
30   * @since 3.0
31   */
32  public interface IPreferencesService {
33  
34      /**
35       * Lookup the given key in the specified preference nodes in the given order.
36       * Return the value from the first node the key is found in. If the key is not
37       * defined in any of the given nodes, then return the specified default value.
38       * <p>
39       * Immediately returns the default value if the node list is <code>null</code>.
40       * If any of the individual entries in the node list are <code>null</code> then
41       * skip over them and move on to the next node in the list.
42       * </p>
43       * @param key the preference key
44       * @param defaultValue the default value
45       * @param nodes the list of nodes to search, or <code>null</code>
46       * @return the stored preference value or the specified default value 
47       * @see org.osgi.service.prefs.Preferences
48       */
49      public String   get(String   key, String   defaultValue, Preferences[] nodes);
50  
51      /**
52       * Return the value stored in the preference store for the given key. 
53       * If the key is not defined then return the specified default value. 
54       * Use the canonical scope lookup order for finding the preference value. 
55       * <p>
56       * The semantics of this method are to calculate the appropriate 
57       * {@link Preferences} nodes in the preference hierarchy to use
58       * and then call the {@link #get(String, String, Preferences[])} 
59       * method. The order of the nodes is calculated by consulting the default 
60       * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}.
61       * </p><p>
62       * The specified key may either refer to a simple key or be the concatenation of the 
63       * path of a child node and key. If the key contains a slash ("/") character, then a 
64       * double-slash must be used to denote the end of they child path and the beginning 
65       * of the key. Otherwise it is assumed that the key is the last segment of the path.
66       * The following are some examples of keys and their meanings:
67       * <ul>
68       * <li>"a" - look for a value for the property "a"
69       * <li>"//a" - look for a value for the property "a"
70       * <li>"///a" - look for a value for the property "/a"
71       * <li>"//a//b" - look for a value for the property "a//b"
72       * <li>"a/b/c" - look in the child node "a/b" for property "c"
73       * <li>"/a/b/c" - look in the child node "a/b" for property "c"
74       * <li>"/a/b//c" - look in the child node "a/b" for the property "c"
75       * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d"
76       * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d"
77       * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d"
78       * </ul>
79       * </p><p>
80       * Callers may specify an array of scope context objects to aid in the 
81       * determination of the correct nodes. For each entry in the lookup 
82       * order, the array of contexts is consulted and if one matching the 
83       * scope exists, then it is used to calculate the node. Otherwise a
84       * default calculation algorithm is used. 
85       * </p><p>
86       * An example of a qualifier for an Eclipse 2.1 preference is the
87       * plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")
88       * </p>
89       * @param qualifier a namespace qualifier for the preference
90       * @param key the name of the preference (optionally including its path)
91       * @param defaultValue the value to use if the preference is not defined
92       * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code>
93       * @return the value of the preference or the given default value
94       * @see IScopeContext
95       * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
96       * @see #getLookupOrder(java.lang.String, java.lang.String)
97       * @see #getDefaultLookupOrder(java.lang.String, java.lang.String)
98       */
99      public boolean getBoolean(String   qualifier, String   key, boolean defaultValue, IScopeContext[] contexts);
100 
101     /**
102      * Return the value stored in the preference store for the given key. 
103      * If the key is not defined then return the specified default value. 
104      * Use the canonical scope lookup order for finding the preference value. 
105      * <p>
106      * The semantics of this method are to calculate the appropriate 
107      * {@link Preferences} nodes in the preference hierarchy to use
108      * and then call the {@link #get(String, String, Preferences[])} 
109      * method. The order of the nodes is calculated by consulting the default 
110      * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}.
111      * </p><p>
112      * The specified key may either refer to a simple key or be the concatenation of the 
113      * path of a child node and key. If the key contains a slash ("/") character, then a 
114      * double-slash must be used to denote the end of they child path and the beginning 
115      * of the key. Otherwise it is assumed that the key is the last segment of the path.
116      * The following are some examples of keys and their meanings:
117      * <ul>
118      * <li>"a" - look for a value for the property "a"
119      * <li>"//a" - look for a value for the property "a"
120      * <li>"///a" - look for a value for the property "/a"
121      * <li>"//a//b" - look for a value for the property "a//b"
122      * <li>"a/b/c" - look in the child node "a/b" for property "c"
123      * <li>"/a/b/c" - look in the child node "a/b" for property "c"
124      * <li>"/a/b//c" - look in the child node "a/b" for the property "c"
125      * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d"
126      * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d"
127      * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d"
128      * </ul>
129      * </p><p>
130      * Callers may specify an array of scope context objects to aid in the 
131      * determination of the correct nodes. For each entry in the lookup 
132      * order, the array of contexts is consulted and if one matching the 
133      * scope exists, then it is used to calculate the node. Otherwise a
134      * default calculation algorithm is used. 
135      * </p><p>
136      * An example of a qualifier for an Eclipse 2.1 preference is the
137      * plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")
138      * </p>
139      * @param qualifier a namespace qualifier for the preference
140      * @param key the name of the preference (optionally including its path)
141      * @param defaultValue the value to use if the preference is not defined
142      * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code>
143      * @return the value of the preference or the given default value
144      * @see IScopeContext
145      * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
146      * @see #getLookupOrder(java.lang.String, java.lang.String)
147      * @see #getDefaultLookupOrder(java.lang.String, java.lang.String)
148      */
149     public byte[] getByteArray(String   qualifier, String   key, byte[] defaultValue, IScopeContext[] contexts);
150 
151     /**
152      * Return the value stored in the preference store for the given key. 
153      * If the key is not defined then return the specified default value. 
154      * Use the canonical scope lookup order for finding the preference value. 
155      * <p>
156      * The semantics of this method are to calculate the appropriate 
157      * {@link Preferences} nodes in the preference hierarchy to use
158      * and then call the {@link #get(String, String, Preferences[])} 
159      * method. The order of the nodes is calculated by consulting the default 
160      * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}.
161      * </p><p>
162      * The specified key may either refer to a simple key or be the concatenation of the 
163      * path of a child node and key. If the key contains a slash ("/") character, then a 
164      * double-slash must be used to denote the end of they child path and the beginning 
165      * of the key. Otherwise it is assumed that the key is the last segment of the path.
166      * The following are some examples of keys and their meanings:
167      * <ul>
168      * <li>"a" - look for a value for the property "a"
169      * <li>"//a" - look for a value for the property "a"
170      * <li>"///a" - look for a value for the property "/a"
171      * <li>"//a//b" - look for a value for the property "a//b"
172      * <li>"a/b/c" - look in the child node "a/b" for property "c"
173      * <li>"/a/b/c" - look in the child node "a/b" for property "c"
174      * <li>"/a/b//c" - look in the child node "a/b" for the property "c"
175      * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d"
176      * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d"
177      * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d"
178      * </ul>
179      * </p><p>
180      * Callers may specify an array of scope context objects to aid in the 
181      * determination of the correct nodes. For each entry in the lookup 
182      * order, the array of contexts is consulted and if one matching the 
183      * scope exists, then it is used to calculate the node. Otherwise a
184      * default calculation algorithm is used. 
185      * </p><p>
186      * An example of a qualifier for an Eclipse 2.1 preference is the
187      * plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")
188      * </p>
189      * @param qualifier a namespace qualifier for the preference
190      * @param key the name of the preference (optionally including its path)
191      * @param defaultValue the value to use if the preference is not defined
192      * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code>
193      * @return the value of the preference or the given default value
194      * @see IScopeContext
195      * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
196      * @see #getLookupOrder(java.lang.String, java.lang.String)
197      * @see #getDefaultLookupOrder(java.lang.String, java.lang.String)
198      */
199     public double getDouble(String   qualifier, String   key, double defaultValue, IScopeContext[] contexts);
200 
201     /**
202      * Return the value stored in the preference store for the given key. 
203      * If the key is not defined then return the specified default value. 
204      * Use the canonical scope lookup order for finding the preference value. 
205      * <p>
206      * The semantics of this method are to calculate the appropriate 
207      * {@link Preferences} nodes in the preference hierarchy to use
208      * and then call the {@link #get(String, String, Preferences[])} 
209      * method. The order of the nodes is calculated by consulting the default 
210      * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}.
211      * </p><p>
212      * The specified key may either refer to a simple key or be the concatenation of the 
213      * path of a child node and key. If the key contains a slash ("/") character, then a 
214      * double-slash must be used to denote the end of they child path and the beginning 
215      * of the key. Otherwise it is assumed that the key is the last segment of the path.
216      * The following are some examples of keys and their meanings:
217      * <ul>
218      * <li>"a" - look for a value for the property "a"
219      * <li>"//a" - look for a value for the property "a"
220      * <li>"///a" - look for a value for the property "/a"
221      * <li>"//a//b" - look for a value for the property "a//b"
222      * <li>"a/b/c" - look in the child node "a/b" for property "c"
223      * <li>"/a/b/c" - look in the child node "a/b" for property "c"
224      * <li>"/a/b//c" - look in the child node "a/b" for the property "c"
225      * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d"
226      * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d"
227      * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d"
228      * </ul>
229      * </p><p>
230      * Callers may specify an array of scope context objects to aid in the 
231      * determination of the correct nodes. For each entry in the lookup 
232      * order, the array of contexts is consulted and if one matching the 
233      * scope exists, then it is used to calculate the node. Otherwise a
234      * default calculation algorithm is used. 
235      * </p><p>
236      * An example of a qualifier for an Eclipse 2.1 preference is the
237      * plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")
238      * </p>
239      * @param qualifier a namespace qualifier for the preference
240      * @param key the name of the preference (optionally including its path)
241      * @param defaultValue the value to use if the preference is not defined
242      * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code>
243      * @return the value of the preference or the given default value
244      * @see IScopeContext
245      * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
246      * @see #getLookupOrder(java.lang.String, java.lang.String)
247      * @see #getDefaultLookupOrder(java.lang.String, java.lang.String)
248      */
249     public float getFloat(String   qualifier, String   key, float defaultValue, IScopeContext[] contexts);
250 
251     /**
252      * Return the value stored in the preference store for the given key. 
253      * If the key is not defined then return the specified default value. 
254      * Use the canonical scope lookup order for finding the preference value. 
255      * <p>
256      * The semantics of this method are to calculate the appropriate 
257      * {@link Preferences} nodes in the preference hierarchy to use
258      * and then call the {@link #get(String, String, Preferences[])} 
259      * method. The order of the nodes is calculated by consulting the default 
260      * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}.
261      * </p><p>
262      * The specified key may either refer to a simple key or be the concatenation of the 
263      * path of a child node and key. If the key contains a slash ("/") character, then a 
264      * double-slash must be used to denote the end of they child path and the beginning 
265      * of the key. Otherwise it is assumed that the key is the last segment of the path.
266      * The following are some examples of keys and their meanings:
267      * <ul>
268      * <li>"a" - look for a value for the property "a"
269      * <li>"//a" - look for a value for the property "a"
270      * <li>"///a" - look for a value for the property "/a"
271      * <li>"//a//b" - look for a value for the property "a//b"
272      * <li>"a/b/c" - look in the child node "a/b" for property "c"
273      * <li>"/a/b/c" - look in the child node "a/b" for property "c"
274      * <li>"/a/b//c" - look in the child node "a/b" for the property "c"
275      * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d"
276      * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d"
277      * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d"
278      * </ul>
279      * </p><p>
280      * Callers may specify an array of scope context objects to aid in the 
281      * determination of the correct nodes. For each entry in the lookup 
282      * order, the array of contexts is consulted and if one matching the 
283      * scope exists, then it is used to calculate the node. Otherwise a
284      * default calculation algorithm is used. 
285      * </p><p>
286      * An example of a qualifier for an Eclipse 2.1 preference is the
287      * plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")
288      * </p>
289      * @param qualifier a namespace qualifier for the preference
290      * @param key the name of the preference (optionally including its path)
291      * @param defaultValue the value to use if the preference is not defined
292      * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code>
293      * @return the value of the preference or the given default value
294      * @see IScopeContext
295      * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
296      * @see #getLookupOrder(java.lang.String, java.lang.String)
297      * @see #getDefaultLookupOrder(java.lang.String, java.lang.String)
298      */
299     public int getInt(String   qualifier, String   key, int defaultValue, IScopeContext[] contexts);
300 
301     /**
302      * Return the value stored in the preference store for the given key. 
303      * If the key is not defined then return the specified default value. 
304      * Use the canonical scope lookup order for finding the preference value. 
305      * <p>
306      * The semantics of this method are to calculate the appropriate 
307      * {@link Preferences} nodes in the preference hierarchy to use
308      * and then call the {@link #get(String, String, Preferences[])} 
309      * method. The order of the nodes is calculated by consulting the default 
310      * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}.
311      * </p><p>
312      * The specified key may either refer to a simple key or be the concatenation of the 
313      * path of a child node and key. If the key contains a slash ("/") character, then a 
314      * double-slash must be used to denote the end of they child path and the beginning 
315      * of the key. Otherwise it is assumed that the key is the last segment of the path.
316      * The following are some examples of keys and their meanings:
317      * <ul>
318      * <li>"a" - look for a value for the property "a"
319      * <li>"//a" - look for a value for the property "a"
320      * <li>"///a" - look for a value for the property "/a"
321      * <li>"//a//b" - look for a value for the property "a//b"
322      * <li>"a/b/c" - look in the child node "a/b" for property "c"
323      * <li>"/a/b/c" - look in the child node "a/b" for property "c"
324      * <li>"/a/b//c" - look in the child node "a/b" for the property "c"
325      * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d"
326      * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d"
327      * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d"
328      * </ul>
329      * </p><p>
330      * Callers may specify an array of scope context objects to aid in the 
331      * determination of the correct nodes. For each entry in the lookup 
332      * order, the array of contexts is consulted and if one matching the 
333      * scope exists, then it is used to calculate the node. Otherwise a
334      * default calculation algorithm is used. 
335      * </p><p>
336      * An example of a qualifier for an Eclipse 2.1 preference is the
337      * plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")
338      * </p>
339      * @param qualifier a namespace qualifier for the preference
340      * @param key the name of the preference (optionally including its path)
341      * @param defaultValue the value to use if the preference is not defined
342      * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code>
343      * @return the value of the preference or the given default value
344      * @see IScopeContext
345      * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
346      * @see #getLookupOrder(java.lang.String, java.lang.String)
347      * @see #getDefaultLookupOrder(java.lang.String, java.lang.String)
348      */
349     public long getLong(String   qualifier, String   key, long defaultValue, IScopeContext[] contexts);
350 
351     /**
352      * Return the value stored in the preference store for the given key. 
353      * If the key is not defined then return the specified default value. 
354      * Use the canonical scope lookup order for finding the preference value. 
355      * <p>
356      * The semantics of this method are to calculate the appropriate 
357      * {@link Preferences} nodes in the preference hierarchy to use
358      * and then call the {@link #get(String, String, Preferences[])} 
359      * method. The order of the nodes is calculated by consulting the default 
360      * scope lookup order as set by {@link #setDefaultLookupOrder(String, String, String[])}.
361      * </p><p>
362      * The specified key may either refer to a simple key or be the concatenation of the 
363      * path of a child node and key. If the key contains a slash ("/") character, then a 
364      * double-slash must be used to denote the end of they child path and the beginning 
365      * of the key. Otherwise it is assumed that the key is the last segment of the path.
366      * The following are some examples of keys and their meanings:
367      * <ul>
368      * <li>"a" - look for a value for the property "a"
369      * <li>"//a" - look for a value for the property "a"
370      * <li>"///a" - look for a value for the property "/a"
371      * <li>"//a//b" - look for a value for the property "a//b"
372      * <li>"a/b/c" - look in the child node "a/b" for property "c"
373      * <li>"/a/b/c" - look in the child node "a/b" for property "c"
374      * <li>"/a/b//c" - look in the child node "a/b" for the property "c"
375      * <li>"a/b//c/d" - look in the child node "a/b" for the property "c/d"
376      * <li>"/a/b//c/d" - look in the child node "a/b" for the property "c/d"
377      * <li>"/a/b//c//d" - look in the child node "a/b" for the property "c//d"
378      * </ul>
379      * </p><p>
380      * Callers may specify an array of scope context objects to aid in the 
381      * determination of the correct nodes. For each entry in the lookup 
382      * order, the array of contexts is consulted and if one matching the 
383      * scope exists, then it is used to calculate the node. Otherwise a
384      * default calculation algorithm is used. 
385      * </p><p>
386      * An example of a qualifier for an Eclipse 2.1 preference is the
387      * plug-in identifier. (e.g. "org.eclipse.core.resources" for "description.autobuild")
388      * </p>
389      * @param qualifier a namespace qualifier for the preference
390      * @param key the name of the preference (optionally including its path)
391      * @param defaultValue the value to use if the preference is not defined
392      * @param contexts optional context objects to help scopes determine which nodes to search, or <code>null</code>
393      * @return the value of the preference or the given default value
394      * @see IScopeContext
395      * @see #get(java.lang.String, java.lang.String, org.osgi.service.prefs.Preferences[])
396      * @see #getLookupOrder(java.lang.String, java.lang.String)
397      * @see #getDefaultLookupOrder(java.lang.String, java.lang.String)
398      */
399     public String   getString(String   qualifier, String   key, String   defaultValue, IScopeContext[] contexts);
400 
401     /**
402      * Return the root node of the Eclipse preference hierarchy.
403      * 
404      * @return the root of the hierarchy
405      */
406     public IEclipsePreferences getRootNode();
407 
408     /**
409      * Exports all preferences for the given preference node and all its children to the specified
410      * output stream. It is the responsibility of the client to close the given output stream.
411      * <p>
412      * If the given export list is <code>null</code> then all preferences for all sub-nodes
413      * of the given node are exported to the given stream. Otherwise the export list is
414      * consulted before exporting each preference value. If there is a string match then
415      * the preference is not exported. The exclusion can also occur at a per-node level. 
416      * Wild cards are <em>not</em> accepted in the excludes list as a basic String compare
417      * is done. The basic algorithm is similar to the following:
418      * <pre>
419      * String fullPath = node.absolutePath() + '/' + key;
420      * if (!fullPath.startsWith(excludesList[i]))
421      *  // export preference
422      * </pre>
423      * </p>
424      * <p>
425      * The values stored in the resulting stream are suitable for later being read by the
426      * by {@link #importPreferences(InputStream)} or {@link #readPreferences(InputStream)} methods.
427      * </p>
428      * @param node the node to treat as the root of the export
429      * @param output the stream to write to
430      * @param excludesList a list of path prefixes to exclude from the export, or <code>null</code>
431      * @return a status object describing success or detailing failure reasons
432      * @throws CoreException if there was a problem exporting the preferences
433      * @throws IllegalArgumentException if the node or stream is <code>null</code>
434      * @see #importPreferences(java.io.InputStream)
435      * @see #readPreferences(InputStream)
436      */
437     public IStatus exportPreferences(IEclipsePreferences node, OutputStream   output, String  [] excludesList) throws CoreException;
438 
439     /**
440      * Loads preferences from the given file and stores them in the preferences store.
441      * Existing values are over-ridden by those from the stream. The stream must not be
442      * <code>null</code> and is closed upon return from this method.
443      * <p>
444      * This file must have been written by the 
445      * {@link #exportPreferences(IEclipsePreferences, OutputStream, String[])} 
446      * method.
447      * </p>
448      * <p>
449      * This method is equivalent to calling <code>applyPreferences(readPreferences(input));</code>.
450      * </p>
451      * @param input the stream to load the preferences from
452      * @return a status object describing success or detailing failure reasons
453      * @throws CoreException if there are problems importing the preferences
454      * @throws IllegalArgumentException if the stream is <code>null</code>
455      * @see #exportPreferences(IEclipsePreferences, OutputStream, String[])
456      */
457     public IStatus importPreferences(InputStream   input) throws CoreException;
458 
459     /**
460      * Take the given preference tree and apply it to the Eclipse
461      * global preference hierarchy. If a node is an export root, then 
462      * remove it from the global tree before adding any preferences
463      * contained in it or its children. The given preferences object
464      * must not be <code>null</code>.
465      * <p>
466      * Before the tree is applied to the global preference tree,
467      * the registered <code>PreferenceModifyListener</code> objects
468      * are called and given the opportunity to modify the tree.
469      * </p>
470      * 
471      * @param preferences the preferences to apply globally
472      * @return status object indicating success or failure
473      * @throws IllegalArgumentException if the preferences are <code>null</code>
474      * @throws CoreException if there are problems applying the preferences
475      * @see PreferenceModifyListener
476      */
477     public IStatus applyPreferences(IExportedPreferences preferences) throws CoreException;
478 
479     /**
480      * Read from the given input stream and create a node hierarchy
481      * representing the preferences and their values. The given input stream
482      * must not be <code>null</code>. The result of this function is suitable
483      * for passing as an argument to {@link #applyPreferences(IExportedPreferences)}.
484      * <p>
485      * It is assumed the contents of the input stream have been written by
486      * {@link #exportPreferences(IEclipsePreferences, OutputStream, String[])}.
487      * </p>
488      * @param input the input stream to read from
489      * @return the node hierarchy representing the stream contents
490      * @throws IllegalArgumentException if the given stream is null
491      * @throws CoreException if there are problems reading the preferences
492      * @see #exportPreferences(IEclipsePreferences, OutputStream, String[])
493      * @see #applyPreferences(IExportedPreferences)
494      */
495     public IExportedPreferences readPreferences(InputStream   input) throws CoreException;
496 
497     /**
498      * Return an array with the default lookup order for the preference keyed by the given
499      * qualifier and simple name. Return <code>null</code> if no default has been set.
500      * <p>
501      * The lookup order returned is based on an exact match to the specified qualifier
502      * and simple name. For instance, if the given key is non-<code>null</code> and
503      * no default lookup order is found, the default lookup order for the qualifier (and a
504      * <code>null</code> key) is <em>NOT</em> returned. Clients should call
505      * {@link #getLookupOrder(String, String)} if they desire this behavior.
506      * </p>
507      * @param qualifier the namespace qualifier for the preference
508      * @param key the preference name or <code>null</code>
509      * @return the scope order or <code>null</code>
510      * @see #setDefaultLookupOrder(String, String, String[])
511      * @see #getLookupOrder(String, String)
512      */
513     public String  [] getDefaultLookupOrder(String   qualifier, String   key);
514 
515     /**
516      * Return an array with the lookup order for the preference keyed by the given
517      * qualifier and simple name. 
518      * <p>
519      * First do an exact match lookup with the given qualifier and simple name. If a match
520      * is found then return it. Otherwise if the key is non-<code>null</code> then
521      * do a lookup based on only the qualifier and return the set value. 
522      * Return the default-default order as defined by the platform if no order has been set.
523      * </p>
524      * @param qualifier the namespace qualifier for the preference
525      * @param key the preference name or <code>null</code>
526      * @return the scope order 
527      * @throws IllegalArgumentException if the qualifier is <code>null</code>
528      * @see #getDefaultLookupOrder(String, String)
529      * @see #setDefaultLookupOrder(String, String, String[])
530      */
531     public String  [] getLookupOrder(String   qualifier, String   key);
532 
533     /**
534      * Set the default scope lookup order for the preference keyed by the given
535      * qualifier and simple name. If the given order is <code>null</code> then the set
536      * ordering (if it exists) is removed.
537      * <p>
538      * If the given simple name is <code>null</code> then set the given lookup
539      * order to be used for all keys with the given qualifier.
540      * </p><p>
541      * Note that the default lookup order is not persisted across platform invocations. 
542      * </p>
543      * @param qualifier the namespace qualifier for the preference
544      * @param key the preference name or <code>null</code>
545      * @param order the lookup order or <code>null</code>
546      * @throws IllegalArgumentException
547      * <ul>
548      * <li>if the qualifier is <code>null</code></li>
549      * <li>if an entry in the order array is <code>null</code> (the array itself is 
550      * allowed to be <code>null</code></li>
551      * </ul>
552      * @see #getDefaultLookupOrder(String, String)
553      */
554     public void setDefaultLookupOrder(String   qualifier, String   key, String  [] order);
555 
556     /**
557      * Export the preference tree rooted at the given node, to the specified output
558      * stream. Apply the given list of preference filters, only exporting
559      * preference node and keys which are applicable to at least one filter in the list.
560      * <p>
561      * The given node and output stream must not be <code>null</code>.
562      * If the list of filters is <code>null</code> or empty then do nothing.
563      * </p>
564      * <p>
565      * It is the responsibility of the client to close the given output stream.
566      * </p>
567      * 
568      * @param node the tree to export
569      * @param filters the list of filters to export
570      * @param output the stream to export to
571      * @throws CoreException
572      * @see #exportPreferences(IEclipsePreferences, OutputStream, String[])
573      * @see #readPreferences(InputStream)
574      * @see #applyPreferences(IEclipsePreferences, IPreferenceFilter[])
575      * @see #applyPreferences(IExportedPreferences)
576      * @see IPreferenceFilter
577      * @since 3.1
578      */
579     public void exportPreferences(IEclipsePreferences node, IPreferenceFilter[] filters, OutputStream   output) throws CoreException;
580 
581     /**
582      * Return a list of filters which match the given tree and is a subset of the given
583      * filter list. If the specified list of filters is <code>null</code>, empty, or there 
584      * are no matches, then return an empty list.
585      * 
586      * @param node the tree to match against
587      * @param filters the list of filters to match against
588      * @return the array of matching transfers
589      * @throws CoreException
590      * @see IPreferenceFilter
591      * @since 3.1
592      */
593     public IPreferenceFilter[] matches(IEclipsePreferences node, IPreferenceFilter[] filters) throws CoreException;
594 
595     /**
596      * Apply the preference tree rooted at the given node, to the system's preference tree.
597      * The list of preference filters will act as a filter and only preferences in the tree which
598      * apply to at least one filter in the list, will be applied.
599      * <p>
600      * If the list of filters is <code>null</code> or empty then do nothing.
601      * </p>
602      * <p>
603      * Before the tree is applied to the global preference tree,
604      * the registered <code>PreferenceModifyListener</code> objects
605      * are called and given the opportunity to modify the tree.
606      * </p>
607      * 
608      * @param node the tree to consider applying
609      * @param filters the filters to use
610      * @throws CoreException
611      * @see #applyPreferences(IExportedPreferences)
612      * @see #readPreferences(InputStream)
613      * @see IPreferenceFilter
614      * @see PreferenceModifyListener
615      * @since 3.1
616      */
617     public void applyPreferences(IEclipsePreferences node, IPreferenceFilter[] filters) throws CoreException;
618 }
619
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags