1 package com.atlassian.plugin.parsers;
2
3 import com.atlassian.plugin.ModuleDescriptor;
4 import com.atlassian.plugin.ModuleDescriptorFactory;
5 import com.atlassian.plugin.Plugin;
6 import com.atlassian.plugin.PluginInformation;
7 import com.atlassian.plugin.PluginParseException;
8 import org.dom4j.Element;
9
10 /**
11 * Interface for parsing a plugin descriptor file, e.g. atlassian-plugin.xml.
12 *
13 * @see XmlDescriptorParser
14 * @see DescriptorParserFactory
15 */
16 public interface DescriptorParser {
17 /**
18 * Sets the configuration on the plugin argument to match the configuration specified in the
19 * plugin descriptor (typically an XML file).
20 *
21 * @param moduleDescriptorFactory a factory for instantiating the required plugin modules
22 * @param plugin the plugin whose configuration will be modified
23 * @return the original plugin with the configuration changed and the module descriptors added
24 * @throws PluginParseException if there was an error getting information about the plugin
25 */
26 Plugin configurePlugin(ModuleDescriptorFactory moduleDescriptorFactory, Plugin plugin) throws PluginParseException;
27
28 /**
29 * @return the key of the plugin specified in the descriptor
30 */
31 String getKey();
32
33 /**
34 * @return true if this plugin is marked as a system plugin in the descriptor. This should only be
35 * acted on by plugin loaders which can trust their plugins implicitly (e.g. a classpath plugin
36 * loader).
37 * @deprecated The parser will set the SystemPlugin flag within the configurePlugin() method, so there is no need to use this externally.
38 * See PLUG-415. Deprecated since 2.3.0
39 */
40 boolean isSystemPlugin();
41
42 /**
43 * @return The version of the plugin system expected by this plugin. If unknown, it is assumed to be 1.
44 */
45 int getPluginsVersion();
46
47 PluginInformation getPluginInformation();
48
49 /**
50 * Create a new module and initialise it with the plugin, then return it.
51 * <p>
52 * In the event of a problem loading the module, return an {@link com.atlassian.plugin.descriptors.UnrecognisedModuleDescriptor}
53 * with error.
54 *
55 * @param moduleDescriptorFactory basic factory, may be overridden
56 * @param plugin that the module will be initialised with
57 * @param module to create
58 * @since 4.0.0
59 */
60 ModuleDescriptor<?> addModule(ModuleDescriptorFactory moduleDescriptorFactory, Plugin plugin, Element module);
61 }