Package org.java.plugin
Class PluginManager
java.lang.Object
org.java.plugin.PluginManager
- Direct Known Subclasses:
StandardPluginManager
JPF "runtime" class - the entry point to the framework API. It is expected
that only one instance of this class will be created per application (other
scenarios may be possible but not tested).
Usage example. Somewhere in the beginning of your application:
manager = factory.createManager(); manager.publishPlugins(getLocations(dir));Later on, before accessing plug-in:
manager.activatePlugin(pluginId);
- Version:
- $Id: PluginManager.java,v 1.5 2007/04/07 12:42:14 ddimon Exp $
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Plug-ins life-cycle events callback interface.static class
An abstract adapter class for receiving plug-ins life-cycle events.static interface
Simple callback interface to hold info about plug-in manifest and plug-in data locations. -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract void
activatePlugin
(String id) Activates plug-in with given ID if it is not activated yet.abstract void
Deactivates plug-in with given ID if it has been successfully activated before.abstract PluginDescriptor[]
disablePlugin
(PluginDescriptor descr) Disables plug-in (with dependencies) in this manager instance.protected final void
Forwards call toPluginClassLoader.dispose()
method.abstract PluginDescriptor[]
enablePlugin
(PluginDescriptor descr, boolean includeDependings) Enables plug-in (or plug-ins) in this manager instance.abstract PathResolver
abstract Plugin
Looks for plug-in with given ID and activates it if it is not activated yet.abstract PluginClassLoader
Returns instance of plug-in's class loader and not tries to activate plug-in.abstract Plugin
getPluginFor
(Object obj) Looks for plug-in, given object belongs to.abstract PluginRegistry
protected final void
initPlugin
(Plugin plugin, PluginDescriptor descr) Initializes given plug-in with this manager instance and given descriptor.abstract boolean
isBadPlugin
(PluginDescriptor descr) abstract boolean
abstract boolean
abstract boolean
isPluginEnabled
(PluginDescriptor descr) static PluginManager
Looks for plug-in manager instance for given object.protected final void
Forwards call toPluginClassLoader.pluginsSetChanged()
method.publishPlugins
(PluginManager.PluginLocation[] locations) Registers plug-ins and their locations with this plug-in manager.abstract void
registerListener
(PluginManager.EventListener listener) Registers plug-in manager event listener.abstract void
shutdown()
Shuts down the framework.protected final void
startPlugin
(Plugin plugin) Starts given plug-in.protected final void
stopPlugin
(Plugin plugin) Stops given plug-in.abstract void
Unregisters manager event listener.
-
Field Details
-
VERSION
JPF version number.- See Also:
-
VERSION_PROPERTY
JPF version system property name.- See Also:
-
-
Constructor Details
-
PluginManager
public PluginManager()
-
-
Method Details
-
lookup
Looks for plug-in manager instance for given object.- Parameters:
obj
- any object that may be managed by some plug-in manager- Returns:
- plug-in manager instance or
null
if given object doesn't belong to any plug-in (possibly it is part of "host" application) and thus doesn't managed by the Framework directly or indirectly.
-
getRegistry
- Returns:
- registry, used by this manager
-
getPathResolver
- Returns:
- path resolver
-
publishPlugins
public abstract Map<String,Identity> publishPlugins(PluginManager.PluginLocation[] locations) throws JpfException Registers plug-ins and their locations with this plug-in manager. You should use this method to register new plug-ins to make them available for activation with this manager instance (compare this toPluginRegistry.register(URL[])
method that just makes plug-in's meta-data available for reading and doesn't "know" where are things actually located).Note that this method only load plug-ins to this manager but not activate them. Call
activatePlugin(String)
method to make plug-in activated. It is recommended to do this immediately before first plug-in use.- Parameters:
locations
- plug-in locations data- Returns:
- map where keys are manifest URL's and values are registered plug-ins or plug-in fragments, URL's for unprocessed manifests are not included
- Throws:
JpfException
- if given plug-ins can't be registered or published (optional behavior)- See Also:
-
getPlugin
Looks for plug-in with given ID and activates it if it is not activated yet. Note that this method will never returnnull
.- Parameters:
id
- plug-in ID- Returns:
- found plug-in
- Throws:
PluginLifecycleException
- if plug-in can't be found or activated
-
activatePlugin
Activates plug-in with given ID if it is not activated yet. Actually this makes plug-in "running" and callsPlugin.doStart()
method. This method will effectively activate all depending plug-ins. It is safe to call this method more than once.- Parameters:
id
- plug-in ID- Throws:
PluginLifecycleException
- if plug-in can't be found or activated
-
getPluginFor
Looks for plug-in, given object belongs to.- Parameters:
obj
- any object that maybe belongs to some plug-in- Returns:
- plug-in or
null
if given object doesn't belong to any plug-in (possibly it is part of "host" application) and thus doesn't managed by the Framework directly or indirectly
-
isPluginActivated
- Parameters:
descr
- plug-in descriptor- Returns:
true
if plug-in with given descriptor is activated
-
isBadPlugin
- Parameters:
descr
- plug-in descriptor- Returns:
true
if plug-in disabled as it's activation fails
-
isPluginActivating
- Parameters:
descr
- plug-in descriptor- Returns:
true
if plug-in is currently activating
-
getPluginClassLoader
Returns instance of plug-in's class loader and not tries to activate plug-in. Use this method if you need to get access to plug-in resources and don't want to cause plug-in activation.- Parameters:
descr
- plug-in descriptor- Returns:
- class loader instance for plug-in with given descriptor
-
shutdown
public abstract void shutdown()Shuts down the framework.
Calling this method will deactivate all active plug-ins in order, reverse to the order they was activated. It also releases all resources allocated by this manager (class loaders, plug-in descriptors etc.). All disabled plug-ins will be marked as "enabled", all registered event listeners will be unregistered. -
deactivatePlugin
Deactivates plug-in with given ID if it has been successfully activated before. This method makes plug-in "not running" and callsPlugin.doStop()
method. Note that this method will effectively deactivate all depending plug-ins.- Parameters:
id
- plug-in ID
-
disablePlugin
Disables plug-in (with dependencies) in this manager instance. Disabled plug-in can't be activated although it may be valid and successfully registered with plug-in registry. Before disabling, plug-in will be deactivated if it was successfully activated.Be careful with this method as it can effectively disable large set of inter-depending plug-ins and your application may become unstable or even disabled as whole.
- Parameters:
descr
- descriptor of plug-in to be disabled- Returns:
- descriptors of plug-ins that was actually disabled
-
enablePlugin
Enables plug-in (or plug-ins) in this manager instance. Don't miss this with plug-in activation semantic. Enabled plug-in is simply ready to be activated. By default all loaded plug-ins are enabled.- Parameters:
descr
- descriptor of plug-in to be enabledincludeDependings
- iftrue
, depending plug-ins will be also enabled- Returns:
- descriptors of plug-ins that was actually enabled
- See Also:
-
isPluginEnabled
- Parameters:
descr
- plug-in descriptor- Returns:
true
if given plug-in is disabled in this manager
-
registerListener
Registers plug-in manager event listener. If given listener has been registered before, this method will throw anIllegalArgumentException
.- Parameters:
listener
- new manager event listener
-
unregisterListener
Unregisters manager event listener. If given listener hasn't been registered before, this method will throw anIllegalArgumentException
.- Parameters:
listener
- registered listener
-
initPlugin
Initializes given plug-in with this manager instance and given descriptor.- Parameters:
plugin
- plug-in instance to be initializeddescr
- plug-in descriptor
-
startPlugin
Starts given plug-in. Simply forward call toPlugin.doStart()
method.- Parameters:
plugin
- plug-in to be started- Throws:
Exception
- if any error has occurred during plug-in start
-
stopPlugin
Stops given plug-in. Simply forward call toPlugin.doStop()
method.- Parameters:
plugin
- plug-in to be stopped- Throws:
Exception
- if any error has occurred during plug-in stop
-
disposeClassLoader
Forwards call toPluginClassLoader.dispose()
method.- Parameters:
cl
- plug-in class loader to be disposed
-
notifyClassLoader
Forwards call toPluginClassLoader.pluginsSetChanged()
method.- Parameters:
cl
- plug-in class loader to be notified
-