Class 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()
    • 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