1 package com.atlassian.plugin;
2
3 import org.dom4j.Element;
4 import org.slf4j.LoggerFactory;
5
6 import java.util.Collection;
7 import java.util.Set;
8
9 /**
10 * Interface to control the state of the plugin system
11 */
12 public interface PluginController {
13 /**
14 * Enable a plugin by key.
15 *
16 * @param key The plugin key.
17 * @deprecated since 2.5.0, use {#link enablePlugins(String... keys)} instead
18 */
19 void enablePlugin(String key);
20
21 /**
22 * Enable a set of plugins by key. This will implicitly and recursively enable all dependent plugins
23 *
24 * @param keys The plugin keys. Must not be null.
25 * @since 2.5.0
26 */
27 void enablePlugins(String... keys);
28
29 /**
30 * Disables the plugin with the given key.
31 * <p>
32 * Calling this method will persist the disabled state so that the plugin will also be disabled on next startup.
33 * This would normally be used when a user manually disables a plugin.
34 * <p>
35 * If you extend DefaultPluginManager and override this method, you will also need to override {@link #disablePluginWithoutPersisting(String)}.
36 * <p>
37 * Mandatory dependent plugins will also be disabled. Optionally dependent plugins will be disabled then enabled.
38 * Dynamically dependent plugins will not be disabled.
39 *
40 * @param key The plugin key.
41 * @see #disablePluginWithoutPersisting(String)
42 * @see Plugin#getDependencies()
43 */
44 void disablePlugin(String key);
45
46 /**
47 * Disables the plugin with the given key without persisting the disabled state.
48 * <p>
49 * Calling this method will NOT persist the disabled state so that the framework will try to enable the plugin on next startup.
50 * This is used when a plugin has errors on startup.
51 * <p>
52 * If you extend DefaultPluginManager and override {@link #disablePlugin(String)}, you will also need to override this method.
53 * <p>
54 * Mandatory dependent plugins will also be disabled. Optionally dependent plugins will be disabled then enabled.
55 * Dynamically dependent plugins will not be disabled.
56 *
57 * @param key The plugin key.
58 * @see #disablePlugin(String)
59 * @see Plugin#getDependencies()
60 * @since 2.3.0
61 */
62 void disablePluginWithoutPersisting(String key);
63
64 /**
65 * Enable a plugin module by key.
66 *
67 * @param completeKey The "complete key" of the plugin module.
68 */
69 void enablePluginModule(String completeKey);
70
71 /**
72 * Disable a plugin module by key.
73 *
74 * @param completeKey The "complete key" of the plugin module.
75 */
76 void disablePluginModule(String completeKey);
77
78 /**
79 * Installs a plugin and returns the plugin key
80 *
81 * @param pluginArtifact The plugin artifact to install
82 * @return The plugin key
83 * @throws com.atlassian.plugin.PluginParseException if the plugin is not a valid plugin
84 * @deprecated Since 2.3.0, use {@link #installPlugins(PluginArtifact...)} instead
85 */
86 String installPlugin(PluginArtifact pluginArtifact) throws PluginParseException;
87
88 /**
89 * Installs multiple plugins and returns the list of plugin keys. All plugin artifacts must be for valid plugins
90 * or none will be installed.
91 *
92 * @param pluginArtifacts The list of plugin artifacts to install
93 * @return A list of plugin keys
94 * @throws com.atlassian.plugin.PluginParseException if any plugin is not a valid plugin
95 * @since 2.3.0
96 */
97 Set<String> installPlugins(PluginArtifact... pluginArtifacts) throws PluginParseException;
98
99 /**
100 * Uninstall the plugin, disabling it first.
101 *
102 * @param plugin The plugin.
103 * @throws PluginException if there was some problem uninstalling the plugin.
104 */
105 void uninstall(Plugin plugin) throws PluginException;
106
107 /**
108 * Uninstall multiple plugin, disabling it first.
109 *
110 * @param plugins The plugins to uninstall.
111 * @throws PluginException if there was some problem uninstalling a plugin.
112 */
113 default void uninstallPlugins(Collection<Plugin> plugins) throws PluginException {
114 LoggerFactory.getLogger(PluginController.class).warn("Naive uninstallPlugins implementation. Please upgrade plugin framework.");
115 plugins.stream().forEach(this::uninstall);
116 }
117
118 /**
119 * Restores the state of any plugin requiring a restart that had been removed, upgraded, or installed. If marked
120 * as removed, the mark will be deleted. If marked as upgrade, an attempt to restore the original plugin artifact
121 * will be made. If marked as install, the artifact will be deleted.
122 *
123 * @param pluginKey The plugin key
124 * @throws PluginException if there was some problem reverting the plugin state.
125 * @throws IllegalArgumentException if the plugin key is null or cannot be resolved to a plugin
126 * @since 2.5.0
127 */
128 void revertRestartRequiredChange(String pluginKey) throws PluginException;
129
130 /**
131 * Search all loaders and add any new plugins you find.
132 *
133 * @return The number of new plugins found.
134 */
135 int scanForNewPlugins() throws PluginParseException;
136
137 /**
138 * Add a new module described by <code>element</code> to the plugin specified.
139 * <p>
140 * Module will be enabled if the following conditions are met:
141 * <ul>
142 * <li>{@link ModuleDescriptor#isEnabledByDefault()} returns <code>true</code></li>
143 * <li>This module has not been marked as disabled elsewhere, e.g. by user</li>
144 * </ul>
145 *
146 * @param plugin to add the module to
147 * @param module to add
148 * @return added module
149 * @see com.atlassian.plugin.PluginController#removeDynamicModule(Plugin, ModuleDescriptor)
150 * @see com.atlassian.plugin.PluginAccessor#getDynamicModules(Plugin)
151 * @since 4.0.0
152 */
153 ModuleDescriptor<?> addDynamicModule(Plugin plugin, Element module);
154
155 /**
156 * Remove a module that was dynamically added to plugin..
157 *
158 * @param plugin to remove the module from
159 * @param module to remove
160 * @see com.atlassian.plugin.PluginController#addDynamicModule(Plugin, org.dom4j.Element)
161 * @see com.atlassian.plugin.PluginAccessor#getDynamicModules(Plugin)
162 */
163 void removeDynamicModule(Plugin plugin, ModuleDescriptor<?> module);
164 }