IExtensionRegistry


1   /*******************************************************************************
2    * Copyright (c) 2003, 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.core.runtime;
12  
13  import java.io.InputStream  ;
14  import java.util.ResourceBundle  ;
15  
16  /**
17   * The extension registry holds the master list of all
18   * discovered namespaces, extension points and extensions. 
19   * <p>
20   * The extension registry can be queried, by name, for 
21   * extension points and extensions.  
22   * </p>
23   * <p>
24   * The various objects that describe the contents of the extension registry
25   * ({@link IExtensionPoint}, {@link IExtension}, and {@link IConfigurationElement})
26   * are intended for relatively short-term use. Clients that deal with these objects
27   * must be aware that they may become invalid if the declaring plug-in is updated
28   * or uninstalled. If this happens, all methods on these object except
29   * <code>isValid()</code> will throw {@link org.eclipse.core.runtime.InvalidRegistryObjectException}.
30   * Code in a plug-in that has declared that it is not dynamic aware (or not declared
31   * anything) can safely ignore this issue, since the registry would not be
32   * modified while it is active. However, code in a plug-in that declares that it
33   * is dynamic aware must be careful if it accesses extension registry objects,
34   * because it's at risk if plug-in are removed. Similarly, tools that analyze
35   * or display the extension registry are vulnerable. Client code can pre-test for
36   * invalid objects by calling <code>isValid()</code>, which never throws this exception.
37   * However, pre-tests are usually not sufficient because of the possibility of the
38   * extension registry object becoming invalid as a result of a concurrent activity.
39   * At-risk clients must treat <code>InvalidRegistryObjectException</code> as if it
40   * were a checked exception. Also, such clients should probably register a listener
41   * with the extension registry so that they receive notification of any changes to
42   * the registry.
43   * </p>
44   * <p>
45   * Extensions and extension points are declared by generic entities called 
46   * <cite>namespaces</cite>. The only fact known about namespaces is that they 
47   * have unique string-based identifiers. One example of a namespace 
48   * is a plug-in, for which the namespace id is the plug-in id.
49   * </p><p>
50   * This interface can be used without OSGi running.
51   * </p><p>
52   * This interface is not intended to be implemented by clients.
53   * </p>
54   * @since 3.0
55   */
56  public interface IExtensionRegistry {
57      /**
58       * Adds the given listener for registry change events related to extension points 
59       * in the given namespace.
60       * Has no effect if an identical listener is already registered. After 
61       * completion of this method, the given listener will be registered for events 
62       * related to extension points in the specified namespace. If no namespace 
63       * is specified, the listener will receive notifications for changes to 
64       * extension points in any namespace.  
65       * <p>
66       * Once registered, a listener starts receiving notification of changes to
67       *  the registry. Registry change notifications are sent asynchronously.
68       * The listener continues to receive notifications until it is removed. 
69       * </p>
70       * @param listener the listener
71       * @param namespace the namespace in which to listen for changes
72       * @see IRegistryChangeListener
73       * @see IRegistryChangeEvent
74       * @see #removeRegistryChangeListener(IRegistryChangeListener) 
75       */
76      public void addRegistryChangeListener(IRegistryChangeListener listener, String   namespace);
77  
78      /**
79       * Adds the given listener for registry change events.
80       * Has no effect if an identical listener is already registered.
81       * 
82       * <p>
83       * This method is equivalent to:
84       * <pre>
85       *     addRegistryChangeListener(listener,null);
86       * </pre>
87       * </p>
88       * 
89       * @param listener the listener
90       * @see IRegistryChangeListener
91       * @see IRegistryChangeEvent
92       * @see #addRegistryChangeListener(IRegistryChangeListener, String)
93       * @see #removeRegistryChangeListener(IRegistryChangeListener)
94       */
95      public void addRegistryChangeListener(IRegistryChangeListener listener);
96  
97      /**
98       * Returns all configuration elements from all extensions configured
99       * into the identified extension point. Returns an empty array if the extension 
100      * point does not exist, has no extensions configured, or none of the extensions 
101      * contain configuration elements.
102      *
103      * @param extensionPointId the unique identifier of the extension point
104      *      (e.g. <code>"org.eclipse.core.resources.builders"</code>)
105      * @return the configuration elements
106      */
107     public IConfigurationElement[] getConfigurationElementsFor(String   extensionPointId);
108 
109     /**
110      * Returns all configuration elements from all extensions configured
111      * into the identified extension point. Returns an empty array if the extension 
112      * point does not exist, has no extensions configured, or none of the extensions 
113      * contain configuration elements.
114      *
115      * @param namespace the namespace for the extension point 
116      *      (e.g. <code>"org.eclipse.core.resources"</code>)
117      * @param extensionPointName the simple identifier of the 
118      *      extension point (e.g. <code>"builders"</code>)
119      * @return the configuration elements
120      */
121     public IConfigurationElement[] getConfigurationElementsFor(String   namespace, String   extensionPointName);
122 
123     /**
124      * Returns all configuration elements from the identified extension.
125      * Returns an empty array if the extension does not exist or 
126      * contains no configuration elements.
127      *
128      * @param namespace the namespace for the extension point 
129      *      (e.g. <code>"org.eclipse.core.resources"</code>)
130      * @param extensionPointName the simple identifier of the 
131      *      extension point (e.g. <code>"builders"</code>)
132      * @param extensionId the unique identifier of the extension 
133      *      (e.g. <code>"com.example.acme.coolbuilder</code>)
134      * @return the configuration elements
135      */
136     public IConfigurationElement[] getConfigurationElementsFor(String   namespace, String   extensionPointName, String   extensionId);
137 
138     /**
139      * Returns the specified extension in this extension registry, 
140      * or <code>null</code> if there is no such extension.
141      *
142      * @param extensionId the unique identifier of the extension 
143      *      (e.g. <code>"com.example.acme.coolbuilder"</code>)
144      * @return the extension, or <code>null</code>
145      */
146     public IExtension getExtension(String   extensionId);
147 
148     /**
149      * Returns the specified extension in this extension registry, 
150      * or <code>null</code> if there is no such extension.
151      * The first parameter identifies the extension point, and the second
152      * parameter identifies an extension plugged in to that extension point.
153      *
154      * @param extensionPointId the unique identifier of the extension point
155      *      (e.g. <code>"org.eclipse.core.resources.builders"</code>)
156      * @param extensionId the unique identifier of the extension 
157      *      (e.g. <code>"com.example.acme.coolbuilder"</code>)
158      * @return the extension, or <code>null</code>
159      */
160     public IExtension getExtension(String   extensionPointId, String   extensionId);
161 
162     /**
163      * Returns the specified extension in this extension registry, 
164      * or <code>null</code> if there is no such extension.
165      * The first two parameters identify the extension point, and the third
166      * parameter identifies an extension plugged in to that extension point.
167      *
168      * @param namespace the namespace for the extension point 
169      *      (e.g. <code>"org.eclipse.core.resources"</code>)
170      * @param extensionPointName the simple identifier of the 
171      *      extension point (e.g. <code>"builders"</code>)
172      * @param extensionId the unique identifier of the extension 
173      *      (e.g. <code>"com.example.acme.coolbuilder"</code>)
174      * @return the extension, or <code>null</code>
175      */
176     public IExtension getExtension(String   namespace, String   extensionPointName, String   extensionId);
177 
178     /**
179      * Returns the extension point with the given extension point identifier
180      * in this extension registry, or <code>null</code> if there is no such
181      * extension point.
182      *
183      * @param extensionPointId the unique identifier of the extension point 
184      *    (e.g., <code>"org.eclipse.core.resources.builders"</code>)
185      * @return the extension point, or <code>null</code>
186      */
187     public IExtensionPoint getExtensionPoint(String   extensionPointId);
188 
189     /**
190      * Returns the extension point in this extension registry
191      * with the given namespace and extension point simple identifier,
192      * or <code>null</code> if there is no such extension point.
193      *
194      * @param namespace the namespace for the given extension point 
195      *      (e.g. <code>"org.eclipse.core.resources"</code>)
196      * @param extensionPointName the simple identifier of the 
197      *      extension point (e.g. <code>"builders"</code>)
198      * @return the extension point, or <code>null</code>
199      */
200     public IExtensionPoint getExtensionPoint(String   namespace, String   extensionPointName);
201 
202     /**
203      * Returns all extension points known to this extension registry.
204      * Returns an empty array if there are no extension points.
205      *
206      * @return the extension points known to this extension registry
207      */
208     public IExtensionPoint[] getExtensionPoints();
209 
210     /**
211      * Returns all extension points declared in the given namespace. Returns an empty array if 
212      * there are no extension points declared in the namespace.
213      * 
214      * @param namespace the namespace for the extension points 
215      *      (e.g. <code>"org.eclipse.core.resources"</code>) 
216      * @return the extension points in this registry declared in the given namespace 
217      */
218     public IExtensionPoint[] getExtensionPoints(String   namespace);
219 
220     /**
221      * Returns all extensions declared in the given namespace. Returns an empty array if 
222      * no extensions are declared in the namespace.
223      * 
224      * @param namespace the namespace for the extensions 
225      *      (e.g. <code>"org.eclipse.core.resources"</code>)
226      * @return the extensions in this registry declared in the given namespace 
227      */
228     public IExtension[] getExtensions(String   namespace);
229 
230     /**
231      * Returns all namespaces currently used by extensions and extension points in this 
232      * registry. Returns an empty array if there are no known extensions/extension points
233      * in this registry.
234      * <p>
235      * The fully-qualified name of an extension point or an extension consist of 
236      * a namespace and a simple name (much like a qualified Java class name consist
237      * of a package name and a class name). The simple names are presumed to be unique
238      * in the namespace.
239      * </p> 
240      * @return all namespaces known to this registry
241      */
242     public String  [] getNamespaces();
243 
244     /** 
245      * Removes the given registry change listener from this registry.
246      * Has no effect if an identical listener is not registered.
247      *
248      * @param listener the listener
249      * @see IRegistryChangeListener
250      * @see #addRegistryChangeListener(IRegistryChangeListener)
251      * @see #addRegistryChangeListener(IRegistryChangeListener, String)
252      */
253     public void removeRegistryChangeListener(IRegistryChangeListener listener);
254 
255     /**
256      * Adds to this extension registry an extension point(s), extension(s), or 
257      * a combination of those described by the XML file. The information in 
258      * the XML file should be supplied in the same format as the plugin.xml; in fact,
259      * Plug-in Manifest editor can be used to prepare the XML file. The top token
260      * of the contribution (normally, "plugin" or "fragment" in the Plug-in Manifest 
261      * editor) is ignored by this method. 
262      * <p>
263      * This method is an access controlled method. Proper token (master token or user token) should 
264      * be passed as an argument. Two registry keys are set in the registry constructor 
265      * {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}: 
266      * master token and a user token. Master token allows all operations; user token allows 
267      * non-persisted registry elements to be modified.
268      * </p><p>
269      * <b>Note:</b> This class/interface is part of an interim API that is still under 
270      * development and expected to change significantly before reaching stability. 
271      * It is being made available at this early stage to solicit feedback from pioneering 
272      * adopters on the understanding that any code that uses this API will almost certainly 
273      * be broken (repeatedly) as the API evolves.
274      * </p>
275      * @param is stream open on the XML file. The XML file can contain an extension 
276      * point(s) or/and extension(s) described in the format similar to plugin.xml. The method
277      * closes  the stream before returning
278      * @param contributor the contributor making this contribution.
279      * @param persist indicates if the contribution(s) should be stored in the registry cache. If <code>false</code>,
280      *  contribution is not persisted in the registry cache and is lost on Eclipse restart
281      * @param name optional name of the contribution. Used for error reporting; might be <code>null</code>
282      * @param translationBundle optional resource bundle used for translations; might be <code>null</code>
283      * @param token the key used to check permissions
284      * @return <code>true</code> if the contribution was successfully processed and <code>false</code>
285      *  otherwise
286      * @throws IllegalArgumentException if an incorrect token is passed
287      * 
288      * @see IContributor
289      * @since org.eclipse.equinox.registry 3.2   
290      */
291     public boolean addContribution(InputStream   is, IContributor contributor, boolean persist, String   name, ResourceBundle   translationBundle, Object   token) throws IllegalArgumentException  ;
292 
293     /**
294      * Removes the given extension from this registry.
295      * <p>
296      * This method is an access controlled method. Proper token (master token or user token) should 
297      * be passed as an argument. Two registry keys are set in the registry constructor 
298      * {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}: 
299      * master token and a user token. Master token allows all operations; user token only
300      * allows non-persisted registry elements to be modified.
301      * </p><p>
302      * <b>Note:</b> This class/interface is part of an interim API that is still under 
303      * development and expected to change significantly before reaching stability. 
304      * It is being made available at this early stage to solicit feedback from pioneering 
305      * adopters on the understanding that any code that uses this API will almost certainly 
306      * be broken (repeatedly) as the API evolves.
307      * </p>
308      * @param extension extension to be removed
309      * @param token the key used to check permissions
310      * @return <code>true</code> if the extension was successfully removed, and <code>false</code> otherwise
311      * @throws IllegalArgumentException if an incorrect token is passed
312      * 
313      * @since org.eclipse.equinox.registry 3.2   
314      */
315     public boolean removeExtension(IExtension extension, Object   token) throws IllegalArgumentException  ;
316 
317     /**
318      * Removes the specified extension point from this registry.
319      * <p>
320      * This method is an access controlled method. Proper token (master token or user token) should 
321      * be passed as an argument. Two registry keys are set in the registry constructor 
322      * {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}: 
323      * master token and a user token. Master token allows all operations; user token only
324      * allows non-persisted registry elements to be modified.
325      * </p><p>
326      * <b>Note:</b> This class/interface is part of an interim API that is still under 
327      * development and expected to change significantly before reaching stability. 
328      * It is being made available at this early stage to solicit feedback from pioneering 
329      * adopters on the understanding that any code that uses this API will almost certainly 
330      * be broken (repeatedly) as the API evolves.
331      * </p>
332      * @param extensionPoint extension point to be removed
333      * @param token the key used to check permissions
334      * @return <code>true</code> if the extension point was successfully removed, and 
335      *  <code>false</code> otherwise
336      * @throws IllegalArgumentException if incorrect token is passed
337      * 
338      * @since org.eclipse.equinox.registry 3.2   
339      */
340     public boolean removeExtensionPoint(IExtensionPoint extensionPoint, Object   token) throws IllegalArgumentException  ;
341 
342     /**
343      * Call this method to properly stop the registry. The method stops registry event processing
344      * and writes out cache information to be used in the next run. This is an access controlled 
345      * method; master token is required.
346      * <p>
347      * This method is an access controlled method. Master token should be passed as an argument.
348      * </p>
349      * @see RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)
350      * @param token master token for the registry
351      * @throws IllegalArgumentException if incorrect token is passed
352      * 
353      * @since org.eclipse.equinox.registry 3.2
354      */
355     public void stop(Object   token) throws IllegalArgumentException  ;
356 }
357
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags