Package org.apache.wiki.plugin

Class DefaultPluginManager

  • All Implemented Interfaces:
    ModuleManager, PluginManager
    public class DefaultPluginManager
extends BaseModuleManager
implements PluginManager
    Manages plugin classes. There exists a single instance of PluginManager per each instance of Engine, that is, each JSPWiki instance.

    A plugin is defined to have three parts:

    1. The plugin class
    2. The plugin parameters
    3. The plugin body
    For example, in the following line of code: 
      [{INSERT org.apache.wiki.plugin.FunnyPlugin  foo='bar'
  blob='goo'

  abcdefghijklmnopqrstuvw
  01234567890}]
    The plugin class is "org.apache.wiki.plugin.FunnyPlugin", the parameters are "foo" and "blob" (having values "bar" and "goo", respectively), and the plugin body is then "abcdefghijklmnopqrstuvw\n01234567890". The plugin body is accessible via a special parameter called "_body".

    If the parameter "debug" is set to "true" for the plugin, JSPWiki will output debugging information directly to the page if there is an exception.

    The class name can be shortened, and marked without the package. For example, "FunnyPlugin" would be expanded to "org.apache.wiki.plugin.FunnyPlugin" automatically. It is also possible to define other packages, by setting the "jspwiki.plugin.searchPath" property. See the included jspwiki.properties file for examples.

    Even though the nominal way of writing the plugin is 

      [{INSERT pluginclass WHERE param1=value1...}],
    it is possible to shorten this quite a lot, by skipping the INSERT, and WHERE words, and dropping the package name. For example: 
      [{INSERT org.apache.wiki.plugin.Counter WHERE name='foo'}]
    is the same as 
      [{Counter name='foo'}]

    Plugin property files

    Since 2.3.25 you can also define a generic plugin XML properties file per each JAR file. 

      
   
       Janne Jalkanen
       
       foo.css
       code
   
   
       Janne Jalkanen

    Plugin lifecycle

    Plugin can implement multiple interfaces to let JSPWiki know at which stages they should be invoked:

    • InitializablePlugin: If your plugin implements this interface, the initialize()-method is called once for this class before any actual execute() methods are called. You should use the initialize() for e.g. precalculating things. But notice that this method is really called only once during the entire Engine lifetime. The InitializablePlugin is available from 2.5.30 onwards.
    • ParserStagePlugin: If you implement this interface, the executeParse() method is called when JSPWiki is forming the DOM tree. You will receive an incomplete DOM tree, as well as the regular parameters. However, since JSPWiki caches the DOM tree to speed up later places, which means that whatever this method returns would be irrelevant. You can do some DOM tree manipulation, though. The ParserStagePlugin is available from 2.5.30 onwards.
    • Plugin: The regular kind of plugin which is executed at every rendering stage. Each new page load is guaranteed to invoke the plugin, unlike with the ParserStagePlugins.
    Since:
    1.6.1

    • Constructor Detail

      • DefaultPluginManager

        public DefaultPluginManager​(Engine engine,
                            java.util.Properties props)
        Create a new PluginManager.
        Parameters:
        engine - Engine which owns this manager.
        props - Contents of a "jspwiki.properties" file.

    • Method Detail

      • enablePlugins

        public void enablePlugins​(boolean enabled)
        Enables or disables plugin execution.
        Specified by:
        enablePlugins in interface PluginManager
        Parameters:
        enabled - True, if plugins should be globally enabled; false, if disabled.

      • pluginsEnabled

        public boolean pluginsEnabled()
        Returns plugin execution status. If false, plugins are not executed when they are encountered on a WikiPage, and an empty string is returned in their place.
        Specified by:
        pluginsEnabled in interface PluginManager
        Returns:
        True, if plugins are enabled; false otherwise.

      • execute

        public java.lang.String execute​(Context context,
                                java.lang.String classname,
                                java.util.Map<java.lang.String,​java.lang.String> params)
                         throws PluginException
        Executes a plugin class in the given context.

        Used to be private, but is public since 1.9.21.

        Specified by:
        execute in interface PluginManager
        Parameters:
        context - The current WikiContext.
        classname - The name of the class. Can also be a shortened version without the package name, since the class name is searched from the package search path.
        params - A parsed map of key-value pairs.
        Returns:
        Whatever the plugin returns.
        Throws:
        PluginException - If the plugin execution failed for some reason.

      • parseArgs

        public java.util.Map<java.lang.String,​java.lang.String> parseArgs​(java.lang.String argstring)
                                                                 throws java.io.IOException
        Parses plugin arguments. Handles quotes and all other kewl stuff.

        Special parameters

        The plugin body is put into a special parameter defined by PluginManager.PARAM_BODY; the plugin's command line into a parameter defined by PluginManager.PARAM_CMDLINE; and the bounds of the plugin within the wiki page text by a parameter defined by PluginManager.PARAM_BOUNDS, whose value is stored as a two-element int[] array, i.e., [start,end].
        Specified by:
        parseArgs in interface PluginManager
        Parameters:
        argstring - The argument string to the plugin. This is typically a list of key-value pairs, using "'" to escape spaces in strings, followed by an empty line and then the plugin body. In case the parameter is null, will return an empty parameter list.
        Returns:
        A parsed list of parameters.
        Throws:
        java.io.IOException - If the parsing fails.

      • execute

        public java.lang.String execute​(Context context,
                                java.lang.String commandline)
                         throws PluginException
        Parses a plugin. Plugin commands are of the form:
        [{INSERT myplugin WHERE param1=value1, param2=value2}]
        myplugin may either be a class name or a plugin alias.

        This is the main entry point that is used.

        Specified by:
        execute in interface PluginManager
        Parameters:
        context - The current WikiContext.
        commandline - The full command line, including plugin name, parameters and body.
        Returns:
        HTML as returned by the plugin, or possibly an error message.
        Throws:
        PluginException - From the plugin itself, it propagates, waah!

      • modules

        public java.util.Collection<WikiModuleInfo> modules()
        Returns a collection of modules currently managed by this ModuleManager. Each entry is an instance of the WikiModuleInfo class. This method should return something which is safe to iterate over, even if the underlying collection changes.
        Specified by:
        modules in interface ModuleManager
        Returns:
        A Collection of WikiModuleInfo instances.