public interface IExtensionRegistry
The extension registry can be queried, by name, for extension points and extensions.
The various objects that describe the contents of the extension registry
(IExtensionPoint
, IExtension
, and 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
isValid()
will throw 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 isValid()
, 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 InvalidRegistryObjectException
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.
Extensions and extension points are declared by generic entities called namespaces. 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.
This interface can be used without OSGi running.
This interface is not intended to be implemented by clients.
Modifier and Type | Method and Description |
---|---|
boolean |
addContribution(InputStream is,
IContributor contributor,
boolean persist,
String name,
ResourceBundle translationBundle,
Object token)
Adds to this extension registry an extension point(s), extension(s), or
a combination of those described by the XML file.
|
void |
addListener(IRegistryEventListener listener)
Adds the given listener for registry change events.
|
void |
addListener(IRegistryEventListener listener,
String extensionPointId)
Adds the given listener for registry change events related to specified
extension point.
|
void |
addRegistryChangeListener(IRegistryChangeListener listener)
Note: for new implementations consider using
addListener(IRegistryEventListener) . |
void |
addRegistryChangeListener(IRegistryChangeListener listener,
String namespace)
Note: for new implementations consider using
addListener(IRegistryEventListener, String) . |
IConfigurationElement[] |
getConfigurationElementsFor(String extensionPointId)
Returns all configuration elements from all extensions configured
into the identified extension point.
|
IConfigurationElement[] |
getConfigurationElementsFor(String namespace,
String extensionPointName)
Returns all configuration elements from all extensions configured
into the identified extension point.
|
IConfigurationElement[] |
getConfigurationElementsFor(String namespace,
String extensionPointName,
String extensionId)
Returns all configuration elements from the identified extension.
|
IExtension |
getExtension(String extensionId)
Returns the specified extension in this extension registry,
or
null if there is no such extension. |
IExtension |
getExtension(String extensionPointId,
String extensionId)
Returns the specified extension in this extension registry,
or
null if there is no such extension. |
IExtension |
getExtension(String namespace,
String extensionPointName,
String extensionId)
Returns the specified extension in this extension registry,
or
null if there is no such extension. |
IExtensionPoint |
getExtensionPoint(String extensionPointId)
Returns the extension point with the given extension point identifier
in this extension registry, or
null if there is no such
extension point. |
IExtensionPoint |
getExtensionPoint(String namespace,
String extensionPointName)
Returns the extension point in this extension registry
with the given namespace and extension point simple identifier,
or
null if there is no such extension point. |
IExtensionPoint[] |
getExtensionPoints()
Returns all extension points known to this extension registry.
|
IExtensionPoint[] |
getExtensionPoints(IContributor contributor)
Returns all extension points supplied by the contributor, or
null
if there are no such extension points. |
IExtensionPoint[] |
getExtensionPoints(String namespace)
Returns all extension points declared in the given namespace.
|
IExtension[] |
getExtensions(IContributor contributor)
Returns all extensions supplied by the contributor, or
null if there
are no such extensions. |
IExtension[] |
getExtensions(String namespace)
Returns all extensions declared in the given namespace.
|
String[] |
getNamespaces()
Returns all namespaces currently used by extensions and extension points in this
registry.
|
boolean |
isMultiLanguage()
Call this method to determine if this extension registry supports multiple languages.
|
boolean |
removeExtension(IExtension extension,
Object token)
Removes the given extension from this registry.
|
boolean |
removeExtensionPoint(IExtensionPoint extensionPoint,
Object token)
Removes the specified extension point from this registry.
|
void |
removeListener(IRegistryEventListener listener)
Removes the given registry change listener from this registry.
|
void |
removeRegistryChangeListener(IRegistryChangeListener listener)
Removes the given registry change listener from this registry.
|
void |
stop(Object token)
Call this method to properly stop the registry.
|
void addRegistryChangeListener(IRegistryChangeListener listener, String namespace)
addListener(IRegistryEventListener, String)
.
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.
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.
listener
- the listenernamespace
- the namespace in which to listen for changesIRegistryChangeListener
,
IRegistryChangeEvent
,
removeRegistryChangeListener(IRegistryChangeListener)
void addRegistryChangeListener(IRegistryChangeListener listener)
addListener(IRegistryEventListener)
.
Adds the given listener for registry change events. Has no effect if an identical listener is already registered.
This method is equivalent to:
addRegistryChangeListener(listener,null);
listener
- the listenerIRegistryChangeListener
,
IRegistryChangeEvent
,
addRegistryChangeListener(IRegistryChangeListener, String)
,
removeRegistryChangeListener(IRegistryChangeListener)
IConfigurationElement[] getConfigurationElementsFor(String extensionPointId)
extensionPointId
- the unique identifier of the extension point
(e.g. "org.eclipse.core.resources.builders"
)IConfigurationElement[] getConfigurationElementsFor(String namespace, String extensionPointName)
namespace
- the namespace for the extension point
(e.g. "org.eclipse.core.resources"
)extensionPointName
- the simple identifier of the
extension point (e.g. "builders"
)IConfigurationElement[] getConfigurationElementsFor(String namespace, String extensionPointName, String extensionId)
namespace
- the namespace for the extension point
(e.g. "org.eclipse.core.resources"
)extensionPointName
- the simple identifier of the
extension point (e.g. "builders"
)extensionId
- the unique identifier of the extension
(e.g. "com.example.acme.coolbuilder"
)IExtension getExtension(String extensionId)
null
if there is no such extension.extensionId
- the unique identifier of the extension
(e.g. "com.example.acme.coolbuilder"
)null
IExtension getExtension(String extensionPointId, String extensionId)
null
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.extensionPointId
- the unique identifier of the extension point
(e.g. "org.eclipse.core.resources.builders"
)extensionId
- the unique identifier of the extension
(e.g. "com.example.acme.coolbuilder"
)null
IExtension getExtension(String namespace, String extensionPointName, String extensionId)
null
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.namespace
- the namespace for the extension point
(e.g. "org.eclipse.core.resources"
)extensionPointName
- the simple identifier of the
extension point (e.g. "builders"
)extensionId
- the unique identifier of the extension
(e.g. "com.example.acme.coolbuilder"
)null
IExtensionPoint getExtensionPoint(String extensionPointId)
null
if there is no such
extension point.extensionPointId
- the unique identifier of the extension point
(e.g., "org.eclipse.core.resources.builders"
)null
IExtensionPoint getExtensionPoint(String namespace, String extensionPointName)
null
if there is no such extension point.namespace
- the namespace for the given extension point
(e.g. "org.eclipse.core.resources"
)extensionPointName
- the simple identifier of the
extension point (e.g. "builders"
)null
IExtensionPoint[] getExtensionPoints()
IExtensionPoint[] getExtensionPoints(String namespace)
namespace
- the namespace for the extension points
(e.g. "org.eclipse.core.resources"
)IExtensionPoint[] getExtensionPoints(IContributor contributor)
null
if there are no such extension points.contributor
- the contributor for the extensions (for OSGi registry, bundles and
fragments are different contributors)null
IExtension[] getExtensions(String namespace)
namespace
- the namespace for the extensions
(e.g. "org.eclipse.core.resources"
)IExtension[] getExtensions(IContributor contributor)
null
if there
are no such extensions.contributor
- the contributor for the extensions (for OSGi registry, bundles and
fragments are different contributors)null
String[] getNamespaces()
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.
void removeRegistryChangeListener(IRegistryChangeListener listener)
listener
- the listenerIRegistryChangeListener
,
addRegistryChangeListener(IRegistryChangeListener)
,
addRegistryChangeListener(IRegistryChangeListener, String)
boolean addContribution(InputStream is, IContributor contributor, boolean persist, String name, ResourceBundle translationBundle, Object token) throws IllegalArgumentException
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
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.
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 returningcontributor
- the contributor making this contribution.persist
- indicates if the contribution(s) should be stored in the registry cache. If false
,
contribution is not persisted in the registry cache and is lost on Eclipse restartname
- optional name of the contribution. Used for error reporting; might be null
translationBundle
- optional resource bundle used for translations; might be null
token
- the key used to check permissionstrue
if the contribution was successfully processed and false
otherwiseIllegalArgumentException
- if an incorrect token is passedIContributor
boolean removeExtension(IExtension extension, Object token) throws IllegalArgumentException
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
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.
extension
- extension to be removedtoken
- the key used to check permissionstrue
if the extension was successfully removed, and false
otherwiseIllegalArgumentException
- if an incorrect token is passedboolean removeExtensionPoint(IExtensionPoint extensionPoint, Object token) throws IllegalArgumentException
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
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.
extensionPoint
- extension point to be removedtoken
- the key used to check permissionstrue
if the extension point was successfully removed, and
false
otherwiseIllegalArgumentException
- if incorrect token is passedvoid stop(Object token) throws IllegalArgumentException
This method is an access controlled method. Master token should be passed as an argument.
token
- master token for the registryIllegalArgumentException
- if incorrect token is passedRegistryFactory.createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)
void addListener(IRegistryEventListener listener)
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.
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.
This method has no effect if the listener is already registered.
listener
- the listenervoid addListener(IRegistryEventListener listener, String extensionPointId)
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.
This method has no effect if the listener is already registered.
listener
- the listenerextensionPointId
- the unique identifier of extension pointIExtensionPoint.getUniqueIdentifier()
void removeListener(IRegistryEventListener listener)
This method has no effect if the listener is not registered.
listener
- the listeneraddListener(IRegistryEventListener)
,
addListener(IRegistryEventListener, String)
boolean isMultiLanguage()
See the runtime option "-registryMultiLanguage" for enabling multi-language support.
true
if multiple languages are supported by this
instance of the extension registry; false
otherwise.
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.