Class PluginManager

java.lang.Object
org.java.plugin.PluginManager
Direct Known Subclasses:
StandardPluginManager

public abstract class PluginManager extends 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:
  • Field Details

  • Constructor Details

    • PluginManager

      public PluginManager()
  • Method Details

    • lookup

      public static PluginManager lookup(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 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 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:
    • getPlugin

      public abstract Plugin getPlugin(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(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(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(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:
    • 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 Exception
      Starts given plug-in. Simply forward call to Plugin.doStart() method.
      Parameters:
      plugin - plug-in to be started
      Throws:
      Exception - if any error has occurred during plug-in start
    • stopPlugin

      protected final void stopPlugin(Plugin plugin) throws Exception
      Stops given plug-in. Simply forward call to Plugin.doStop() method.
      Parameters:
      plugin - plug-in to be stopped
      Throws:
      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