com.ecyrd.jspwiki.plugin
Class PluginManager

java.lang.Object
  extended by com.ecyrd.jspwiki.modules.ModuleManager
      extended by com.ecyrd.jspwiki.plugin.PluginManager

public class PluginManager
extends ModuleManager

Manages plugin classes. There exists a single instance of PluginManager per each instance of WikiEngine, 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 com.ecyrd.jspwiki.plugin.FunnyPlugin  foo='bar'
  blob='goo'

  abcdefghijklmnopqrstuvw
  01234567890}]
  
The plugin class is "com.ecyrd.jspwiki.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 "com.ecyrd.jspwiki.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 com.ecyrd.jspwiki.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:

Since:
1.6.1

Nested Class Summary
static class PluginManager.WikiPluginInfo
          Contains information about a bunch of plugins.
 
Field Summary
static String DEFAULT_PACKAGE
          This is the default package to try in case the instantiation fails.
static String PARAM_BODY
          The name of the body content.
static String PARAM_BOUNDS
          The name of the parameter containing the start and end positions in the read stream of the plugin text (stored as a two-element int[], start and end resp.).
static String PARAM_CMDLINE
          The name of the command line content parameter.
static String PARAM_DEBUG
          A special name to be used in case you want to see debug output
static String PROP_SEARCHPATH
          The property name defining which packages will be searched for properties.
 
Fields inherited from class com.ecyrd.jspwiki.modules.ModuleManager
m_engine, PLUGIN_RESOURCE_LOCATION
 
Constructor Summary
PluginManager(WikiEngine engine, Properties props)
          Create a new PluginManager.
 
Method Summary
 void enablePlugins(boolean enabled)
          Enables or disables plugin execution.
 String execute(WikiContext context, String commandline)
          Parses a plugin.
 String execute(WikiContext context, String classname, Map params)
          Executes a plugin class in the given context.
 void executeParse(PluginContent content, WikiContext context)
          Executes parse stage, unless plugins are disabled.
static boolean isPluginLink(String link)
          Returns true if the link is really command to insert a plugin.
 Collection modules()
          Returns a collection of modules currently managed by this ModuleManager.
 Map parseArgs(String argstring)
          Parses plugin arguments.
 PluginContent parsePluginLine(WikiContext context, String commandline, int pos)
          Parses a plugin invocation and returns a DOM element.
 boolean pluginsEnabled()
          Returns plugin execution status.
 
Methods inherited from class com.ecyrd.jspwiki.modules.ModuleManager
checkCompatibility
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_PACKAGE

public static final String DEFAULT_PACKAGE
This is the default package to try in case the instantiation fails.

See Also:
Constant Field Values

PROP_SEARCHPATH

public static final String PROP_SEARCHPATH
The property name defining which packages will be searched for properties.

See Also:
Constant Field Values

PARAM_BODY

public static final String PARAM_BODY
The name of the body content. Current value is "_body".

See Also:
Constant Field Values

PARAM_CMDLINE

public static final String PARAM_CMDLINE
The name of the command line content parameter. The value is "_cmdline".

See Also:
Constant Field Values

PARAM_BOUNDS

public static final String PARAM_BOUNDS
The name of the parameter containing the start and end positions in the read stream of the plugin text (stored as a two-element int[], start and end resp.).

See Also:
Constant Field Values

PARAM_DEBUG

public static final String PARAM_DEBUG
A special name to be used in case you want to see debug output

See Also:
Constant Field Values
Constructor Detail

PluginManager

public PluginManager(WikiEngine engine,
                     Properties props)
Create a new PluginManager.

Parameters:
engine - WikiEngine which owns this manager.
props - Contents of a "jspwiki.properties" file.
Method Detail

enablePlugins

public void enablePlugins(boolean enabled)
Enables or disables plugin execution.

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.

Returns:
True, if plugins are enabled; false otherwise.

isPluginLink

public static boolean isPluginLink(String link)
Returns true if the link is really command to insert a plugin.

Currently we just check if the link starts with "{INSERT", or just plain "{" but not "{$".

Parameters:
link - Link text, i.e. the contents of text between [].
Returns:
True, if this link seems to be a command to insert a plugin here.

execute

public String execute(WikiContext context,
                      String classname,
                      Map params)
               throws PluginException
Executes a plugin class in the given context.

Used to be private, but is public since 1.9.21.

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.
Since:
2.0

parseArgs

public Map parseArgs(String argstring)
              throws IOException
Parses plugin arguments. Handles quotes and all other kewl stuff.

Special parameters

The plugin body is put into a special parameter defined by PARAM_BODY; the plugin's command line into a parameter defined by PARAM_CMDLINE; and the bounds of the plugin within the wiki page text by a parameter defined by PARAM_BOUNDS, whose value is stored as a two-element int[] array, i.e., [start,end].

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:
IOException - If the parsing fails.

execute

public String execute(WikiContext context,
                      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.

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!

parsePluginLine

public PluginContent parsePluginLine(WikiContext context,
                                     String commandline,
                                     int pos)
                              throws PluginException
Parses a plugin invocation and returns a DOM element.

Parameters:
context - The WikiContext
commandline - The line to parse
pos - The position in the stream parsing.
Returns:
A DOM element
Throws:
PluginException - If plugin invocation is faulty

modules

public Collection 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 class ModuleManager
Returns:
A Collection of WikiModuleInfo instances.

executeParse

public void executeParse(PluginContent content,
                         WikiContext context)
                  throws PluginException
Executes parse stage, unless plugins are disabled.

Parameters:
content - The content item.
context - A WikiContext
Throws:
PluginException - If something goes wrong.