Java > Open Source Codes > org > eclipse > ui > internal > cheatsheets > registry > CheatSheetRegistryReader


1 /*******************************************************************************
2  * Copyright (c) 2002, 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.ui.internal.cheatsheets.registry;
12
13 import com.ibm.icu.text.Collator;
14 import java.util.ArrayList ;
15 import java.util.HashMap ;
16 import java.util.Iterator ;
17 import java.util.Map ;
18 import java.util.Set ;
19 import java.util.StringTokenizer ;
20
21 import org.eclipse.core.runtime.*;
22 import org.eclipse.ui.internal.cheatsheets.*;
23 import org.eclipse.ui.model.AdaptableList;
24
25 /**
26  * Instances access the registry that is provided at creation time
27  * in order to determine the contained CheatSheet Contents
28  */
29 public class CheatSheetRegistryReader extends RegistryReader implements IRegistryChangeListener {
30
31     private class CategoryNode {
32         private Category category;
33         private String path;
34         public CategoryNode(Category cat) {
35             category = cat;
36             path = ICheatSheetResource.EMPTY_STRING;
37             String [] categoryPath = category.getParentPath();
38             if (categoryPath != null) {
39                 for (int nX = 0; nX < categoryPath.length; nX++) {
40                     path += categoryPath[nX] + '/';
41                 }
42             }
43             path += cat.getId();
44         }
45         public Category getCategory() {
46             return category;
47         }
48         public String getPath() {
49             return path;
50         }
51     }
52
53     /**
54      * Represents a taskEditor entry in the registry
55      */
56     public class TaskEditorNode {
57         private String className;
58         private String iconPath;
59         private String id;
60         private String pluginId;
61         public void setClassName(String className) {
62             this.className = className;
63         }
64         public String getClassName() {
65             return className;
66         }
67         public void setIconPath(String iconPath) {
68             this.iconPath = iconPath;
69         }
70         public String getIconPath() {
71             return iconPath;
72         }
73         public void setId(String id) {
74             this.id = id;
75         }
76         public String getId() {
77             return id;
78         }
79         public void setPluginId(String pluginId) {
80             this.pluginId = pluginId;
81         }
82         public String getPluginId() {
83             return pluginId;
84         }
85     }
86     
87     /**
88      * Represents a taskExplorer entry in the registry
89      */
90     public class TaskExplorerNode {
91         private String className;
92         private String iconPath;
93         private String name;
94         private String id;
95         private String pluginId;
96         public void setClassName(String className) {
97             this.className = className;
98         }
99         public String getClassName() {
100             return className;
101         }
102         public void setIconPath(String iconPath) {
103             this.iconPath = iconPath;
104         }
105         public String getIconPath() {
106             return iconPath;
107         }
108         public void setName(String name) {
109             this.name = name;
110         }
111         public String getName() {
112             return name;
113         }
114         public void setId(String id) {
115             this.id = id;
116         }
117         public String getId() {
118             return id;
119         }
120         public void setPluginId(String pluginId) {
121             this.pluginId = pluginId;
122         }
123         public String getPluginId() {
124             return pluginId;
125         }
126     }
127
128     // constants
129 private final static String ATT_CATEGORY = "category"; //$NON-NLS-1$
130 public final static String ATT_CONTENTFILE = "contentFile"; //$NON-NLS-1$
131 protected final static String ATT_ICON = "icon"; //$NON-NLS-1$
132 protected final static String ATT_ID = "id"; //$NON-NLS-1$
133 protected final static String ATT_LISTENERCLASS = "listener"; //$NON-NLS-1$
134 protected final static String ATT_NAME = "name"; //$NON-NLS-1$
135 protected final static String ATT_CLASS = "class"; //$NON-NLS-1$
136 private final static String ATT_COMPOSITE = "composite"; //$NON-NLS-1$
137 private final static String CATEGORY_SEPARATOR = "/"; //$NON-NLS-1$
138 private final static String ATT_ITEM_ATTRIBUTE = "itemAttribute"; //$NON-NLS-1$
139 private static CheatSheetRegistryReader instance;
140     private final static String TAG_CATEGORY = "category"; //$NON-NLS-1$
141 public final static String TAG_CHEATSHEET = "cheatsheet"; //$NON-NLS-1$
142 protected final static String TAG_ITEM_EXTENSION = "itemExtension"; //$NON-NLS-1$
143 protected final static String TAG_TASK_EDITOR = "taskEditor"; //$NON-NLS-1$
144 protected final static String TAG_TASK_EXPLORER = "taskExplorer"; //$NON-NLS-1$
145 protected final static String trueString = "TRUE"; //$NON-NLS-1$
146 private final static String UNCATEGORIZED_CHEATSHEET_CATEGORY = "org.eclipse.ui.Other"; //$NON-NLS-1$
147 private final static String UNCATEGORIZED_CHEATSHEET_CATEGORY_LABEL = Messages.CHEAT_SHEET_OTHER_CATEGORY;
148     public final static String CHEAT_SHEET_CONTENT = "cheatSheetContent"; //$NON-NLS-1$
149
150     /**
151      * Returns a list of cheatsheets, project and not.
152      *
153      * The return value for this method is cached since computing its value
154      * requires non-trivial work.
155      */
156     public static CheatSheetRegistryReader getInstance() {
157         if (instance == null) {
158             instance = new CheatSheetRegistryReader();
159             IExtensionRegistry xregistry = Platform.getExtensionRegistry();
160             xregistry.addRegistryChangeListener(instance, ICheatSheetResource.CHEAT_SHEET_PLUGIN_ID);
161         }
162
163         return instance;
164     }
165
166     protected ArrayList cheatsheetItemExtensions;
167     protected AdaptableList cheatsheets;
168     private ArrayList deferCategories = null;
169     private ArrayList deferCheatSheets = null;
170     private final String csItemExtension = "cheatSheetItemExtension"; //$NON-NLS-1$
171 protected Map taskExplorers = new HashMap ();
172     protected Map taskEditors = new HashMap ();
173
174     /**
175      * Create an instance of this class.
176      */
177     private CheatSheetRegistryReader() {
178     }
179
180     /**
181      * Adds new cheatsheet to the provided collection. Override to
182      * provide more logic.
183      * <p>
184      * This implementation uses a defering strategy. For more info see
185      * <code>readCheatSheets</code>.
186      * </p>
187      */
188     protected void addNewElementToResult(CheatSheetElement element, IConfigurationElement config, AdaptableList result) {
189         deferCheatSheet(element);
190     }
191
192     /**
193      * Returns a new CheatSheetElement configured according to the parameters
194      * contained in the passed Registry.
195      *
196      * May answer null if there was not enough information in the Extension to create
197      * an adequate cheatsheet
198      */
199     protected CheatSheetElement createCheatSheetElement(IConfigurationElement element) {
200         // CheatSheetElements must have a name attribute
201 String nameString = element.getAttribute(ATT_NAME);
202         if (nameString == null) {
203             logMissingAttribute(element, ATT_NAME);
204             return null;
205         }
206         CheatSheetElement result = new CheatSheetElement(nameString);
207         if (initializeCheatSheet(result, element))
208             return result; // ie.- initialization was successful
209
210         return null;
211     }
212
213     /**
214      * Create and answer a new CheatSheetCollectionElement, configured as a
215      * child of <code>parent</code>
216      *
217      * @return org.eclipse.ui.internal.model.CheatSheetCollectionElement
218      * @param parent org.eclipse.ui.internal.model.CheatSheetCollectionElement
219      * @param childName java.lang.String
220      */
221     protected CheatSheetCollectionElement createCollectionElement(CheatSheetCollectionElement parent, String pluginId, String id, String label) {
222         CheatSheetCollectionElement newElement = new CheatSheetCollectionElement(pluginId, id, label, parent);
223
224         parent.add(newElement);
225         return newElement;
226     }
227
228     /**
229      * Creates empty element collection. Overrider to fill
230      * initial elements, if needed.
231      */
232     protected AdaptableList createEmptyCheatSheetCollection() {
233         return new CheatSheetCollectionElement(null, "root", "root", null); //$NON-NLS-1$//$NON-NLS-2$
234 }
235
236     /**
237      * Stores a category element for deferred addition.
238      */
239     private void deferCategory(IConfigurationElement config) {
240         // Create category.
241 Category category = null;
242         try {
243             category = new Category(config);
244         } catch (CoreException e) {
245             CheatSheetPlugin.getPlugin().getLog().log(e.getStatus());
246             return;
247         }
248
249         // Defer for later processing.
250 if (deferCategories == null)
251             deferCategories = new ArrayList (20);
252         deferCategories.add(category);
253     }
254
255     /**
256      * Stores a cheatsheet element for deferred addition.
257      */
258     private void deferCheatSheet(CheatSheetElement element) {
259         if (deferCheatSheets == null)
260             deferCheatSheets = new ArrayList (50);
261         deferCheatSheets.add(element);
262     }
263
264     /**
265      * Returns the first cheatsheet
266      * with a given id.
267      */
268     public CheatSheetElement findCheatSheet(String id) {
269         Object [] cheatsheetsList = getCheatSheets().getChildren();
270         for (int nX = 0; nX < cheatsheetsList.length; nX++) {
271             CheatSheetCollectionElement collection = (CheatSheetCollectionElement) cheatsheetsList[nX];
272             CheatSheetElement element = collection.findCheatSheet(id, true);
273             if (element != null)
274                 return element;
275         }
276         return null;
277     }
278     
279     /**
280      * Returns the first task editor
281      * with a given id.
282      */
283     public TaskEditorNode findTaskEditor(String id) {
284         if (cheatsheets == null) {
285             readCheatSheets(); // Ensure that the registry has been read
286 }
287         return (TaskEditorNode)taskEditors.get(id);
288     }
289     
290     /**
291      * Returns the first task explorer
292      * with a given id.
293      */
294     public TaskExplorerNode findTaskExplorer(String id) {
295         if (cheatsheets == null) {
296             readCheatSheets(); // Ensure that the registry has been read
297 }
298         return (TaskExplorerNode)taskExplorers.get(id);
299     }
300     
301     /**
302      * Get the list of explorer ids
303      * @return an iterator for the explorer ids
304      */
305     public String [] getExplorerIds() {
306         if (cheatsheets == null) {
307             readCheatSheets(); // Ensure that the registry has been read
308 }
309         Set keys = taskExplorers.keySet();
310         return (String []) keys.toArray(new String [keys.size()]);
311     }
312
313     /**
314      * Finishes the addition of categories. The categories are sorted and
315      * added in a root to depth traversal.
316      */
317     private void finishCategories() {
318         // If no categories just return.
319 if (deferCategories == null)
320             return;
321
322         // Sort categories by flattened name.
323 CategoryNode[] flatArray = new CategoryNode[deferCategories.size()];
324         for (int i = 0; i < deferCategories.size(); i++) {
325             flatArray[i] = new CategoryNode((Category) deferCategories.get(i));
326         }
327         Sorter sorter = new Sorter() {
328             private Collator collator = Collator.getInstance();
329
330             public boolean compare(Object o1, Object o2) {
331                 String s1 = ((CategoryNode) o1).getPath();
332                 String s2 = ((CategoryNode) o2).getPath();
333                 return collator.compare(s2, s1) > 0;
334             }
335         };
336         Object [] sortedCategories = sorter.sort(flatArray);
337
338         // Add each category.
339 for (int nX = 0; nX < sortedCategories.length; nX++) {
340             Category cat = ((CategoryNode) sortedCategories[nX]).getCategory();
341             finishCategory(cat);
342         }
343
344         // Cleanup.
345 deferCategories = null;
346     }
347
348     /**
349      * Save new category definition.
350      */
351     private void finishCategory(Category category) {
352         CheatSheetCollectionElement currentResult = (CheatSheetCollectionElement) cheatsheets;
353
354         String [] categoryPath = category.getParentPath();
355         CheatSheetCollectionElement parent = currentResult; // ie.- root
356
357         // Traverse down into parent category.
358 if (categoryPath != null) {
359             for (int i = 0; i < categoryPath.length; i++) {
360                 CheatSheetCollectionElement tempElement = getChildWithID(parent, categoryPath[i]);
361                 if (tempElement == null) {
362                     // The parent category is invalid. By returning here the
363 // category will be dropped and any cheatsheet within the category
364 // will be added to the "Other" category.
365 return;
366                 }
367                 parent = tempElement;
368             }
369         }
370
371         // If another category already exists with the same id ignore this one.
372 Object test = getChildWithID(parent, category.getId());
373         if (test != null)
374             return;
375
376         if (parent != null)
377             createCollectionElement(parent, category.getPluginId(), category.getId(), category.getLabel());
378     }
379
380     /**
381      * Insert the passed cheatsheet element into the cheatsheet collection appropriately
382      * based upon its defining extension's CATEGORY tag value
383      *
384      * @param element CheatSheetElement
385      * @param extension
386      * @param currentResult CheatSheetCollectionElement
387      */
388     private void finishCheatSheet(CheatSheetElement element, IConfigurationElement config, AdaptableList result) {
389         CheatSheetCollectionElement currentResult = (CheatSheetCollectionElement) result;
390         StringTokenizer familyTokenizer = new StringTokenizer (getCategoryStringFor(config), CATEGORY_SEPARATOR);
391
392         // use the period-separated sections of the current CheatSheet's category
393 // to traverse through the NamedSolution "tree" that was previously created
394 CheatSheetCollectionElement currentCollectionElement = currentResult; // ie.- root
395 boolean moveToOther = false;
396
397         while (familyTokenizer.hasMoreElements()) {
398             CheatSheetCollectionElement tempCollectionElement = getChildWithID(currentCollectionElement, familyTokenizer.nextToken());
399
400             if (tempCollectionElement == null) { // can't find the path; bump it to uncategorized
401 moveToOther = true;
402                 break;
403             }
404             currentCollectionElement = tempCollectionElement;
405         }
406
407         if (moveToOther)
408             moveElementToUncategorizedCategory(currentResult, element);
409         else
410             currentCollectionElement.add(element);
411     }
412
413     /**
414      * Finishes the addition of cheatsheets. The cheatsheets are processed and categorized.
415      */
416     private void finishCheatSheets() {
417         if (deferCheatSheets != null) {
418             Iterator iter = deferCheatSheets.iterator();
419             while (iter.hasNext()) {
420                 CheatSheetElement cheatsheet = (CheatSheetElement) iter.next();
421                 IConfigurationElement config = cheatsheet.getConfigurationElement();
422                 finishCheatSheet(cheatsheet, config, cheatsheets);
423             }
424             deferCheatSheets = null;
425         }
426     }
427
428     /**
429      * Return the appropriate category (tree location) for this CheatSheet.
430      * If a category is not specified then return a default one.
431      */
432     protected String getCategoryStringFor(IConfigurationElement config) {
433         String result = config.getAttribute(ATT_CATEGORY);
434         if (result == null)
435             result = UNCATEGORIZED_CHEATSHEET_CATEGORY;
436
437         return result;
438     }
439
440     /**
441      * Returns a list of cheatsheets, project and not.
442      *
443      * The return value for this method is cached since computing its value
444      * requires non-trivial work.
445      */
446     public AdaptableList getCheatSheets() {
447         if (cheatsheets == null)
448             readCheatSheets();
449         return cheatsheets;
450     }
451
452     /**
453      * Go through the children of the passed parent and answer the child
454      * with the passed name. If no such child is found then return null.
455      *
456      * @return org.eclipse.ui.internal.model.CheatSheetCollectionElement
457      * @param parent org.eclipse.ui.internal.model.CheatSheetCollectionElement
458      * @param childName java.lang.String
459      */
460     protected CheatSheetCollectionElement getChildWithID(CheatSheetCollectionElement parent, String id) {
461         Object [] children = parent.getChildren();
462         for (int i = 0; i < children.length; ++i) {
463             CheatSheetCollectionElement currentChild = (CheatSheetCollectionElement) children[i];
464             if (currentChild.getId().equals(id))
465                 return currentChild;
466         }
467         return null;
468     }
469
470     /**
471      * Initialize the passed element's properties based on the contents of
472      * the passed registry. Answer a boolean indicating whether the element
473      * was able to be adequately initialized.
474      *
475      * @return boolean
476      * @param element CheatSheetElement
477      * @param extension Extension
478      */
479     protected boolean initializeCheatSheet(CheatSheetElement element, IConfigurationElement config) {
480         element.setID(config.getAttribute(ATT_ID));
481         element.setDescription(getDescription(config));
482         element.setConfigurationElement(config);
483         element.setRegistered(true);
484
485         String contentFile = config.getAttribute(ATT_CONTENTFILE);
486         if (contentFile != null) {
487             element.setContentFile(contentFile);
488         }
489
490         // ensure that a contentfile was specified
491 if (element.getConfigurationElement() == null || element.getContentFile() == null) {
492             logMissingAttribute(config, ATT_CONTENTFILE);
493             return false;
494         }
495
496         String listenerClass = config.getAttribute(ATT_LISTENERCLASS);
497         if (listenerClass != null) {
498             element.setListenerClass(listenerClass);
499         }
500         String composite = config.getAttribute(ATT_COMPOSITE);
501         if (composite != null) {
502             element.setComposite(composite.equalsIgnoreCase(trueString));
503         }
504         return true;
505     }
506
507     /**
508      * Moves given element to "Other" category, previously creating one if missing.
509      */
510     protected void moveElementToUncategorizedCategory(CheatSheetCollectionElement root, CheatSheetElement element) {
511         CheatSheetCollectionElement otherCategory = getChildWithID(root, UNCATEGORIZED_CHEATSHEET_CATEGORY);
512
513         if (otherCategory == null)
514             otherCategory = createCollectionElement(root, null, UNCATEGORIZED_CHEATSHEET_CATEGORY, UNCATEGORIZED_CHEATSHEET_CATEGORY_LABEL);
515
516         otherCategory.add(element);
517     }
518
519     /**
520      * Removes the empty categories from a cheatsheet collection.
521      */
522     private void pruneEmptyCategories(CheatSheetCollectionElement parent) {
523         Object [] children = parent.getChildren();
524         for (int nX = 0; nX < children.length; nX++) {
525             CheatSheetCollectionElement child = (CheatSheetCollectionElement) children[nX];
526             pruneEmptyCategories(child);
527         }
528     }
529
530     /**
531      * Reads the cheatsheets in a registry.
532      * <p>
533      * This implementation uses a defering strategy. All of the elements
534      * (categories, cheatsheets) are read. The categories are created as the read occurs.
535      * The cheatsheets are just stored for later addition after the read completes.
536      * This ensures that cheatsheet categorization is performed after all categories
537      * have been read.
538      * </p>
539      */
540     protected void readCheatSheets() {
541         IExtensionRegistry xregistry = Platform.getExtensionRegistry();
542
543         if (cheatsheets == null) {
544             cheatsheets = createEmptyCheatSheetCollection();
545             readRegistry(xregistry, ICheatSheetResource.CHEAT_SHEET_PLUGIN_ID, CHEAT_SHEET_CONTENT);
546         }
547
548         finishCategories();
549         finishCheatSheets();
550
551         if (cheatsheets != null) {
552             CheatSheetCollectionElement parent = (CheatSheetCollectionElement) cheatsheets;
553             pruneEmptyCategories(parent);
554         }
555     }
556
557     public ArrayList readItemExtensions() {
558         if (cheatsheetItemExtensions == null) {
559             cheatsheetItemExtensions = new ArrayList ();
560
561             IExtensionRegistry xregistry = Platform.getExtensionRegistry();
562             //Now read the cheat sheet extensions.
563 readRegistry(xregistry, ICheatSheetResource.CHEAT_SHEET_PLUGIN_ID, csItemExtension);
564         }
565
566         return cheatsheetItemExtensions;
567     }
568
569     private void createItemExtensionElement(IConfigurationElement element) {
570         String className = element.getAttribute(ATT_CLASS);
571         String itemAttribute = element.getAttribute(ATT_ITEM_ATTRIBUTE);
572
573         // ensure that a class was specified
574 if (className == null) {
575             logMissingAttribute(element, ATT_CLASS);
576             return;
577         }
578         // ensure that a itemAttribute was specified
579 if (itemAttribute == null) {
580             logMissingAttribute(element, ATT_ITEM_ATTRIBUTE);
581             return;
582         }
583
584         CheatSheetItemExtensionElement itemExtensionElement = new CheatSheetItemExtensionElement();
585         itemExtensionElement.setClassName(className);
586         itemExtensionElement.setItemAttribute(itemAttribute);
587         itemExtensionElement.setConfigurationElement(element);
588
589         cheatsheetItemExtensions.add(itemExtensionElement);
590     }
591     
592     /*
593      * Get a required attribute. Log an error if it has no value.
594      */
595     private String getAndCheckAttribute(IConfigurationElement element, String name) {
596         String result = element.getAttribute(name);
597         if (result == null) {
598             logMissingAttribute(element, name);
599         }
600         return result;
601     }
602     
603     private void createTaskExplorerElement(IConfigurationElement element) {
604         String icon = element.getAttribute(ATT_ICON);
605         String className = getAndCheckAttribute(element, ATT_CLASS);
606         String name = getAndCheckAttribute(element, ATT_NAME);
607         String id = getAndCheckAttribute(element, ATT_ID);
608         String pluginId = element.getContributor().getName();
609         if (id != null && className != null && name != null ) {
610             TaskExplorerNode node = new TaskExplorerNode();
611             node.setId(id);
612             node.setIconPath(icon);
613             node.setClassName(className);
614             node.setName(name);
615             node.setPluginId(pluginId);
616             taskExplorers.put(id, node);
617         }
618     }
619
620     private void createTaskEditorElement(IConfigurationElement element) {
621         String icon = getAndCheckAttribute(element, ATT_ICON);
622         String className = getAndCheckAttribute(element, ATT_CLASS);
623         String id = getAndCheckAttribute(element, ATT_ID);
624         String pluginId = element.getContributor().getName();
625         if (id != null && className != null && icon != null ) {
626             TaskEditorNode node = new TaskEditorNode();
627             node.setId(id);
628             node.setIconPath(icon);
629             node.setClassName(className);
630             node.setPluginId(pluginId);
631             taskEditors.put(id, node);
632         }
633     }
634
635     /**
636      * Implement this method to read element attributes.
637      */
638     protected boolean readElement(IConfigurationElement element) {
639         if (element.getName().equals(TAG_CATEGORY)) {
640             deferCategory(element);
641             return true;
642         } else if (element.getName().equals(TAG_ITEM_EXTENSION)) {
643             createItemExtensionElement(element);
644             return true;
645         } else if (element.getName().equals(TAG_TASK_EDITOR)) {
646             createTaskEditorElement(element);
647             return true;
648         } else if (element.getName().equals(TAG_TASK_EXPLORER)) {
649             createTaskExplorerElement(element);
650             return true;
651         } else {
652             if (!element.getName().equals(TAG_CHEATSHEET))
653                 return false;
654
655             CheatSheetElement cheatsheet = createCheatSheetElement(element);
656             if (cheatsheet != null)
657                 addNewElementToResult(cheatsheet, element, cheatsheets);
658             return true;
659         }
660     }
661
662     /* (non-Javadoc)
663      * @see org.eclipse.core.runtime.IRegistryChangeListener#registryChanged(org.eclipse.core.runtime.IRegistryChangeEvent)
664      */
665     public void registryChanged(IRegistryChangeEvent event) {
666         IExtensionDelta[] cheatSheetDeltas = event.getExtensionDeltas(ICheatSheetResource.CHEAT_SHEET_PLUGIN_ID, CHEAT_SHEET_CONTENT);
667         if (cheatSheetDeltas.length > 0) {
668             // reset the list of cheat sheets, it will be build on demand
669 cheatsheets = null;
670         }
671
672         IExtensionDelta[] itemExtensionDeltas = event.getExtensionDeltas(ICheatSheetResource.CHEAT_SHEET_PLUGIN_ID, csItemExtension);
673         if (itemExtensionDeltas.length > 0) {
674             // reset the list of cheat sheets item extensions, it will be build on demand
675 cheatsheetItemExtensions = null;
676         }
677     }
678     
679     public void stop() {
680         IExtensionRegistry xregistry = Platform.getExtensionRegistry();
681         xregistry.removeRegistryChangeListener(instance);
682
683         instance = null;
684     }
685 }
686

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags