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.Map;
029import java.util.ResourceBundle;
030
031
032public interface PluginManager extends ModuleManager {
033
034    /** The property name defining which external jars will be added to the classpath when searching for plugin classes. */
035    String PROP_EXTERNALJARS = "jspwiki.plugin.externalJars";
036
037    /** This is the default package to try in case the instantiation fails. */
038    String DEFAULT_PACKAGE = "org.apache.wiki.plugin";
039
040    /** The name of the body content. Current value is "_body". */
041    String PARAM_BODY      = "_body";
042
043    /** The name of the command line content parameter. The value is "_cmdline". */
044    String PARAM_CMDLINE   = "_cmdline";
045
046    /**
047     *  The name of the parameter containing the start and end positions in the read stream of the plugin text (stored as a two-element
048     *  int[], start and end resp.).
049     */
050    String PARAM_BOUNDS    = "_bounds";
051
052    /** A special name to be used in case you want to see debug output */
053    String PARAM_DEBUG     = "debug";
054
055    /**
056     * Enables or disables plugin execution.
057     * 
058     * @param enabled True, if plugins should be globally enabled; false, if disabled.
059     */
060    void enablePlugins( boolean enabled );
061
062    /**
063     * Returns plugin execution status. If false, plugins are not executed when they are encountered on a WikiPage, and an
064     * empty string is returned in their place.
065     * 
066     * @return True, if plugins are enabled; false otherwise.
067     */
068    boolean pluginsEnabled();
069    
070    /**
071     * Returns plugin insert pattern.
072     * 
073     * @return plugin insert pattern.
074     */
075    Pattern getPluginPattern();
076
077    /**
078     * Executes a plugin class in the given context.
079     * <P>Used to be private, but is public since 1.9.21.
080     *
081     * @param context The current WikiContext.
082     * @param classname The name of the class.  Can also be a shortened version without the package name, since the class name is
083     *                 searched from the package search path.
084     * @param params A parsed map of key-value pairs.
085     * @return Whatever the plugin returns.
086     * @throws PluginException If the plugin execution failed for some reason.
087     *
088     * @since 2.0
089     */
090    String execute( Context context, String classname, Map< String, String > params ) throws PluginException;
091
092    /**
093     * Parses plugin arguments.  Handles quotes and all other kewl stuff.
094     *
095     * <h3>Special parameters</h3>
096     * The plugin body is put into a special parameter defined by {@link #PARAM_BODY}; the plugin's command line into a parameter defined
097     * by {@link #PARAM_CMDLINE}; and the bounds of the plugin within the wiki page text by a parameter defined by {@link #PARAM_BOUNDS},
098     * whose value is stored as a two-element int[] array, i.e., <tt>[start,end]</tt>.
099     *
100     * @param argstring The argument string to the plugin.  This is typically a list of key-value pairs, using "'" to escape
101     * spaces in strings, followed by an empty line and then the plugin body.  In case the parameter is null, will return an
102     * empty parameter list.
103     * @return A parsed list of parameters.
104     * @throws IOException If the parsing fails.
105     */
106    Map< String, String > parseArgs( String argstring ) throws IOException;
107
108    /**
109     *  Parses a plugin.  Plugin commands are of the form:<br/>
110     *  {@code [{INSERT myplugin WHERE param1=value1, param2=value2}]}<br/>
111     *  myplugin may either be a class name or a plugin alias.
112     *  <P>
113     *  This is the main entry point that is used.
114     *
115     *  @param context The current WikiContext.
116     *  @param commandline The full command line, including plugin name, parameters and body.
117     *  @return HTML as returned by the plugin, or possibly an error message.
118     *  @throws PluginException From the plugin itself, it propagates, waah!
119     */
120    String execute( Context context, String commandline ) throws PluginException;
121    
122    /**
123     * Creates a {@link Plugin}.
124     * 
125     * @param pluginName plugin's classname
126     * @param rb {@link ResourceBundle} with i18ned text for exceptions.
127     * @return a {@link Plugin}.
128     * @throws PluginException if there is a problem building the {@link Plugin}.
129     */
130    Plugin newWikiPlugin( String pluginName, ResourceBundle rb ) throws PluginException;
131    
132}