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