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.

      <modules>

           <author>Janne Jalkanen</author>

           <stylesheet>foo.css</stylesheet>
           <alias>code</alias>

           <author>Janne Jalkanen</author>

       </modules>

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

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static final class`
`DefaultPluginManager.WikiPluginInfo`
Contains information about a bunch of plugins.

## Field Summary

### Fields inherited from class org.apache.wiki.modules.BaseModuleManager

`m_engine`

### Fields inherited from interface org.apache.wiki.modules.ModuleManager

`PLUGIN_RESOURCE_LOCATION`

### Fields inherited from interface org.apache.wiki.plugin.PluginManager

`DEFAULT_PACKAGE, PARAM_BODY, PARAM_BOUNDS, PARAM_CMDLINE, PARAM_DEBUG, PROP_EXTERNALJARS`

## Constructor Summary

Constructors
Constructor
Description
`DefaultPluginManager(Engine engine, Properties props)`
Create a new PluginManager.

## Method Summary

Modifier and Type
Method
Description
`void`
`enablePlugins(boolean enabled)`
Enables or disables plugin execution.
`String`
`execute(Context context, String commandline)`
Parses a plugin.
`String`
`execute(Context context, String classname, Map<String,String> params)`
Executes a plugin class in the given context.
`DefaultPluginManager.WikiPluginInfo`
`getModuleInfo(String moduleName)`
Returns the `WikiModuleInfo` information about the provided moduleName.
`org.apache.oro.text.regex.Pattern`
`getPluginPattern()`
Returns plugin insert pattern.
`Collection<WikiModuleInfo>`
`modules()`
Returns a collection of modules currently managed by this ModuleManager.
`Plugin`
`newWikiPlugin(String pluginName, ResourceBundle rb)`
Creates a `Plugin`.
`Map<String,String>`
`parseArgs(String argstring)`
Parses plugin arguments.
`boolean`
`pluginsEnabled()`
Returns plugin execution status.

### Methods inherited from class org.apache.wiki.modules.BaseModuleManager

`checkCompatibility, modules`

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface org.apache.wiki.modules.ModuleManager

`checkCompatibility`

## Constructor Details

### DefaultPluginManager

public DefaultPluginManager(Engine engine, 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 String execute(Context 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.

### 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(Context 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 `ModuleManager`
Returns:
  A Collection of WikiModuleInfo instances.

### getModuleInfo

public DefaultPluginManager.WikiPluginInfo getModuleInfo(String moduleName)
Returns the `WikiModuleInfo` information about the provided moduleName.

Specified by:
  `getModuleInfo` in interface `ModuleManager`
Returns:
  The wikiModuleInfo

### newWikiPlugin

public Plugin newWikiPlugin(String pluginName, 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`.