NewWizardsRegistryReader


1   /*******************************************************************************
2    * Copyright (c) 2000, 2004 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials 
4    * are made available under the terms of the Common Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/cpl-v10.html
7    * 
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.ui.internal.registry;
12  
13  import java.text.Collator  ;
14  import java.util.ArrayList  ;
15  import java.util.Arrays  ;
16  import java.util.Collections  ;
17  import java.util.Comparator  ;
18  import java.util.Iterator  ;
19  import java.util.StringTokenizer  ;
20  
21  import org.eclipse.core.runtime.CoreException;
22  import org.eclipse.core.runtime.IConfigurationElement;
23  import org.eclipse.core.runtime.IExtension;
24  import org.eclipse.jface.resource.ImageDescriptor;
25  import org.eclipse.ui.internal.IWorkbenchConstants;
26  import org.eclipse.ui.internal.WorkbenchMessages;
27  import org.eclipse.ui.internal.WorkbenchPlugin;
28  import org.eclipse.ui.internal.dialogs.WizardCollectionElement;
29  import org.eclipse.ui.internal.dialogs.WorkbenchWizardElement;
30  import org.eclipse.ui.plugin.AbstractUIPlugin;
31  
32  /**
33   *  Instances of this class provide a simple API to the workbench for
34   *  accessing of the core registry.  It accepts a registry at creation
35   *  time and extracts workbench-related information from it as requested.
36   */
37  public class NewWizardsRegistryReader extends WizardsRegistryReader {
38      
39      private boolean projectsOnly;
40      private WizardCollectionElement wizardElements = null;
41      private ArrayList   deferWizards = null;
42      private ArrayList   deferCategories = null;
43      private ArrayList   deferPrimary;
44      
45      // constants
46      public final static String        BASE_CATEGORY = "Base";//$NON-NLS-1$
47      public final static String        EXAMPLES_WIZARD_CATEGORY = "Examples";//$NON-NLS-1$
48      public final static String        FULL_EXAMPLES_WIZARD_CATEGORY = "org.eclipse.ui.Examples";//$NON-NLS-1$
49      private final static String       TAG_CATEGORY = "category";  //$NON-NLS-1$
50      private final static String       TAG_PRIMARYWIZARD = "primaryWizard";    //$NON-NLS-1$
51      private final static String       ATT_HELP_HREF = "helpHref"; //$NON-NLS-1$
52      private final static String       ATT_DESCRIPTION_IMAGE = "descriptionImage"; //$NON-NLS-1$
53      private final static String       UNCATEGORIZED_WIZARD_CATEGORY = "org.eclipse.ui.Other";//$NON-NLS-1$
54      private final static String       UNCATEGORIZED_WIZARD_CATEGORY_LABEL = WorkbenchMessages.getString("NewWizardsRegistryReader.otherCategory");//$NON-NLS-1$
55      private final static String       CATEGORY_SEPARATOR = "/";//$NON-NLS-1$
56      private final static String       ATT_CATEGORY = "category";//$NON-NLS-1$
57      // @issue project-specific attribute and behavior
58      private final static String   ATT_PROJECT = "project";//$NON-NLS-1$
59      private final static String   STR_TRUE = "true";//$NON-NLS-1$
60      
61      private WorkbenchWizardElement [] primaryWizards = new WorkbenchWizardElement[0];
62  
63      private class CategoryNode {
64          private Category category;
65          private String   path;
66          public CategoryNode(Category cat) {
67              category = cat;
68              path = ""; //$NON-NLS-1$
69              String  [] categoryPath = category.getParentPath();
70              if (categoryPath != null) {
71                  for (int nX = 0; nX < categoryPath.length; nX ++) {
72                      path += categoryPath[nX] + '/'; //$NON-NLS-1$
73                  }
74              }
75              path += cat.getId();
76          }
77          public String   getPath() {
78              return path;
79          }
80          public Category getCategory() {
81              return category;
82          }
83      }
84      
85      private static final Comparator   comparer = new Comparator  () {
86          private Collator   collator = Collator.getInstance();
87  
88          public int compare(Object   arg0, Object   arg1) {
89              String   s1 = ((CategoryNode)arg0).getPath();
90              String   s2 = ((CategoryNode)arg1).getPath();
91              return collator.compare(s1, s2);
92          }
93      }; 
94  
95  /**
96   * Constructs a new reader.  All wizards are read, including projects.
97   */
98  public NewWizardsRegistryReader() {
99      this(false);
100 }
101 /**
102  * Constructs a new reader.
103  *
104  * @param projectsOnly if true, only projects are read.
105  */
106 public NewWizardsRegistryReader(boolean projectsOnly) {
107     super(IWorkbenchConstants.PL_NEW);
108     this.projectsOnly = projectsOnly;
109 }
110 /* (non-Javadoc)
111  * Method declared on WizardRegistryReader.  
112  * <p>
113  * This implementation uses a defering strategy.  For more info see
114  * <code>readWizards</code>.
115  * </p>
116  */
117 protected void addNewElementToResult(WorkbenchWizardElement element, IConfigurationElement config) {
118     deferWizard(element);
119 }
120 /**
121  *  Create and answer a new WizardCollectionElement, configured as a
122  *  child of <code>parent</code>
123  *
124  *  @return org.eclipse.ui.internal.model.WizardCollectionElement
125  *  @param parent org.eclipse.ui.internal.model.WizardCollectionElement
126  *  @param id the id of the new collection
127  *  @param pluginId the originating plugin id of the collection, if any. <code>null</code> otherwise.
128  *  @param label java.lang.String
129  */
130 protected WizardCollectionElement createCollectionElement(WizardCollectionElement parent, String   id, String   pluginId, String   label) {
131     WizardCollectionElement newElement = new WizardCollectionElement(id, pluginId, label, parent);
132 
133     parent.add(newElement);
134     return newElement;
135 }
136 /**
137  * Creates empty element collection. Overrider to fill
138  * initial elements, if needed.
139  */
140 protected void createEmptyWizardCollection() {
141     wizardElements = new WizardCollectionElement("root", null, "root", null);//$NON-NLS-2$//$NON-NLS-1$
142 }
143 /**
144  * Returns a new WorkbenchWizardElement configured according to the parameters
145  * contained in the passed Registry.  
146  *
147  * May answer null if there was not enough information in the Extension to create 
148  * an adequate wizard
149  */
150 protected WorkbenchWizardElement createWizardElement(IConfigurationElement element) {
151     if (projectsOnly) {
152         String   flag = element.getAttribute(ATT_PROJECT);
153         if (flag == null || !flag.equalsIgnoreCase(STR_TRUE))
154             return null;
155     }
156     return super.createWizardElement(element);
157 }
158 /**
159  * Stores a category element for deferred addition.
160  */
161 private void deferCategory(IConfigurationElement config) {
162     // Create category.
163     Category category = null;
164     try {
165         category = new Category(config);
166     } catch (CoreException e) {
167         WorkbenchPlugin.log("Cannot create category: ", e.getStatus());//$NON-NLS-1$
168         return;
169     }
170 
171     // Defer for later processing.
172     if (deferCategories == null)
173         deferCategories = new ArrayList  (20);
174     deferCategories.add(category);
175 }
176 /**
177  * Stores a wizard element for deferred addition.
178  */
179 private void deferWizard(WorkbenchWizardElement element) {
180     if (deferWizards == null)
181         deferWizards = new ArrayList  (50);
182     deferWizards.add(element);
183 }
184 /**
185  * Finishes the addition of categories.  The categories are sorted and
186  * added in a root to depth traversal.
187  */
188 private void finishCategories() {
189     // If no categories just return.
190     if (deferCategories == null)
191         return;
192 
193     // Sort categories by flattened name.
194     CategoryNode [] flatArray = new CategoryNode[deferCategories.size()];
195     for (int i=0; i < deferCategories.size(); i++) {
196         flatArray[i] = new CategoryNode((Category)deferCategories.get(i));
197     }
198     Collections.sort(Arrays.asList(flatArray), comparer);
199 
200     // Add each category.
201     for (int nX = 0; nX < flatArray.length; nX ++) {
202         Category cat = flatArray[nX].getCategory();
203         finishCategory(cat);
204     }
205 
206     // Cleanup.
207     deferCategories = null;
208 }
209 /**
210  * Save new category definition.
211  */
212 private void finishCategory(Category category) {
213     String  [] categoryPath = category.getParentPath();
214     WizardCollectionElement parent = wizardElements;        // ie.- root
215 
216     // Traverse down into parent category.  
217     if (categoryPath != null) {
218         for (int i = 0; i < categoryPath.length; i++) {
219             WizardCollectionElement tempElement = getChildWithID(parent,categoryPath[i]);
220             if (tempElement == null) {
221                 // The parent category is invalid.  By returning here the
222                 // category will be dropped and any wizard within the category
223                 // will be added to the "Other" category.
224                 return;
225             } else
226                 parent = tempElement;
227         }
228     }
229 
230     // If another category already exists with the same id ignore this one.
231     Object   test = getChildWithID(parent, category.getId());
232     if (test != null)
233         return;
234         
235     if (parent != null)
236         createCollectionElement(parent, category.getId(), category.getPluginId(), category.getLabel());
237 }
238 
239 /**
240  * Finishes the recognition of primary wizards.
241  */
242 private void finishPrimary() {
243     if (deferPrimary != null) {
244         ArrayList   primary = new ArrayList  ();
245         for (Iterator   i = deferPrimary.iterator(); i.hasNext();) {
246             String   id = (String  ) i.next();
247             WorkbenchWizardElement element = getWizardElements().findWizard(id, true);
248             if (element != null) {
249                 primary.add(element);
250             }
251         }
252         
253         primaryWizards = (WorkbenchWizardElement []) primary.toArray(new WorkbenchWizardElement [primary.size()]);
254                 
255         deferPrimary = null;
256     } 
257 }
258 
259 /**
260  *  Insert the passed wizard element into the wizard collection appropriately
261  *  based upon its defining extension's CATEGORY tag value
262  *
263  *  @param element WorkbenchWizardElement
264  *  @param extension 
265  *  @param currentResult WizardCollectionElement
266  */
267 private void finishWizard(WorkbenchWizardElement element, IConfigurationElement config) {
268     StringTokenizer   familyTokenizer = new StringTokenizer  (getCategoryStringFor(config),CATEGORY_SEPARATOR);
269 
270     // use the period-separated sections of the current Wizard's category
271     // to traverse through the NamedSolution "tree" that was previously created
272     WizardCollectionElement currentCollectionElement = wizardElements; // ie.- root
273     boolean moveToOther = false;
274     
275     while (familyTokenizer.hasMoreElements()) {
276         WizardCollectionElement tempCollectionElement =
277             getChildWithID(currentCollectionElement,familyTokenizer.nextToken());
278             
279         if (tempCollectionElement == null) {    // can't find the path; bump it to uncategorized
280             moveToOther = true;
281             break;
282         }
283         else
284             currentCollectionElement = tempCollectionElement;
285     }
286     
287     if (moveToOther)
288         moveElementToUncategorizedCategory(wizardElements, element);
289     else
290         currentCollectionElement.add(element);
291 }
292 /**
293  * Finishes the addition of wizards.  The wizards are processed and categorized.
294  */
295 private void finishWizards() {
296     if (deferWizards != null) {
297         Iterator   iter = deferWizards.iterator();
298         while (iter.hasNext()) {
299             WorkbenchWizardElement wizard = (WorkbenchWizardElement)iter.next();
300             IConfigurationElement config = wizard.getConfigurationElement();
301             finishWizard(wizard, config);
302         }
303         deferWizards = null;
304     }
305 }
306 /**
307  *  Return the appropriate category (tree location) for this Wizard.
308  *  If a category is not specified then return a default one.
309  */
310 protected String   getCategoryStringFor(IConfigurationElement config) {
311     String   result = config.getAttribute(ATT_CATEGORY);
312     if (result == null)
313         result = UNCATEGORIZED_WIZARD_CATEGORY;
314 
315     return result;
316 }
317 /**
318  *  Go through the children of  the passed parent and answer the child
319  *  with the passed name.  If no such child is found then return null.
320  *
321  *  @return org.eclipse.ui.internal.model.WizardCollectionElement
322  *  @param parent org.eclipse.ui.internal.model.WizardCollectionElement
323  *  @param childName java.lang.String
324  */
325 protected WizardCollectionElement getChildWithID(WizardCollectionElement parent, String   id) {
326     Object  [] children = parent.getChildren(null);
327     for (int i = 0; i < children.length; ++i) {
328         WizardCollectionElement currentChild = (WizardCollectionElement)children[i];
329         if (currentChild.getId().equals(id))
330             return currentChild;
331     }
332     return null;
333 }
334 /**
335  *  Moves given element to "Other" category, previously creating one if missing.
336  */
337 protected void moveElementToUncategorizedCategory(WizardCollectionElement root, WorkbenchWizardElement element) {
338     WizardCollectionElement otherCategory = getChildWithID(root, UNCATEGORIZED_WIZARD_CATEGORY);
339     
340     if (otherCategory == null)
341         otherCategory = createCollectionElement(root,UNCATEGORIZED_WIZARD_CATEGORY, null, UNCATEGORIZED_WIZARD_CATEGORY_LABEL);
342 
343     otherCategory.add(element);
344 }
345 /**
346  * Removes the empty categories from a wizard collection. 
347  */
348 private void pruneEmptyCategories(WizardCollectionElement parent) {
349     Object   [] children = parent.getChildren(null);
350     for (int nX = 0; nX < children.length; nX ++) {
351         WizardCollectionElement child = (WizardCollectionElement)children[nX];
352         pruneEmptyCategories(child);
353         boolean shouldPrune = projectsOnly || child.getId().equals(FULL_EXAMPLES_WIZARD_CATEGORY);
354         if (child.isEmpty() && shouldPrune)
355             parent.remove(child);
356     }
357 }
358 /**
359  * Implement this method to read element attributes.
360  */
361 public boolean readElement(IConfigurationElement element) {
362     if (element.getName().equals(TAG_CATEGORY)) {
363         deferCategory(element);
364         return true;
365     } 
366     else if (element.getName().equals(TAG_PRIMARYWIZARD)) {
367         if (deferPrimary == null)
368             deferPrimary = new ArrayList  (50);
369         deferPrimary.add(element.getAttribute(ATT_ID));
370 
371         return true;
372     }
373     else {
374     
375         return super.readElement(element);
376     }
377 }
378 /**
379  * Reads the wizards in a registry.  
380  * <p>
381  * This implementation uses a defering strategy.  All of the elements 
382  * (categories, wizards) are read.  The categories are created as the read occurs. 
383  * The wizards are just stored for later addition after the read completes.
384  * This ensures that wizard categorization is performed after all categories
385  * have been read.
386  * </p>
387  */
388 protected void readWizards() {
389     super.readWizards();
390     finishCategories();
391     finishWizards();
392     finishPrimary();
393     if (wizardElements != null) {
394         pruneEmptyCategories(wizardElements);
395     }
396 }
397 
398 /**
399  * Returns the list of wizards that are considered 'primary'.
400  * 
401  * The return value for this method is cached since computing its value
402  * requires non-trivial work.  
403  */
404 public WorkbenchWizardElement [] getPrimaryWizards() {
405     if (!areWizardsRead()) {
406         readWizards();
407     }
408     return primaryWizards;    
409 }
410 
411 /**
412  * Returns whether the wizards have been read already
413  */
414 protected boolean areWizardsRead() {
415     return wizardElements != null;
416 }
417 /**
418  * Returns a list of wizards, project and not.
419  *
420  * The return value for this method is cached since computing its value
421  * requires non-trivial work.  
422  */
423 public WizardCollectionElement getWizardElements() {
424     if (!areWizardsRead()) {
425         readWizards();
426     }
427     return wizardElements;
428 }
429 protected Object  [] getWizardCollectionElements() {
430     if (!areWizardsRead()) {
431         readWizards();
432     }
433     return wizardElements.getChildren();
434 }
435 /* (non-Javadoc)
436  * @see org.eclipse.ui.internal.registry.WizardsRegistryReader#initializeWizard(org.eclipse.ui.internal.dialogs.WorkbenchWizardElement, org.eclipse.core.runtime.IConfigurationElement)
437  */
438 protected boolean initializeWizard(WorkbenchWizardElement element,
439         IConfigurationElement config) {
440     boolean result = super.initializeWizard(element, config);
441     if (!result)
442         return result;
443     element.setHelpHref(config.getAttribute(ATT_HELP_HREF));
444     String   descImage = config.getAttribute(ATT_DESCRIPTION_IMAGE);
445     if (descImage != null) {
446         IExtension extension = config.getDeclaringExtension();
447         String   extendingPluginId = extension.getNamespace();
448         ImageDescriptor image =
449             AbstractUIPlugin.imageDescriptorFromPlugin(extendingPluginId, descImage);
450         element.setDescriptionImage(image);
451     }
452     return result;
453 }
454 }
455
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags