IEclipsePreferences


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.util.EventObject  ;
14  import org.osgi.service.prefs.BackingStoreException;
15  import org.osgi.service.prefs.Preferences;
16  
17  /**
18   * This interface describes Eclipse extensions to the preference
19   * story. It provides means for both preference and node change
20   * listeners.
21   * <p>
22   * Clients may implement this interface.
23   * </p>
24   * 
25   * @see org.osgi.service.prefs.Preferences
26   * @since 3.0
27   */
28  public interface IEclipsePreferences extends Preferences {
29  
30      /**
31       * An event object which describes the details of a change in the 
32       * preference node hierarchy. The child node is the one which 
33       * was added or removed.
34       * 
35       * @see IEclipsePreferences.INodeChangeListener
36       * @since 3.0
37       */
38      public final class NodeChangeEvent extends EventObject   {
39          /**
40           * All serializable objects should have a stable serialVersionUID
41           */
42          private static final long serialVersionUID = 1L;
43  
44          private Preferences child;
45  
46          /**
47           * Constructor for a new node change event object.
48           * 
49           * @param parent the parent node
50           * @param child the child node
51           */
52          public NodeChangeEvent(Preferences parent, Preferences child) {
53              super(parent);
54              this.child = child;
55          }
56  
57          /**
58           * Return the parent node for this event. This is the parent
59           * of the node which was added or removed.
60           * 
61           * @return the parent node
62           */
63          public Preferences getParent() {
64              return (Preferences) getSource();
65          }
66  
67          /**
68           * Return the child node for this event. This is the node
69           * which was added or removed.
70           * <p>
71           * Note: The child node may have been removed as a result of
72           * the bundle supplying its implementation being un-installed. In this case
73           * the only method which can safely be called on the child is #name().
74           * </p>
75           * @return the child node
76           */
77          public Preferences getChild() {
78              return child;
79          }
80      }
81  
82      /**
83       * A listener to be used to receive preference node change events.
84       * <p>
85       * Clients may implement this interface.
86       * </p>
87       * 
88       * @since 3.0
89       */
90      public interface INodeChangeListener {
91  
92          /**
93           * Notification that a child node was added to the preference hierarchy.
94           * The given event must not be <code>null</code>.
95           * 
96           * @param event an event specifying the details about the new node
97           * @see IEclipsePreferences.NodeChangeEvent
98           * @see IEclipsePreferences#addNodeChangeListener(IEclipsePreferences.INodeChangeListener)
99           * @see IEclipsePreferences#removeNodeChangeListener(IEclipsePreferences.INodeChangeListener)
100          */
101         public void added(NodeChangeEvent event);
102 
103         /**
104          * Notification that a child node was removed from the preference hierarchy.
105          * The given event must not be <code>null</code>.
106          * 
107          * @param event an event specifying the details about the removed node
108          * @see IEclipsePreferences.NodeChangeEvent
109          * @see IEclipsePreferences#addNodeChangeListener(IEclipsePreferences.INodeChangeListener)
110          * @see IEclipsePreferences#removeNodeChangeListener(IEclipsePreferences.INodeChangeListener)
111          */
112         public void removed(NodeChangeEvent event);
113     }
114 
115     /**
116      * An event object describing the details of a change to a preference
117      * in the preference store.
118      * 
119      * @see IEclipsePreferences.IPreferenceChangeListener
120      * @since 3.0
121      */
122     public final class PreferenceChangeEvent extends EventObject   {
123         /**
124          * All serializable objects should have a stable serialVersionUID
125          */
126         private static final long serialVersionUID = 1L;
127 
128         private String   key;
129         private Object   newValue;
130         private Object   oldValue;
131 
132         /**
133          * Constructor for a new preference change event. The node and the
134          * key must not be <code>null</code>. The old and new preference
135          * values must be either a <code>String</code> or <code>null</code>.
136          * 
137          * @param node the node on which the change occurred
138          * @param key the preference key
139          * @param oldValue the old preference value, as a <code>String</code> 
140          *  or <code>null</code>
141          * @param newValue the new preference value, as a <code>String</code>
142          *  or <code>null</code>
143          */
144         public PreferenceChangeEvent(Object   node, String   key, Object   oldValue, Object   newValue) {
145             super(node);
146             if (key == null || !(node instanceof Preferences))
147                 throw new IllegalArgumentException  ();
148             this.key = key;
149             this.newValue = newValue;
150             this.oldValue = oldValue;
151         }
152 
153         /**
154          * Return the preference node on which the change occurred.
155          * Must not be <code>null</code>.
156          * 
157          * @return the node
158          */
159         public Preferences getNode() {
160             return (Preferences) source;
161         }
162 
163         /**
164          * Return the key of the preference which was changed.
165          * Must not be <code>null</code>.
166          * 
167          * @return the preference key
168          */
169         public String   getKey() {
170             return key;
171         }
172 
173         /**
174          * Return the new value for the preference encoded as a 
175          * <code>String</code>, or <code>null</code> if the 
176          * preference was removed.
177          * 
178          * @return the new value or <code>null</code>
179          */
180         public Object   getNewValue() {
181             return newValue;
182         }
183 
184         /**
185          * Return the old value for the preference encoded as a 
186          * <code>String</code>, or <code>null</code> if the 
187          * preference was removed or if it cannot be determined.
188          * 
189          * @return the old value or <code>null</code>
190          */
191         public Object   getOldValue() {
192             return oldValue;
193         }
194     }
195 
196     /**
197      * A listener used to receive changes to preference values in the preference store.
198      * <p>
199      * Clients may implement this interface.
200      * </p>
201      * 
202      * @since 3.0
203      */
204     public interface IPreferenceChangeListener {
205 
206         /**
207          * Notification that a preference value has changed in the preference store.
208          * The given event object describes the change details and must not
209          * be <code>null</code>.
210          * 
211          * @param event the event details
212          * @see IEclipsePreferences.PreferenceChangeEvent
213          * @see IEclipsePreferences#addPreferenceChangeListener(IEclipsePreferences.IPreferenceChangeListener)
214          * @see IEclipsePreferences#removePreferenceChangeListener(IEclipsePreferences.IPreferenceChangeListener)
215          */
216         public void preferenceChange(PreferenceChangeEvent event);
217     }
218 
219     /**
220      * Register the given listener for changes to this node. Duplicate calls
221      * to this method with the same listener will have no effect. The given
222      * listener argument must not be <code>null</code>.
223      *  
224      * @param listener the node change listener to add
225      * @throws IllegalStateException if this node or an ancestor has been removed
226      * @see #removeNodeChangeListener(IEclipsePreferences.INodeChangeListener)
227      * @see IEclipsePreferences.INodeChangeListener
228      */
229     public void addNodeChangeListener(INodeChangeListener listener);
230 
231     /**
232      * De-register the given listener from receiving event change notifications
233      * for this node. Calling this method with a listener which is not registered
234      * has no effect. The given listener argument must not be <code>null</code>.
235      * 
236      * @param listener the node change listener to remove
237      * @throws IllegalStateException if this node or an ancestor has been removed
238      * @see #addNodeChangeListener(IEclipsePreferences.INodeChangeListener)
239      * @see IEclipsePreferences.INodeChangeListener
240      */
241     public void removeNodeChangeListener(INodeChangeListener listener);
242 
243     /**
244      * Register the given listener for notification of preference changes to this node.
245      * Calling this method multiple times with the same listener has no effect. The
246      * given listener argument must not be <code>null</code>.
247      * 
248      * @param listener the preference change listener to register
249      * @throws IllegalStateException if this node or an ancestor has been removed
250      * @see #removePreferenceChangeListener(IEclipsePreferences.IPreferenceChangeListener)
251      * @see IEclipsePreferences.IPreferenceChangeListener
252      */
253     public void addPreferenceChangeListener(IPreferenceChangeListener listener);
254 
255     /**
256      * De-register the given listener from receiving notification of preference changes
257      * to this node. Calling this method multiple times with the same listener has no
258      * effect. The given listener argument must not be <code>null</code>.
259      * 
260      * @param listener the preference change listener to remove
261      * @throws IllegalStateException if this node or an ancestor has been removed
262      * @see #addPreferenceChangeListener(IEclipsePreferences.IPreferenceChangeListener)
263      * @see IEclipsePreferences.IPreferenceChangeListener
264      */
265     public void removePreferenceChangeListener(IPreferenceChangeListener listener);
266 
267     /**
268      * Remove this node from the preference hierarchy. If this node is the scope
269      * root, then do not remove this node, only remove this node's children.
270      * <p>
271      * Functionally equivalent to calling {@link Preferences#removeNode()}. 
272      * See the spec of {@link Preferences#removeNode()} for more details. 
273      * </p>
274      * <p>
275      * Implementors must send the appropriate {@link NodeChangeEvent}
276      * to listeners who are registered on this node's parent.
277      * </p>
278      * <p>
279      * When this node is removed, its associated preference and node change 
280      * listeners should be removed as well.
281      * </p>
282      * @throws BackingStoreException if there was a problem removing this node
283      * @see org.osgi.service.prefs.Preferences#removeNode()
284      * @see NodeChangeEvent
285      */
286     public void removeNode() throws BackingStoreException;
287 
288     /**
289      * Return the preferences node with the given path. The given path must
290      * not be <code>null</code>.
291      * <p>
292      * See the spec of {@link Preferences#node(String)} for more details. 
293      * </p>
294      * <p>
295      * Note that if the node does not yet exist and is created, then the appropriate
296      * {@link NodeChangeEvent} must be sent to listeners who are
297      * registered at this node.
298      * </p>
299      * @param path the path of the node
300      * @return the node
301      * @see org.osgi.service.prefs.Preferences#node(String)
302      * @see NodeChangeEvent
303      */
304     public Preferences node(String   path);
305 
306     /**
307      * Accepts the given visitor. The visitor's <code>visit</code> method 
308      * is called with this node. If the visitor returns <code>true</code>, 
309      * this method visits this node's children.
310      *
311      * @param visitor the visitor
312      * @see IPreferenceNodeVisitor#visit(IEclipsePreferences)
313      * @throws BackingStoreException
314      */
315     public void accept(IPreferenceNodeVisitor visitor) throws BackingStoreException;
316 }
317
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags