Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: 5ec344b135a9983d810041b53770bafd3696a2f0 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
/*******************************************************************************
 * Copyright (c) 2003, 2014 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.runtime;

import java.io.InputStream;
import java.util.ResourceBundle;

/**
 * The extension registry holds the master list of all
 * discovered namespaces, extension points and extensions.
 * <p>
 * The extension registry can be queried, by name, for
 * extension points and extensions.
 * </p>
 * <p>
 * The various objects that describe the contents of the extension registry
 * ({@link IExtensionPoint}, {@link IExtension}, and {@link IConfigurationElement})
 * are intended for relatively short-term use. Clients that deal with these objects
 * must be aware that they may become invalid if the declaring plug-in is updated
 * or uninstalled. If this happens, all methods on these object except
 * <code>isValid()</code> will throw {@link org.eclipse.core.runtime.InvalidRegistryObjectException}.
 * Code in a plug-in that has declared that it is not dynamic aware (or not declared
 * anything) can safely ignore this issue, since the registry would not be
 * modified while it is active. However, code in a plug-in that declares that it
 * is dynamic aware must be careful if it accesses extension registry objects,
 * because it's at risk if plug-in are removed. Similarly, tools that analyze
 * or display the extension registry are vulnerable. Client code can pre-test for
 * invalid objects by calling <code>isValid()</code>, which never throws this exception.
 * However, pre-tests are usually not sufficient because of the possibility of the
 * extension registry object becoming invalid as a result of a concurrent activity.
 * At-risk clients must treat <code>InvalidRegistryObjectException</code> as if it
 * were a checked exception. Also, such clients should probably register a listener
 * with the extension registry so that they receive notification of any changes to
 * the registry.
 * </p>
 * <p>
 * Extensions and extension points are declared by generic entities called
 * <cite>namespaces</cite>. The only fact known about namespaces is that they
 * have unique string-based identifiers. One example of a namespace
 * is a plug-in, for which the namespace id is the plug-in id.
 * </p><p>
 * This interface can be used without OSGi running.
 * </p><p>
 * This interface is not intended to be implemented by clients.
 * </p>
 * @since 3.0
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IExtensionRegistry {
	/**
	 * <b>Note:</b> for new implementations consider using {@link #addListener(IRegistryEventListener, String)}.
	 * <p>
	 * Adds the given listener for registry change events related to extension points
	 * in the given namespace.
	 * Has no effect if an identical listener is already registered. After
	 * completion of this method, the given listener will be registered for events
	 * related to extension points in the specified namespace. If no namespace
	 * is specified, the listener will receive notifications for changes to
	 * extension points in any namespace.
	 * </p><p>
	 * Once registered, a listener starts receiving notification of changes to
	 *  the registry. Registry change notifications are sent asynchronously.
	 * The listener continues to receive notifications until it is removed.
	 * </p>
	 * @param listener the listener
	 * @param namespace the namespace in which to listen for changes
	 * @see IRegistryChangeListener
	 * @see IRegistryChangeEvent
	 * @see #removeRegistryChangeListener(IRegistryChangeListener)
	 */
	public void addRegistryChangeListener(IRegistryChangeListener listener, String namespace);

	/**
	 * <b>Note:</b> for new implementations consider using {@link #addListener(IRegistryEventListener)}.
	 * <p>
	 * Adds the given listener for registry change events.
	 * Has no effect if an identical listener is already registered.
	 *
	 * </p><p>
	 * This method is equivalent to:
	 * </p>
	 * <pre>
	 *     addRegistryChangeListener(listener,null);
	 * </pre>
	 *
	 * @param listener the listener
	 * @see IRegistryChangeListener
	 * @see IRegistryChangeEvent
	 * @see #addRegistryChangeListener(IRegistryChangeListener, String)
	 * @see #removeRegistryChangeListener(IRegistryChangeListener)
	 */
	public void addRegistryChangeListener(IRegistryChangeListener listener);

	/**
	 * Returns all configuration elements from all extensions configured
	 * into the identified extension point. Returns an empty array if the extension
	 * point does not exist, has no extensions configured, or none of the extensions
	 * contain configuration elements.
	 *
	 * @param extensionPointId the unique identifier of the extension point
	 *		(e.g. <code>"org.eclipse.core.resources.builders"</code>)
	 * @return the configuration elements
	 */
	public IConfigurationElement[] getConfigurationElementsFor(String extensionPointId);

	/**
	 * Returns all configuration elements from all extensions configured
	 * into the identified extension point. Returns an empty array if the extension
	 * point does not exist, has no extensions configured, or none of the extensions
	 * contain configuration elements.
	 *
	 * @param namespace the namespace for the extension point
	 *		(e.g. <code>"org.eclipse.core.resources"</code>)
	 * @param extensionPointName the simple identifier of the
	 *		extension point (e.g. <code>"builders"</code>)
	 * @return the configuration elements
	 */
	public IConfigurationElement[] getConfigurationElementsFor(String namespace, String extensionPointName);

	/**
	 * Returns all configuration elements from the identified extension.
	 * Returns an empty array if the extension does not exist or
	 * contains no configuration elements.
	 *
	 * @param namespace the namespace for the extension point
	 *		(e.g. <code>"org.eclipse.core.resources"</code>)
	 * @param extensionPointName the simple identifier of the
	 *		extension point (e.g. <code>"builders"</code>)
	 * @param extensionId the unique identifier of the extension
	 *		(e.g. <code>"com.example.acme.coolbuilder"</code>)
	 * @return the configuration elements
	 */
	public IConfigurationElement[] getConfigurationElementsFor(String namespace, String extensionPointName, String extensionId);

	/**
	 * Returns the specified extension in this extension registry,
	 * or <code>null</code> if there is no such extension.
	 *
	 * @param extensionId the unique identifier of the extension
	 *		(e.g. <code>"com.example.acme.coolbuilder"</code>)
	 * @return the extension, or <code>null</code>
	 */
	public IExtension getExtension(String extensionId);

	/**
	 * Returns the specified extension in this extension registry,
	 * or <code>null</code> if there is no such extension.
	 * The first parameter identifies the extension point, and the second
	 * parameter identifies an extension plugged in to that extension point.
	 *
	 * @param extensionPointId the unique identifier of the extension point
	 *		(e.g. <code>"org.eclipse.core.resources.builders"</code>)
	 * @param extensionId the unique identifier of the extension
	 *		(e.g. <code>"com.example.acme.coolbuilder"</code>)
	 * @return the extension, or <code>null</code>
	 */
	public IExtension getExtension(String extensionPointId, String extensionId);

	/**
	 * Returns the specified extension in this extension registry,
	 * or <code>null</code> if there is no such extension.
	 * The first two parameters identify the extension point, and the third
	 * parameter identifies an extension plugged in to that extension point.
	 *
	 * @param namespace the namespace for the extension point
	 *		(e.g. <code>"org.eclipse.core.resources"</code>)
	 * @param extensionPointName the simple identifier of the
	 *		extension point (e.g. <code>"builders"</code>)
	 * @param extensionId the unique identifier of the extension
	 *		(e.g. <code>"com.example.acme.coolbuilder"</code>)
	 * @return the extension, or <code>null</code>
	 */
	public IExtension getExtension(String namespace, String extensionPointName, String extensionId);

	/**
	 * Returns the extension point with the given extension point identifier
	 * in this extension registry, or <code>null</code> if there is no such
	 * extension point.
	 *
	 * @param extensionPointId the unique identifier of the extension point
	 *    (e.g., <code>"org.eclipse.core.resources.builders"</code>)
	 * @return the extension point, or <code>null</code>
	 */
	public IExtensionPoint getExtensionPoint(String extensionPointId);

	/**
	 * Returns the extension point in this extension registry
	 * with the given namespace and extension point simple identifier,
	 * or <code>null</code> if there is no such extension point.
	 *
	 * @param namespace the namespace for the given extension point
	 *		(e.g. <code>"org.eclipse.core.resources"</code>)
	 * @param extensionPointName the simple identifier of the
	 *		extension point (e.g. <code>"builders"</code>)
	 * @return the extension point, or <code>null</code>
	 */
	public IExtensionPoint getExtensionPoint(String namespace, String extensionPointName);

	/**
	 * Returns all extension points known to this extension registry.
	 * Returns an empty array if there are no extension points.
	 *
	 * @return the extension points known to this extension registry
	 */
	public IExtensionPoint[] getExtensionPoints();

	/**
	 * Returns all extension points declared in the given namespace. Returns an empty array if
	 * there are no extension points declared in the namespace.
	 *
	 * @param namespace the namespace for the extension points
	 *		(e.g. <code>"org.eclipse.core.resources"</code>)
	 * @return the extension points in this registry declared in the given namespace
	 */
	public IExtensionPoint[] getExtensionPoints(String namespace);

	/**
	 * Returns all extension points supplied by the contributor, or <code>null</code>
	 * if there are no such extension points.
	 *
	 * @param contributor the contributor for the extensions (for OSGi registry, bundles and
	 * fragments are different contributors)
	 * @return the extension points, or <code>null</code>
	 * @since 3.4
	 */
	public IExtensionPoint[] getExtensionPoints(IContributor contributor);

	/**
	 * Returns all extensions declared in the given namespace. Returns an empty array if
	 * no extensions are declared in the namespace.
	 *
	 * @param namespace the namespace for the extensions
	 *		(e.g. <code>"org.eclipse.core.resources"</code>)
	 * @return the extensions in this registry declared in the given namespace
	 */
	public IExtension[] getExtensions(String namespace);

	/**
	 * Returns all extensions supplied by the contributor, or <code>null</code> if there
	 * are no such extensions.
	 * @param contributor the contributor for the extensions (for OSGi registry, bundles and
	 * fragments are different contributors)
	 * @return the extensions, or <code>null</code>
	 * @since 3.4
	 */
	public IExtension[] getExtensions(IContributor contributor);

	/**
	 * Returns all namespaces currently used by extensions and extension points in this
	 * registry. Returns an empty array if there are no known extensions/extension points
	 * in this registry.
	 * <p>
	 * The fully-qualified name of an extension point or an extension consist of
	 * a namespace and a simple name (much like a qualified Java class name consist
	 * of a package name and a class name). The simple names are presumed to be unique
	 * in the namespace.
	 * </p>
	 * @return all namespaces known to this registry
	 */
	public String[] getNamespaces();

	/**
	 * Removes the given registry change listener from this registry.
	 * Has no effect if an identical listener is not registered.
	 *
	 * @param listener the listener
	 * @see IRegistryChangeListener
	 * @see #addRegistryChangeListener(IRegistryChangeListener)
	 * @see #addRegistryChangeListener(IRegistryChangeListener, String)
	 */
	public void removeRegistryChangeListener(IRegistryChangeListener listener);

	/**
	 * Adds to this extension registry an extension point(s), extension(s), or
	 * a combination of those described by the XML file. The information in
	 * the XML file should be supplied in the same format as the plugin.xml; in fact,
	 * Plug-in Manifest editor can be used to prepare the XML file. The top token
	 * of the contribution (normally, "plugin" or "fragment" in the Plug-in Manifest
	 * editor) is ignored by this method.
	 * <p>
	 * This method is an access controlled method. Proper token (master token or user token) should
	 * be passed as an argument. Two registry keys are set in the registry constructor
	 * {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}:
	 * master token and a user token. Master token allows all operations; user token allows
	 * non-persisted registry elements to be modified.
	 * </p>
	 * @param is stream open on the XML file. The XML file can contain an extension
	 * point(s) or/and extension(s) described in the format similar to plugin.xml. The method
	 * closes  the stream before returning
	 * @param contributor the contributor making this contribution.
	 * @param persist indicates if the contribution(s) should be stored in the registry cache. If <code>false</code>,
	 * 	contribution is not persisted in the registry cache and is lost on Eclipse restart
	 * @param name optional name of the contribution. Used for error reporting; might be <code>null</code>
	 * @param translationBundle optional resource bundle used for translations; might be <code>null</code>
	 * @param token the key used to check permissions
	 * @return <code>true</code> if the contribution was successfully processed and <code>false</code>
	 * 	otherwise
	 * @throws IllegalArgumentException if an incorrect token is passed
	 *
	 * @see IContributor
	 * @since org.eclipse.equinox.registry 3.2
	 */
	public boolean addContribution(InputStream is, IContributor contributor, boolean persist, String name, ResourceBundle translationBundle, Object token) throws IllegalArgumentException;

	/**
	 * Removes the given extension from this registry.
	 * <p>
	 * This method is an access controlled method. Proper token (master token or user token) should
	 * be passed as an argument. Two registry keys are set in the registry constructor
	 * {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}:
	 * master token and a user token. Master token allows all operations; user token only
	 * allows non-persisted registry elements to be modified.
	 * </p>
	 * @param extension extension to be removed
	 * @param token the key used to check permissions
	 * @return <code>true</code> if the extension was successfully removed, and <code>false</code> otherwise
	 * @throws IllegalArgumentException if an incorrect token is passed
	 *
	 * @since org.eclipse.equinox.registry 3.2
	 */
	public boolean removeExtension(IExtension extension, Object token) throws IllegalArgumentException;

	/**
	 * Removes the specified extension point from this registry.
	 * <p>
	 * This method is an access controlled method. Proper token (master token or user token) should
	 * be passed as an argument. Two registry keys are set in the registry constructor
	 * {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}:
	 * master token and a user token. Master token allows all operations; user token only
	 * allows non-persisted registry elements to be modified.
	 * </p>
	 * @param extensionPoint extension point to be removed
	 * @param token the key used to check permissions
	 * @return <code>true</code> if the extension point was successfully removed, and
	 * 	<code>false</code> otherwise
	 * @throws IllegalArgumentException if incorrect token is passed
	 *
	 * @since org.eclipse.equinox.registry 3.2
	 */
	public boolean removeExtensionPoint(IExtensionPoint extensionPoint, Object token) throws IllegalArgumentException;

	/**
	 * Call this method to properly stop the registry. The method stops registry event processing
	 * and writes out cache information to be used in the next run. This is an access controlled
	 * method; master token is required.
	 * <p>
	 * This method is an access controlled method. Master token should be passed as an argument.
	 * </p>
	 * @see RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)
	 * @param token master token for the registry
	 * @throws IllegalArgumentException if incorrect token is passed
	 *
	 * @since org.eclipse.equinox.registry 3.2
	 */
	public void stop(Object token) throws IllegalArgumentException;

	/**
	 * Adds the given listener for registry change events. Listener will be notified
	 * on changes to all extension points and underlying extensions.
	 * <p>
	 * Depending on activity, listeners of this type might receive a large number
	 * of modifications and negatively impact overall system performance. Whenever
	 * possible, consider registering listener specific to an extension point rather
	 * than a "global" listener.
	 * </p><p>
	 * Once registered, a listener starts receiving notification of changes to
	 * the registry. Registry change notifications are sent asynchronously.
	 * The listener continues to receive notifications until it is removed.
	 * </p><p>
	 * This method has no effect if the listener is already registered.
	 * </p>
	 * @param listener the listener
	 * @since org.eclipse.equinox.registry 3.4
	 */
	public void addListener(IRegistryEventListener listener);

	/**
	 * Adds the given listener for registry change events related to specified
	 * extension point.
	 * <p>
	 * Once registered, a listener starts receiving notification of changes to
	 * the registry. Registry change notifications are sent asynchronously.
	 * The listener continues to receive notifications until it is removed.
	 * </p><p>
	 * This method has no effect if the listener is already registered.
	 * </p>
	 * @param listener the listener
	 * @param extensionPointId the unique identifier of extension point
	 * @see IExtensionPoint#getUniqueIdentifier()
	 * @since org.eclipse.equinox.registry 3.4
	 */
	public void addListener(IRegistryEventListener listener, String extensionPointId);

	/**
	 * Removes the given registry change listener from this registry.
	 * <p>
	 * This method has no effect if the listener is not registered.
	 * </p>
	 * @param listener the listener
	 * @see #addListener(IRegistryEventListener)
	 * @see #addListener(IRegistryEventListener, String)
	 * @since org.eclipse.equinox.registry 3.4
	 */
	public void removeListener(IRegistryEventListener listener);

	/**
	 * Call this method to determine if this extension registry supports multiple languages.
	 * <p>
	 * See the runtime option "-registryMultiLanguage" for enabling multi-language
	 * support.
	 * </p>
	 * @return <code>true</code> if multiple languages are supported by this
	 * instance of the extension registry; <code>false</code> otherwise.
	 * @since org.eclipse.equinox.registry 3.5
	 */
	public boolean isMultiLanguage();
}

Back to the top