Package org.apache.wiki.plugin

Class DefaultPluginManager

java.lang.Object
org.apache.wiki.modules.BaseModuleManager
org.apache.wiki.plugin.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 Details

    • 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 Details

    • 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.

    • getPluginPattern

      public org.apache.oro.text.regex.Pattern getPluginPattern()
      Returns plugin insert pattern.
      Specified by:
      getPluginPattern in interface PluginManager
      Returns:
      plugin insert pattern.

    • 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.

    • getModuleInfo

      public DefaultPluginManager.WikiPluginInfo getModuleInfo​(java.lang.String moduleName)
      Returns the WikiModuleInfo information about the provided moduleName.
      Specified by:
      getModuleInfo in interface ModuleManager
      Returns:
      The wikiModuleInfo

    • newWikiPlugin

      public Plugin newWikiPlugin​(java.lang.String pluginName, java.util.ResourceBundle rb) throws PluginException
      Creates a Plugin.
      Specified by:
      newWikiPlugin in interface PluginManager
      Parameters:
      pluginName - plugin's classname
      rb - ResourceBundle with i18ned text for exceptions.
      Returns:
      a Plugin.
      Throws:
      PluginException - if there is a problem building the Plugin.