    001/*
    002    Licensed to the Apache Software Foundation (ASF) under one
    003    or more contributor license agreements.  See the NOTICE file
    004    distributed with this work for additional information
    005    regarding copyright ownership.  The ASF licenses this file
    006    to you under the Apache License, Version 2.0 (the
    007    "License"); you may not use this file except in compliance
    008    with the License.  You may obtain a copy of the License at
    009
    010       http://www.apache.org/licenses/LICENSE-2.0
    011
    012    Unless required by applicable law or agreed to in writing,
    013    software distributed under the License is distributed on an
    014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015    KIND, either express or implied.  See the License for the
    016    specific language governing permissions and limitations
    017    under the License.
    018 */
    019package org.apache.wiki.plugin;
    020
    021import org.apache.oro.text.regex.Pattern;
    022import org.apache.wiki.api.core.Context;
    023import org.apache.wiki.api.exceptions.PluginException;
    024import org.apache.wiki.api.plugin.Plugin;
    025import org.apache.wiki.modules.ModuleManager;
    026
    027import java.io.IOException;
    028import java.util.List;
    029import java.util.Map;
    030import java.util.ResourceBundle;
    031
    032
    033public interface PluginManager extends ModuleManager {
    034
    035    /** The property name defining which external jars will be added to the classpath when searching for plugin classes. */
    036    String PROP_EXTERNALJARS = "jspwiki.plugin.externalJars";
    037
    038    /** This is the default package to try in case the instantiation fails. */
    039    String DEFAULT_PACKAGE = "org.apache.wiki.plugin";
    040
    041    /** The name of the body content. Current value is "_body". */
    042    String PARAM_BODY      = "_body";
    043
    044    /** The name of the command line content parameter. The value is "_cmdline". */
    045    String PARAM_CMDLINE   = "_cmdline";
    046
    047    /**
    048     *  The name of the parameter containing the start and end positions in the read stream of the plugin text (stored as a two-element
    049     *  int[], start and end resp.).
    050     */
    051    String PARAM_BOUNDS    = "_bounds";
    052
    053    /** A special name to be used in case you want to see debug output */
    054    String PARAM_DEBUG     = "debug";
    055
    056    /**
    057     * Enables or disables plugin execution.
    058     *
    059     * @param enabled True, if plugins should be globally enabled; false, if disabled.
    060     */
    061    void enablePlugins( boolean enabled );
    062
    063    /**
    064     * Returns plugin execution status. If false, plugins are not executed when they are encountered on a WikiPage, and an
    065     * empty string is returned in their place.
    066     *
    067     * @return True, if plugins are enabled; false otherwise.
    068     */
    069    boolean pluginsEnabled();
    070
    071    /**
    072     * Returns plugin insert pattern.
    073     *
    074     * @return plugin insert pattern.
    075     */
    076    Pattern getPluginPattern();
    077
    078    /**
    079     * Executes a plugin class in the given context.
    080     * <P>Used to be private, but is public since 1.9.21.
    081     *
    082     * @param context The current WikiContext.
    083     * @param classname The name of the class.  Can also be a shortened version without the package name, since the class name is
    084     *                 searched from the package search path.
    085     * @param params A parsed map of key-value pairs.
    086     * @return Whatever the plugin returns.
    087     * @throws PluginException If the plugin execution failed for some reason.
    088     *
    089     * @since 2.0
    090     */
    091    String execute( Context context, String classname, Map< String, String > params ) throws PluginException;
    092
    093    /**
    094     * Parses plugin arguments.  Handles quotes and all other kewl stuff.
    095     *
    096     * <h3>Special parameters</h3>
    097     * The plugin body is put into a special parameter defined by {@link #PARAM_BODY}; the plugin's command line into a parameter defined
    098     * by {@link #PARAM_CMDLINE}; and the bounds of the plugin within the wiki page text by a parameter defined by {@link #PARAM_BOUNDS},
    099     * whose value is stored as a two-element int[] array, i.e., <tt>[start,end]</tt>.
    100     *
    101     * @param argstring The argument string to the plugin.  This is typically a list of key-value pairs, using "'" to escape
    102     * spaces in strings, followed by an empty line and then the plugin body.  In case the parameter is null, will return an
    103     * empty parameter list.
    104     * @return A parsed list of parameters.
    105     * @throws IOException If the parsing fails.
    106     */
    107    Map< String, String > parseArgs( String argstring ) throws IOException;
    108
    109    /**
    110     *  Parses a plugin.  Plugin commands are of the form:<br/>
    111     *  {@code [{INSERT myplugin WHERE param1=value1, param2=value2}]}<br/>
    112     *  myplugin may either be a class name or a plugin alias.
    113     *  <P>
    114     *  This is the main entry point that is used.
    115     *
    116     *  @param context The current WikiContext.
    117     *  @param commandline The full command line, including plugin name, parameters and body.
    118     *  @return HTML as returned by the plugin, or possibly an error message.
    119     *  @throws PluginException From the plugin itself, it propagates, waah!
    120     */
    121    String execute( Context context, String commandline ) throws PluginException;
    122
    123    /**
    124     * Creates a {@link Plugin}.
    125     *
    126     * @param pluginName plugin's classname
    127     * @param rb {@link ResourceBundle} with i18ned text for exceptions.
    128     * @return a {@link Plugin}.
    129     * @throws PluginException if there is a problem building the {@link Plugin}.
    130     */
    131    Plugin newWikiPlugin( String pluginName, ResourceBundle rb ) throws PluginException;
    132
    133    /**
    134     * gets a list of plugins available via the java service provider discovery
    135     * mechanism. Helpful for populating autocomplete capabilities.
    136     *
    137     * @since 3.0.0
    138     * @return list of plugin instances.
    139     */
    140    List<Plugin> getDiscoveredPlugins();
    141
    142}