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 defined 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'}]
  

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
   
   
  

Since:
1.6.1
Author:
Janne Jalkanen

Nested Class Summary
protected static class PluginManager.WikiPluginInfo
          Contains information about a bunch of plugins.
 
Field Summary
static String DEFAULT_FORMS_PACKAGE
           
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_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
PLUGIN_RESOURCE_LOCATION
 
Constructor Summary
PluginManager(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.
static boolean isPluginLink(String link)
          Returns true if the link is really command to insert a plugin.
 Map parseArgs(String argstring)
          Parses plugin arguments.
 Content parsePluginLine(WikiContext context, String commandline)
           
 boolean pluginsEnabled()
          Returns plugin execution status.
 void setInitStage(boolean value)
          Sets the initialization stage for the initial page scan.
 
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

DEFAULT_FORMS_PACKAGE

public static final String DEFAULT_FORMS_PACKAGE
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_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(Properties props)
Create a new PluginManager.

Parameters:
props - Contents of a "jspwiki.properties" file.
Method Detail

enablePlugins

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


setInitStage

public void setInitStage(boolean value)
Sets the initialization stage for the initial page scan.


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.


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.

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. The plugin body is put into a special parameter defined by PluginManager.PARAM_BODY.
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

parsePluginLine

public Content parsePluginLine(WikiContext context,
                               String commandline)
                        throws PluginException
Throws:
PluginException