JPF 1.5.1

org.java.plugin
Class PluginManager

java.lang.Object
  extended by 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
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
static java.lang.String VERSION
          JPF version number.
static java.lang.String VERSION_PROPERTY
          JPF version system property name.
 
Constructor Summary
PluginManager()
           
 
Method Summary
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 to PluginClassLoader.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 to PluginClassLoader.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.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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
Constructor Detail

PluginManager

public PluginManager()
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 to PluginRegistry.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 return null.

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 calls Plugin.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 calls Plugin.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 enabled
includeDependings - if true, 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 an IllegalArgumentException.

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 an IllegalArgumentException.

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 initialized
descr - plug-in descriptor

startPlugin

protected final void startPlugin(Plugin plugin)
                          throws java.lang.Exception
Starts given plug-in. Simply forward call to Plugin.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 to Plugin.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 to PluginClassLoader.dispose() method.

Parameters:
cl - plug-in class loader to be disposed

notifyClassLoader

protected final void notifyClassLoader(PluginClassLoader cl)
Forwards call to PluginClassLoader.pluginsSetChanged() method.

Parameters:
cl - plug-in class loader to be notified

JPF 1.5.1

Copyright © 2004-2007 Dmitry Olshansky. All Rights Reserved.