org.apache.wiki.plugin
Class DefaultPluginManager

java.lang.Object
  org.apache.wiki.modules.ModuleManager
      org.apache.wiki.plugin.DefaultPluginManager

All Implemented Interfaces:

PluginManager

public class DefaultPluginManager
extends ModuleManager
implements PluginManager

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 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 WikiEngine 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.
• WikiPlugin: 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

Nested Class Summary

static class

DefaultPluginManager.WikiPluginInfo Contains information about a bunch of plugins.

Field Summary

Fields inherited from class org.apache.wiki.modules.ModuleManager

m_engine, PLUGIN_RESOURCE_LOCATION

Fields inherited from interface org.apache.wiki.api.engine.PluginManager

DEFAULT_PACKAGE, PARAM_BODY, PARAM_BOUNDS, PARAM_CMDLINE, PARAM_DEBUG, PROP_EXTERNALJARS, PROP_SEARCHPATH

Constructor Summary

DefaultPluginManager(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<String,String> params) Executes a plugin class in the given context.
org.apache.oro.text.regex.Pattern	getPluginPattern() Returns plugin insert pattern.
String	getPluginSearchPath() Returns plugins' search path.
Collection<WikiModuleInfo>	modules() Returns a collection of modules currently managed by this ModuleManager.
WikiPlugin	newWikiPlugin(String pluginName, ResourceBundle rb) Creates a WikiPlugin.
Map<String,String>	parseArgs(String argstring) Parses plugin arguments.
boolean	pluginsEnabled() Returns plugin execution status.

Methods inherited from class org.apache.wiki.modules.ModuleManager

checkCompatibility

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultPluginManager

public DefaultPluginManager(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.

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.

getPluginSearchPath

public String getPluginSearchPath()

Returns plugins' search path.

Specified by:

getPluginSearchPath in interface PluginManager

Returns:

plugins' search path.

execute

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

Since:

2.0

parseArgs

public Map<String,String> 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 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:

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.

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 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 PluginManager

Specified by:

modules in class ModuleManager

Returns:

A Collection of WikiModuleInfo instances.

newWikiPlugin

public WikiPlugin newWikiPlugin(String pluginName,
                                ResourceBundle rb)
                         throws PluginException

Creates a WikiPlugin.

Specified by:

newWikiPlugin in interface PluginManager

Parameters:

pluginName - plugin's classname

rb - ResourceBundle with i18ned text for exceptions.

Returns:

a WikiPlugin.

Throws:

PluginException - if there is a problem building the WikiPlugin.