Source code: org/eclipse/ui/internal/registry/RegistryReader.java
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.util.Arrays;
14 import java.util.Collections;
15 import java.util.Comparator;
16
17 import org.eclipse.core.runtime.IConfigurationElement;
18 import org.eclipse.core.runtime.IExtension;
19 import org.eclipse.core.runtime.IExtensionPoint;
20 import org.eclipse.core.runtime.IExtensionRegistry;
21 import org.eclipse.ui.internal.WorkbenchPlugin;
22
23 /**
24 * Template implementation of a registry reader that creates objects
25 * representing registry contents. Typically, an extension
26 * contains one element, but this reader handles multiple
27 * elements per extension.
28 *
29 * To start reading the extensions from the registry for an
30 * extension point, call the method <code>readRegistry</code>.
31 *
32 * To read children of an IConfigurationElement, call the
33 * method <code>readElementChildren</code> from your implementation
34 * of the method <code>readElement</code>, as it will not be
35 * done by default.
36 */
37 public abstract class RegistryReader {
38 protected static final String TAG_DESCRIPTION = "description"; //$NON-NLS-1$
39 // for dynamic UI - remove this cache to avoid inconsistency
40 //protected static Hashtable extensionPoints = new Hashtable();
41 /**
42 * The constructor.
43 */
44 protected RegistryReader() {
45 }
46 /**
47 * This method extracts description as a subelement of
48 * the given element.
49 * @return description string if defined, or empty string
50 * if not.
51 */
52 protected String getDescription(IConfigurationElement config) {
53 IConfigurationElement [] children = config.getChildren(TAG_DESCRIPTION);
54 if (children.length>=1) {
55 return children[0].getValue();
56 }
57 return "";//$NON-NLS-1$
58 }
59 /**
60 * Logs the error in the workbench log using the provided
61 * text and the information in the configuration element.
62 */
63 protected static void logError(IConfigurationElement element, String text) {
64 IExtension extension = element.getDeclaringExtension();
65 StringBuffer buf = new StringBuffer();
66 buf.append("Plugin " + extension.getNamespace() + ", extension " + extension.getExtensionPointUniqueIdentifier());//$NON-NLS-2$//$NON-NLS-1$
67 buf.append("\n"+text);//$NON-NLS-1$
68 WorkbenchPlugin.log(buf.toString());
69 }
70 /**
71 * Logs a very common registry error when a required attribute is missing.
72 */
73 protected static void logMissingAttribute(IConfigurationElement element, String attributeName) {
74 logError(element, "Required attribute '"+attributeName+"' not defined");//$NON-NLS-2$//$NON-NLS-1$
75 }
76
77 /**
78 * Logs a very common registry error when a required child is missing.
79 */
80 protected static void logMissingElement(IConfigurationElement element, String elementName) {
81 logError(element, "Required sub element '"+elementName+"' not defined");//$NON-NLS-2$//$NON-NLS-1$
82 }
83
84 /**
85 * Logs a registry error when the configuration element is unknown.
86 */
87 protected static void logUnknownElement(IConfigurationElement element) {
88 logError(element, "Unknown extension tag found: " + element.getName());//$NON-NLS-1$
89 }
90 /**
91 * Apply a reproducable order to the list of extensions
92 * provided, such that the order will not change as
93 * extensions are added or removed.
94 */
95 protected IExtension[] orderExtensions(IExtension[] extensions) {
96 // By default, the order is based on plugin id sorted
97 // in ascending order. The order for a plugin providing
98 // more than one extension for an extension point is
99 // dependent in the order listed in the XML file.
100 IExtension[] sortedExtension = new IExtension[extensions.length];
101 System.arraycopy(extensions, 0, sortedExtension, 0, extensions.length);
102 Comparator comparer = new Comparator() {
103 public int compare(Object arg0, Object arg1) {
104 String s1 = ((IExtension)arg0).getNamespace();
105 String s2 = ((IExtension)arg1).getNamespace();
106 return s1.compareToIgnoreCase(s2);
107 }
108 };
109 Collections.sort(Arrays.asList(sortedExtension), comparer);
110 return sortedExtension;
111 }
112 /**
113 * Implement this method to read element's attributes.
114 * If children should also be read, then implementor
115 * is responsible for calling <code>readElementChildren</code>.
116 * Implementor is also responsible for logging missing
117 * attributes.
118 *
119 * @return true if element was recognized, false if not.
120 */
121 protected abstract boolean readElement(IConfigurationElement element);
122 /**
123 * Read the element's children. This is called by
124 * the subclass' readElement method when it wants
125 * to read the children of the element.
126 */
127 protected void readElementChildren(IConfigurationElement element) {
128 readElements(element.getChildren());
129 }
130 /**
131 * Read each element one at a time by calling the
132 * subclass implementation of <code>readElement</code>.
133 *
134 * Logs an error if the element was not recognized.
135 */
136 protected void readElements(IConfigurationElement[] elements) {
137 for (int i = 0; i < elements.length; i++) {
138 if (!readElement(elements[i]))
139 logUnknownElement(elements[i]);
140 }
141 }
142 /**
143 * Read one extension by looping through its
144 * configuration elements.
145 */
146 protected void readExtension(IExtension extension) {
147 readElements(extension.getConfigurationElements());
148 }
149 /**
150 * Start the registry reading process using the
151 * supplied plugin ID and extension point.
152 */
153 public void readRegistry(IExtensionRegistry registry, String pluginId, String extensionPoint) {
154 IExtensionPoint point = registry.getExtensionPoint(pluginId, extensionPoint);
155 if (point == null) return;
156 IExtension[] extensions = point.getExtensions();
157 extensions = orderExtensions(extensions);
158 for (int i = 0; i < extensions.length; i++)
159 readExtension(extensions[i]);
160 }
161 }