RegistryReader


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 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.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      
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      /**
48       * Logs the error in the workbench log using the provided
49       * text and the information in the configuration element.
50       */
51      protected static void logError(IConfigurationElement element, String   text) {
52          IExtension extension = element.getDeclaringExtension();
53          StringBuffer   buf = new StringBuffer  ();
54          buf
55                  .append("Plugin " + extension.getNamespace() + ", extension " + extension.getExtensionPointUniqueIdentifier());//$NON-NLS-2$//$NON-NLS-1$
56          buf.append("\n" + text);//$NON-NLS-1$
57          WorkbenchPlugin.log(buf.toString());
58      }
59  
60      /**
61       * Logs a very common registry error when a required attribute is missing.
62       */
63      protected static void logMissingAttribute(IConfigurationElement element,
64              String   attributeName) {
65          logError(element,
66                  "Required attribute '" + attributeName + "' not defined");//$NON-NLS-2$//$NON-NLS-1$
67      }
68  
69      /**
70       * Logs a very common registry error when a required child is missing.
71       */
72      protected static void logMissingElement(IConfigurationElement element,
73              String   elementName) {
74          logError(element,
75                  "Required sub element '" + elementName + "' not defined");//$NON-NLS-2$//$NON-NLS-1$
76      }
77  
78      /**
79       * Logs a registry error when the configuration element is unknown.
80       */
81      protected static void logUnknownElement(IConfigurationElement element) {
82          logError(element, "Unknown extension tag found: " + element.getName());//$NON-NLS-1$
83      }
84  
85      /**
86       * Apply a reproducable order to the list of extensions
87       * provided, such that the order will not change as
88       * extensions are added or removed.
89       * @param extensions the extensions to order
90       * @return ordered extensions
91       */
92      public static IExtension[] orderExtensions(IExtension[] extensions) {
93          // By default, the order is based on plugin id sorted
94          // in ascending order. The order for a plugin providing
95          // more than one extension for an extension point is
96          // dependent in the order listed in the XML file.
97          IExtension[] sortedExtension = new IExtension[extensions.length];
98          System.arraycopy(extensions, 0, sortedExtension, 0, extensions.length);
99          Comparator   comparer = new Comparator  () {
100             public int compare(Object   arg0, Object   arg1) {
101                 String   s1 = ((IExtension) arg0).getNamespace();
102                 String   s2 = ((IExtension) arg1).getNamespace();
103                 return s1.compareToIgnoreCase(s2);
104             }
105         };
106         Collections.sort(Arrays.asList(sortedExtension), comparer);
107         return sortedExtension;
108     }
109 
110     /**
111      * Implement this method to read element's attributes.
112      * If children should also be read, then implementor
113      * is responsible for calling <code>readElementChildren</code>.
114      * Implementor is also responsible for logging missing 
115      * attributes.
116      *
117      * @return true if element was recognized, false if not.
118      */
119     protected abstract boolean readElement(IConfigurationElement element);
120 
121     /**
122      * Read the element's children. This is called by
123      * the subclass' readElement method when it wants
124      * to read the children of the element.
125      */
126     protected void readElementChildren(IConfigurationElement element) {
127         readElements(element.getChildren());
128     }
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 
144     /**
145      * Read one extension by looping through its
146      * configuration elements.
147      */
148     protected void readExtension(IExtension extension) {
149         readElements(extension.getConfigurationElements());
150     }
151 
152     /**
153      *  Start the registry reading process using the
154      * supplied plugin ID and extension point.
155      * 
156      * @param registry the registry to read from
157      * @param pluginId the plugin id of the extenion point
158      * @param extensionPoint the extension point id
159      */
160     public void readRegistry(IExtensionRegistry registry, String   pluginId,
161             String   extensionPoint) {
162         IExtensionPoint point = registry.getExtensionPoint(pluginId,
163                 extensionPoint);
164         if (point == null) {
165             return;
166         }
167         IExtension[] extensions = point.getExtensions();
168         extensions = orderExtensions(extensions);
169         for (int i = 0; i < extensions.length; i++) {
170             readExtension(extensions[i]);
171         }
172     }
173     
174     /**
175      * Utility for extracting the description child of an element.
176      * 
177      * @param configElement the element
178      * @return the description
179      * @since 3.1
180      */
181     public static String   getDescription(IConfigurationElement configElement) {
182         IConfigurationElement[] children = configElement.getChildren(IWorkbenchRegistryConstants.TAG_DESCRIPTION);
183         if (children.length >= 1) {
184             return children[0].getValue();
185         }
186         return "";//$NON-NLS-1$
187     }
188     
189     /**
190      * Utility for extracting the value of a class attribute or a nested class
191      * element that follows the pattern set forth by
192      * {@link org.eclipse.core.runtime.IExecutableExtension}.
193      * 
194      * @param configElement
195      *            the element
196      * @param classAttributeName
197      *            the name of the class attribute to check
198      * @return the value of the attribute or nested class element
199      * @since 3.1
200      */
201     public static String   getClassValue(IConfigurationElement configElement, String   classAttributeName) {
202         String   className = configElement.getAttribute(classAttributeName);
203         if (className != null) {
204             return className;
205         }
206         IConfigurationElement [] candidateChildren = configElement.getChildren(classAttributeName);
207         if (candidateChildren.length == 0) {
208             return null;
209         }
210     
211         return candidateChildren[0].getAttribute(IWorkbenchRegistryConstants.ATT_CLASS);
212     }
213 }
214
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags