Package org.java.plugin
Class PluginManager
- java.lang.Object
-
- org.java.plugin.PluginManager
-
- Direct Known Subclasses:
StandardPluginManager
public abstract class PluginManager extends java.lang.Object
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:
ObjectFactory.createManager()
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
PluginManager.EventListener
Plug-ins life-cycle events callback interface.static class
PluginManager.EventListenerAdapter
An abstract adapter class for receiving plug-ins life-cycle events.static interface
PluginManager.PluginLocation
Simple callback interface to hold info about plug-in manifest and plug-in data locations.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
VERSION
JPF version number.static java.lang.String
VERSION_PROPERTY
JPF version system property name.
-
Constructor Summary
Constructors Constructor Description PluginManager()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract void
activatePlugin(java.lang.String id)
Activates plug-in with given ID if it is not activated yet.abstract void
deactivatePlugin(java.lang.String id)
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 void
disposeClassLoader(PluginClassLoader cl)
Forwards call toPluginClassLoader.dispose()
method.abstract PluginDescriptor[]
enablePlugin(PluginDescriptor descr, boolean includeDependings)
Enables plug-in (or plug-ins) in this manager instance.abstract PathResolver
getPathResolver()
abstract Plugin
getPlugin(java.lang.String id)
Looks for plug-in with given ID and activates it if it is not activated yet.abstract PluginClassLoader
getPluginClassLoader(PluginDescriptor descr)
Returns instance of plug-in's class loader and not tries to activate plug-in.abstract Plugin
getPluginFor(java.lang.Object obj)
Looks for plug-in, given object belongs to.abstract PluginRegistry
getRegistry()
protected void
initPlugin(Plugin plugin, PluginDescriptor descr)
Initializes given plug-in with this manager instance and given descriptor.abstract boolean
isBadPlugin(PluginDescriptor descr)
abstract boolean
isPluginActivated(PluginDescriptor descr)
abstract boolean
isPluginActivating(PluginDescriptor descr)
abstract boolean
isPluginEnabled(PluginDescriptor descr)
static PluginManager
lookup(java.lang.Object obj)
Looks for plug-in manager instance for given object.protected void
notifyClassLoader(PluginClassLoader cl)
Forwards call toPluginClassLoader.pluginsSetChanged()
method.abstract java.util.Map<java.lang.String,Identity>
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 void
startPlugin(Plugin plugin)
Starts given plug-in.protected void
stopPlugin(Plugin plugin)
Stops given plug-in.abstract void
unregisterListener(PluginManager.EventListener listener)
Unregisters manager event listener.
-
-
-
Field Detail
-
VERSION
public static final java.lang.String VERSION
JPF version number.- See Also:
- Constant Field Values
-
VERSION_PROPERTY
public static final java.lang.String VERSION_PROPERTY
JPF version system property name.- See Also:
- Constant Field Values
-
-
Method Detail
-
lookup
public static PluginManager lookup(java.lang.Object obj)
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
public abstract PluginRegistry getRegistry()
- Returns:
- registry, used by this manager
-
getPathResolver
public abstract PathResolver getPathResolver()
- Returns:
- path resolver
-
publishPlugins
public abstract java.util.Map<java.lang.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:
PluginDescriptor
,PluginFragment
-
getPlugin
public abstract Plugin getPlugin(java.lang.String id) throws PluginLifecycleException
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
public abstract void activatePlugin(java.lang.String id) throws PluginLifecycleException
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
public abstract Plugin getPluginFor(java.lang.Object obj)
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
public abstract boolean isPluginActivated(PluginDescriptor descr)
- Parameters:
descr
- plug-in descriptor- Returns:
true
if plug-in with given descriptor is activated
-
isBadPlugin
public abstract boolean isBadPlugin(PluginDescriptor descr)
- Parameters:
descr
- plug-in descriptor- Returns:
true
if plug-in disabled as it's activation fails
-
isPluginActivating
public abstract boolean isPluginActivating(PluginDescriptor descr)
- Parameters:
descr
- plug-in descriptor- Returns:
true
if plug-in is currently activating
-
getPluginClassLoader
public abstract PluginClassLoader getPluginClassLoader(PluginDescriptor descr)
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
public abstract void deactivatePlugin(java.lang.String id)
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
public abstract PluginDescriptor[] disablePlugin(PluginDescriptor descr)
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
public abstract PluginDescriptor[] enablePlugin(PluginDescriptor descr, boolean includeDependings)
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:
disablePlugin(PluginDescriptor)
-
isPluginEnabled
public abstract boolean isPluginEnabled(PluginDescriptor descr)
- Parameters:
descr
- plug-in descriptor- Returns:
true
if given plug-in is disabled in this manager
-
registerListener
public abstract void registerListener(PluginManager.EventListener listener)
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
public abstract void unregisterListener(PluginManager.EventListener listener)
Unregisters manager event listener. If given listener hasn't been registered before, this method will throw anIllegalArgumentException
.- Parameters:
listener
- registered listener
-
initPlugin
protected final void initPlugin(Plugin plugin, PluginDescriptor descr)
Initializes given plug-in with this manager instance and given descriptor.- Parameters:
plugin
- plug-in instance to be initializeddescr
- plug-in descriptor
-
startPlugin
protected final void startPlugin(Plugin plugin) throws java.lang.Exception
Starts given plug-in. Simply forward call toPlugin.doStart()
method.- Parameters:
plugin
- plug-in to be started- Throws:
java.lang.Exception
- if any error has occurred during plug-in start
-
stopPlugin
protected final void stopPlugin(Plugin plugin) throws java.lang.Exception
Stops given plug-in. Simply forward call toPlugin.doStop()
method.- Parameters:
plugin
- plug-in to be stopped- Throws:
java.lang.Exception
- if any error has occurred during plug-in stop
-
disposeClassLoader
protected final void disposeClassLoader(PluginClassLoader cl)
Forwards call toPluginClassLoader.dispose()
method.- Parameters:
cl
- plug-in class loader to be disposed
-
notifyClassLoader
protected final void notifyClassLoader(PluginClassLoader cl)
Forwards call toPluginClassLoader.pluginsSetChanged()
method.- Parameters:
cl
- plug-in class loader to be notified
-
-