PreferenceManager


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 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.jface.preference;
12  
13  import java.util.ArrayList  ;
14  import java.util.List  ;
15  import java.util.StringTokenizer  ;
16  
17  import org.eclipse.core.runtime.Assert;
18  
19  /**
20   * A preference manager maintains a hierarchy of preference nodes and
21   * associated preference pages.
22   */
23  public class PreferenceManager {
24      /**
25       * Pre-order traversal means visit the root first,
26       * then the children.
27       */
28      public static final int PRE_ORDER = 0;
29  
30      /**
31       * Post-order means visit the children, and then the root.
32       */
33      public static final int POST_ORDER = 1;
34  
35      /**
36       * The root node.
37       * Note that the root node is a special internal node
38       * that is used to collect together all the nodes that
39       * have no parent; it is not given out to clients.
40       */
41      PreferenceNode root = new PreferenceNode("");//$NON-NLS-1$
42  
43      /**
44       * The path separator character.
45       */
46      String   separator;
47  
48      /**
49       * Creates a new preference manager.
50       */
51      public PreferenceManager() {
52          this('.');
53      }
54  
55      /**
56       * Creates a new preference manager with the given
57       * the path separator.
58       *
59       * @param separatorChar the separator character
60       */
61      public PreferenceManager(char separatorChar) {
62          separator = new String  (new char[] { separatorChar });
63      }
64  
65      /**
66       * Adds the given preference node as a subnode of the
67       * node at the given path.
68       *
69       * @param path the path
70       * @param node the node to add
71       * @return <code>true</code> if the add was successful,
72       *  and <code>false</code> if there is no contribution at
73       *  the given path
74       */
75      public boolean addTo(String   path, IPreferenceNode node) {
76          IPreferenceNode target = find(path);
77          if (target == null) {
78              return false;
79          }
80          target.add(node);
81          return true;
82      }
83  
84      /**
85       * Adds the given preference node as a subnode of the
86       * root.
87       *
88       * @param node the node to add, which must implement 
89       *   <code>IPreferenceNode</code>
90       */
91      public void addToRoot(IPreferenceNode node) {
92          Assert.isNotNull(node);
93          root.add(node);
94      }
95  
96      /**
97       * Recursively enumerates all nodes at or below the given node
98       * and adds them to the given list in the given order.
99       * 
100      * @param node the starting node
101      * @param sequence a read-write list of preference nodes
102      *  (element type: <code>IPreferenceNode</code>)
103      *  in the given order
104      * @param order the traversal order, one of 
105      *  <code>PRE_ORDER</code> and <code>POST_ORDER</code>
106      */
107     protected void buildSequence(IPreferenceNode node, List   sequence, int order) {
108         if (order == PRE_ORDER) {
109             sequence.add(node);
110         }
111         IPreferenceNode[] subnodes = node.getSubNodes();
112         for (int i = 0; i < subnodes.length; i++) {
113             buildSequence(subnodes[i], sequence, order);
114         }
115         if (order == POST_ORDER) {
116             sequence.add(node);
117         }
118     }
119 
120     /**
121      * Finds and returns the contribution node at the given path.
122      *
123      * @param path the path
124      * @return the node, or <code>null</code> if none
125      */
126     public IPreferenceNode find(String   path) {
127        return find(path,root);
128     }
129     
130     /**
131      * Finds and returns the preference node directly
132      * below the top at the given path.
133      *
134      * @param path the path
135      * @param top top at the given path
136      * @return the node, or <code>null</code> if none
137      * 
138      * @since 3.1
139      */
140     protected IPreferenceNode find(String   path,IPreferenceNode top){
141          Assert.isNotNull(path);
142          StringTokenizer   stok = new StringTokenizer  (path, separator);
143          IPreferenceNode node = top;
144          while (stok.hasMoreTokens()) {
145              String   id = stok.nextToken();
146              node = node.findSubNode(id);
147              if (node == null) {
148                 return null;
149             }
150          }
151          if (node == top) {
152             return null;
153         }
154          return node;
155     }
156 
157     /**
158      * Returns all preference nodes managed by this
159      * manager.
160      *
161      * @param order the traversal order, one of 
162      *  <code>PRE_ORDER</code> and <code>POST_ORDER</code>
163      * @return a list of preference nodes
164      *  (element type: <code>IPreferenceNode</code>)
165      *  in the given order
166      */
167     public List   getElements(int order) {
168         Assert.isTrue(order == PRE_ORDER || order == POST_ORDER,
169                 "invalid traversal order");//$NON-NLS-1$
170         ArrayList   sequence = new ArrayList  ();
171         IPreferenceNode[] subnodes = getRoot().getSubNodes();
172         for (int i = 0; i < subnodes.length; i++) {
173             buildSequence(subnodes[i], sequence, order);
174         }
175         return sequence;
176     }
177 
178     /**
179      * Returns the root node.
180      * Note that the root node is a special internal node
181      * that is used to collect together all the nodes that
182      * have no parent; it is not given out to clients.
183      *
184      * @return the root node
185      */
186     protected IPreferenceNode getRoot() {
187         return root;
188     }
189 
190     /**
191      * Returns the root level nodes of this preference manager.
192      * 
193      * @return an array containing the root nodes
194      * @since 3.2
195      */
196     public final IPreferenceNode[] getRootSubNodes() {
197         return getRoot().getSubNodes();
198     }
199 
200     /**
201      * Removes the preference node at the given path.
202      * 
203      * @param path
204      *            the path
205      * @return the node that was removed, or <code>null</code> if there was no
206      *         node at the given path
207      */
208     public IPreferenceNode remove(String   path) {
209         Assert.isNotNull(path);
210         int index = path.lastIndexOf(separator);
211         if (index == -1) {
212             return root.remove(path);
213         }
214         // Make sure that the last character in the string isn't the "."
215         Assert.isTrue(index < path.length() - 1, "Path can not end with a dot");//$NON-NLS-1$
216         String   parentPath = path.substring(0, index);
217         String   id = path.substring(index + 1);
218         IPreferenceNode parentNode = find(parentPath);
219         if (parentNode == null) {
220             return null;
221         }
222         return parentNode.remove(id);
223     }
224 
225     /**
226      * Removes the given prefreence node if it is managed by
227      * this contribution manager.
228      *
229      * @param node the node to remove
230      * @return <code>true</code> if the node was removed,
231      *  and <code>false</code> otherwise
232      */
233     public boolean remove(IPreferenceNode node) {
234         Assert.isNotNull(node);
235 
236         return root.remove(node);
237     }
238 
239     /**
240      * Removes all contribution nodes known to this manager.
241      */
242     public void removeAll() {
243         root = new PreferenceNode("");//$NON-NLS-1$
244     }
245 }
246
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags