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

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