The __[RestrictedWikiPlugin]__ is part of the [NeWikiPlugin] package. It is an ''abstract class'' (not an actual plugin) that adds the ability to restrict usage of WikiPlugins that extend this class, enabling, disabling or permitting '[open-wiki|OpenWikiPlugin]', asserted and/or authenticated use. This is done via configuration in the JSPWiki properties file, where to restrict the use of a specific plugin the property name consists of the prefix "{{restrict-}}" plus the fully-qualified package name of the plugin. The property value is one of the following (in the order of increasing restriction):

* "{{enabled}}" : If the value is 'enabled', the plugin is always enabled. This is recommended for plugins that have no security implications
* "{{open-wiki}}" : If the value is 'open-wiki', the plugin is enabled if the 'open-wiki' flag is true, regardless of a user's authentication state. See OpenWikiPlugin
* "{{asserted}}" : If the value is 'asserted', the plugin is enabled if the user is asserted
* "{{authenticated}}" : If the value is 'authenticated', the plugin is enabled if the user is authenticated
* "{{authenticated+open-wiki}}" : If the value is 'authenticated+open-wiki', the plugin is enabled if the user is authenticated AND the 'open-wiki' flag is true. This is more restrictive than either 'authenticated' OR 'open-wiki'
* "{{disabled}}" : If the value is 'disabled', the plugin is always disabled

Because the default behaviour when unconfigured is '{{disabled}}', if you wish to permit unlimited use of a restricted plugin you must include it in the JSPWiki configuration with a setting of '{{enabled}}'.


!! Usage

All subclasses should call {{checkRestrictions(WikiContext)}} at the beginning of a {{try}} loop. If the check indicates that the restrictions on the plugin have not been met it will throw a __RestrictedPluginException__ whose HTML error message can be returned to the user (i.e., as HTML markup on the wiki page). You should include a {{catch()}} for the {{try}} that calls the exception's {{RestrictedPluginException.getHTML()}} method, returning that as the result. E.g.,

%%(font-size:smaller)
%%prettify
{{{
   try {
       checkRestrictions(context);
       ...
   } catch ( RestrictedPluginException rpe ) {
       return rpe.getHTML();
   } catch ( Exception e ) {
       return ...;
   }
}}}
%%
%%

Failures due to plugin restrictions are considered as warnings, not errors, and therefore use the '{{banner_warning}}' [Banner Style|BannerStyles].


!! Initialisation


When any installed {{RestrictedWikiPlugin}} calls the superclass method {{WikiPlugin.execute(WikiContext, Map)}} for a first time, this grabs the WikiEngine from the WikiContext via the plugin's {{WikiPlugin.execute(WikiContext, Map)}} method, iterates through the properties whose name begins with "{{restrict-}}", and caches the map. No modification of this map can occur after it has been created (this may also be considered a security feature, as a disabled plugin cannot subsequently be enabled by changing the wiki's property set). 


!! Example:

With a property file containing:
{{{
restrict-org.apache.wiki.plugin.RestrictedEnabledTestPlugin=enabled
restrict-org.apache.wiki.plugin.RestrictedOpenWikiTestPlugin=open-wiki
restrict-org.apache.wiki.plugin.RestrictedAssertedTestPlugin=asserted
restrict-org.apache.wiki.plugin.RestrictedAuthenticatedTestPlugin=authenticated
restrict-org.apache.wiki.plugin.RestrictedAuthenticatedOpenWikiTestPlugin=authenticated+open-wiki
restrict-org.apache.wiki.plugin.RestrictedDisabledTestPlugin=disabled
}}}

and 'open-wiki' set as:

[{OpenWiki}]

the set of test plugins produces varying results depending on the aforementioned 
configuration and the authentication state of the user:

! RestrictedEnabledTestPlugin
[{RestrictedEnabledTestPlugin}]
----
! RestrictedOpenWikiTestPlugin
[{RestrictedOpenWikiTestPlugin}]
----
! RestrictedAssertedTestPlugin
[{RestrictedAssertedTestPlugin}]
----
! RestrictedAuthenticatedTestPlugin
[{RestrictedAuthenticatedTestPlugin}]
----
!  RestrictedAuthenticatedOpenWikiTestPlugin
[{RestrictedAuthenticatedOpenWikiTestPlugin}]
----
! RestrictedDisabledTestPlugin
[{RestrictedDisabledTestPlugin}]
----

!! Known RestrictedWikiPlugins (by Tag)

[{HasTagOf RestrictedWikiPlugin}]

----

[{Tag NeWikiPlugin RestrictedWikiPlugin}]