RegistryReader


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.ui.internal.navigator.extensions;
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.core.runtime.Platform;
22  import org.eclipse.ui.internal.navigator.NavigatorPlugin;
23  
24  /**
25   * Template implementation of a registry reader that creates objects representing registry contents.
26   * Typically, an extension contains one element, but this reader handles multiple elements per
27   * extension.
28   * 
29   * To start reading the extensions from the registry for an extension point, call the method
30   * <code>readRegistry</code>.
31   * 
32   * To read children of an IConfigurationElement, call the method <code>readElementChildren</code>
33   * from your implementation of the method <code>readElement</code>, as it will not be done by
34   * default.
35   * <p>
36   * <strong>EXPERIMENTAL</strong>. This class or interface has been added as part of a work in
37   * progress. There is a guarantee neither that this API will work nor that it will remain the same.
38   * Please do not use this API without consulting with the Platform/UI team.
39   * </p>
40   * 
41   * @since 3.2
42   */
43  public abstract class RegistryReader {
44  
45      protected static final String   TAG_DESCRIPTION = "description"; //$NON-NLS-1$
46  
47      private boolean isInitialized;
48      private final String   extensionPointId;
49      private final String   pluginId;
50      private final IExtensionRegistry registry;
51  
52      /**
53       * The constructor.
54       */
55      protected RegistryReader(String   aPluginId, String   anExtensionPoint) {
56          this.registry = Platform.getExtensionRegistry();
57          this.pluginId = aPluginId;
58          this.extensionPointId = anExtensionPoint;
59      }
60  
61      /**
62       * This method extracts description as a subelement of the given element.
63       * 
64       * @return description string if defined, or empty string if not.
65       */
66      protected String   getDescription(IConfigurationElement config) {
67          IConfigurationElement[] children = config.getChildren(TAG_DESCRIPTION);
68          if (children.length >= 1) {
69              return children[0].getValue();
70          }
71          return "";//$NON-NLS-1$
72      }
73  
74      /**
75       * Logs the error in the workbench log using the provided text and the information in the
76       * configuration element.
77       */
78      protected static void logError(IConfigurationElement element, String   text) {
79          IExtension extension = element.getDeclaringExtension();
80          StringBuffer   buf = new StringBuffer  ();
81          buf.append("Plugin " + extension.getNamespaceIdentifier() + ", extension " + extension.getExtensionPointUniqueIdentifier());//$NON-NLS-2$//$NON-NLS-1$
82          buf.append("\n" + text);//$NON-NLS-1$
83          NavigatorPlugin.logError(0, buf.toString(), null);
84      }
85  
86      /**
87       * Logs a very common registry error when a required attribute is missing.
88       */
89      protected static void logMissingAttribute(IConfigurationElement element, String   attributeName) {
90          logError(element, "Required attribute '" + attributeName + "' not defined");//$NON-NLS-2$//$NON-NLS-1$
91      }
92  
93      /**
94       * Logs a very common registry error when a required child is missing.
95       */
96      protected static void logMissingElement(IConfigurationElement element, String   elementName) {
97          logError(element, "Required sub element '" + elementName + "' not defined");//$NON-NLS-2$//$NON-NLS-1$
98      }
99  
100     /**
101      * Logs a registry error when the configuration element is unknown.
102      */
103     protected static void logUnknownElement(IConfigurationElement element) {
104         logError(element, "Unknown extension tag found: " + element.getName());//$NON-NLS-1$
105     }
106 
107     /**
108      * Apply a reproducable order to the list of extensions provided, such that the order will not
109      * change as extensions are added or removed.
110      */
111     protected IExtension[] orderExtensions(IExtension[] extensions) {
112         // By default, the order is based on plugin id sorted
113         // in ascending order. The order for a plugin providing
114         // more than one extension for an extension point is
115         // dependent in the order listed in the XML file.
116         IExtension[] sortedExtension = new IExtension[extensions.length];
117         System.arraycopy(extensions, 0, sortedExtension, 0, extensions.length);
118         Comparator   comparer = new Comparator  () {
119             public int compare(Object   arg0, Object   arg1) {
120                 String   s1 = ((IExtension) arg0).getNamespaceIdentifier();
121                 String   s2 = ((IExtension) arg1).getNamespaceIdentifier();
122                 return s1.compareToIgnoreCase(s2);
123             }
124         };
125         Collections.sort(Arrays.asList(sortedExtension), comparer);
126         return sortedExtension;
127     }
128 
129     /**
130      * Implement this method to read element's attributes. If children should also be read, then
131      * implementor is responsible for calling <code>readElementChildren</code>. Implementor is
132      * also responsible for logging missing attributes.
133      * 
134      * @return true if element was recognized, false if not.
135      */
136     protected abstract boolean readElement(IConfigurationElement element);
137 
138     /**
139      * Read the element's children. This is called by the subclass' readElement method when it wants
140      * to read the children of the element.
141      */
142     protected void readElementChildren(IConfigurationElement element) {
143         readElements(element.getChildren());
144     }
145 
146     /**
147      * Read each element one at a time by calling the subclass implementation of
148      * <code>readElement</code>.
149      * 
150      * Logs an error if the element was not recognized.
151      */
152     protected void readElements(IConfigurationElement[] elements) {
153         for (int i = 0; i < elements.length; i++) {
154             if (!readElement(elements[i])) {
155                 logUnknownElement(elements[i]);
156             }
157         }
158     }
159 
160     /**
161      * Read one extension by looping through its configuration elements.
162      */
163     protected void readExtension(IExtension extension) {
164         readElements(extension.getConfigurationElements());
165     }
166 
167     /**
168      * Start the registry reading process using the supplied plugin ID and extension point.
169      */
170     public void readRegistry() {
171         if (isInitialized) {
172             return;
173         }
174         synchronized (this) {
175             if (!isInitialized) {
176                 IExtensionPoint point = registry.getExtensionPoint(pluginId, extensionPointId);
177                 if (point == null) {
178                     return;
179                 }
180                 IExtension[] extensions = point.getExtensions();
181                 extensions = orderExtensions(extensions);
182                 for (int i = 0; i < extensions.length; i++) {
183                     readExtension(extensions[i]);
184                 }
185                 isInitialized = true;
186             }
187 
188         }
189     }
190 }
191
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags