Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 


Eclipse Platform
Release 3.5

org.eclipse.core.runtime
Interface IExtensionRegistry


public interface IExtensionRegistry

The extension registry holds the master list of all discovered namespaces, extension points and extensions.

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.

Since:
3.0
Restriction:
This interface is not intended to be implemented by clients.

Method Summary
 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 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.
 

Method Detail

addRegistryChangeListener

void addRegistryChangeListener(
IRegistryChangeListener listener,
                               
String namespace)
Note: for new implementations consider using 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.

Parameters:
listener - the listener
namespace - the namespace in which to listen for changes
See Also:
IRegistryChangeListener, IRegistryChangeEvent, removeRegistryChangeListener(IRegistryChangeListener)

addRegistryChangeListener

void addRegistryChangeListener(
IRegistryChangeListener listener)
Note: for new implementations consider using 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);
 

Parameters:
listener - the listener
See Also:
IRegistryChangeListener, IRegistryChangeEvent, addRegistryChangeListener(IRegistryChangeListener, String), removeRegistryChangeListener(IRegistryChangeListener)

getConfigurationElementsFor

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.

Parameters:
extensionPointId - the unique identifier of the extension point (e.g. "org.eclipse.core.resources.builders")
Returns:
the configuration elements

getConfigurationElementsFor

IConfigurationElement[] getConfigurationElementsFor(
String namespace,
                                                    
String extensionPointName)
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.

Parameters:
namespace - the namespace for the extension point (e.g. "org.eclipse.core.resources")
extensionPointName - the simple identifier of the extension point (e.g. "builders")
Returns:
the configuration elements

getConfigurationElementsFor

IConfigurationElement[] getConfigurationElementsFor(
String namespace,
                                                    
String extensionPointName,
                                                    
String extensionId)
Returns all configuration elements from the identified extension. Returns an empty array if the extension does not exist or contains no configuration elements.

Parameters:
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")
Returns:
the configuration elements

getExtension

IExtension getExtension(
String extensionId)
Returns the specified extension in this extension registry, or null if there is no such extension.

Parameters:
extensionId - the unique identifier of the extension (e.g. "com.example.acme.coolbuilder")
Returns:
the extension, or null

getExtension

IExtension getExtension(
String extensionPointId,
                        
String extensionId)
Returns the specified extension in this extension registry, or 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.

Parameters:
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")
Returns:
the extension, or null

getExtension

IExtension getExtension(
String namespace,
                        
String extensionPointName,
                        
String extensionId)
Returns the specified extension in this extension registry, or 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.

Parameters:
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")
Returns:
the extension, or null

getExtensionPoint

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.

Parameters:
extensionPointId - the unique identifier of the extension point (e.g., "org.eclipse.core.resources.builders")
Returns:
the extension point, or null

getExtensionPoint

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.

Parameters:
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")
Returns:
the extension point, or null

getExtensionPoints

IExtensionPoint[] getExtensionPoints()
Returns all extension points known to this extension registry. Returns an empty array if there are no extension points.

Returns:
the extension points known to this extension registry

getExtensionPoints

IExtensionPoint[] getExtensionPoints(
String namespace)
Returns all extension points declared in the given namespace. Returns an empty array if there are no extension points declared in the namespace.

Parameters:
namespace - the namespace for the extension points (e.g. "org.eclipse.core.resources")
Returns:
the extension points in this registry declared in the given namespace

getExtensionPoints

IExtensionPoint[] getExtensionPoints(
IContributor contributor)
Returns all extension points supplied by the contributor, or null if there are no such extension points.

Parameters:
contributor - the contributor for the extensions (for OSGi registry, bundles and fragments are different contributors)
Returns:
the extension points, or null
Since:
3.4

getExtensions

IExtension[] getExtensions(
String namespace)
Returns all extensions declared in the given namespace. Returns an empty array if no extensions are declared in the namespace.

Parameters:
namespace - the namespace for the extensions (e.g. "org.eclipse.core.resources")
Returns:
the extensions in this registry declared in the given namespace

getExtensions

IExtension[] getExtensions(
IContributor contributor)
Returns all extensions supplied by the contributor, or null if there are no such extensions.

Parameters:
contributor - the contributor for the extensions (for OSGi registry, bundles and fragments are different contributors)
Returns:
the extensions, or null
Since:
3.4

getNamespaces

String[] getNamespaces()
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.

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.

Returns:
all namespaces known to this registry

removeRegistryChangeListener

void removeRegistryChangeListener(
IRegistryChangeListener listener)
Removes the given registry change listener from this registry. Has no effect if an identical listener is not registered.

Parameters:
listener - the listener
See Also:
IRegistryChangeListener, addRegistryChangeListener(IRegistryChangeListener), addRegistryChangeListener(IRegistryChangeListener, String)

addContribution

boolean addContribution(
InputStream is,
                        
IContributor contributor,
                        boolean persist,
                        
String name,
                        
ResourceBundle translationBundle,
                        
Object token)
                        throws 
IllegalArgumentException
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.

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.

Note: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.

Parameters:
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
contributor - 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 restart
name - 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 permissions
Returns:
true if the contribution was successfully processed and false otherwise
Throws:
IllegalArgumentException - if an incorrect token is passed
Since:
org.eclipse.equinox.registry 3.2
See Also:
IContributor

removeExtension

boolean removeExtension(
IExtension extension,
                        
Object token)
                        throws 
IllegalArgumentException
Removes the given extension from this registry.

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.

Note: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.

Parameters:
extension - extension to be removed
token - the key used to check permissions
Returns:
true if the extension was successfully removed, and false otherwise
Throws:
IllegalArgumentException - if an incorrect token is passed
Since:
org.eclipse.equinox.registry 3.2

removeExtensionPoint

boolean removeExtensionPoint(
IExtensionPoint extensionPoint,
                             
Object token)
                             throws 
IllegalArgumentException
Removes the specified extension point from this registry.

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.

Note: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.

Parameters:
extensionPoint - extension point to be removed
token - the key used to check permissions
Returns:
true if the extension point was successfully removed, and false otherwise
Throws:
IllegalArgumentException - if incorrect token is passed
Since:
org.eclipse.equinox.registry 3.2

stop

void stop(
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.

This method is an access controlled method. Master token should be passed as an argument.

Parameters:
token - master token for the registry
Throws:
IllegalArgumentException - if incorrect token is passed
Since:
org.eclipse.equinox.registry 3.2
See Also:
RegistryFactory.createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)

addListener

void addListener(
IRegistryEventListener listener)
Adds the given listener for registry change events. Listener will be notified on changes to all extension points and underlying extensions.

Depending on activity, listners 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.

Parameters:
listener - the listener
Since:
3.4

addListener

void addListener(
IRegistryEventListener listener,
                 
String extensionPointId)
Adds the given listener for registry change events related to specified extension point.

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.

Parameters:
listener - the listener
extensionPointId - the unique identifier of extension point
Since:
3.4
See Also:
IExtensionPoint.getUniqueIdentifier()

removeListener

void removeListener(
IRegistryEventListener listener)
Removes the given registry change listener from this registry.

This method has no effect if the listener is not registered.

Parameters:
listener - the listener
Since:
3.4
See Also:
addListener(IRegistryEventListener), addListener(IRegistryEventListener, String)

Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire