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