1 package com.atlassian.plugin;
2
3 import java.util.Set;
4
5 /**
6 * Interface to control the state of the plugin system
7 */
8 public interface PluginController
9 {
10 /**
11 * Enable a plugin by key.
12 * @param key The plugin key.
13 * @deprecated since 2.5.0, use {#link enablePlugins(String... keys)} instead
14 */
15 void enablePlugin(String key);
16
17 /**
18 * Enable a set of plugins by key. This will implicitly and recursively enable all dependent plugins
19 * @param keys The plugin keys. Must not be null.
20 * @since 2.5.0
21 */
22 void enablePlugins(String... keys);
23
24 /**
25 * Disables the plugin with the given key.
26 *
27 * <p>Calling this method will persist the disabled state so that the plugin will also be disabled on next startup.
28 * This would normally be used when a user manually disables a plugin.
29 *
30 * <p>If you extend DefaultPluginManager and override this method, you will also need to override {@link #disablePluginWithoutPersisting(String)}.
31 *
32 * @param key The plugin key.
33 * @see #disablePluginWithoutPersisting(String)
34 */
35 void disablePlugin(String key);
36
37 /**
38 * Disables the plugin with the given key without persisting the disabled state.
39 *
40 * <p>Calling this method will NOT persist the disabled state so that the framework will try to enable the plugin on next startup.
41 * This is used when a plugin has errors on startup.
42 *
43 * <p>If you extend DefaultPluginManager and override {@link #disablePlugin(String)}, you will also need to override this method.
44 *
45 * @param key The plugin key.
46 * @see #disablePlugin(String)
47 * @since 2.3.0
48 */
49 void disablePluginWithoutPersisting(String key);
50
51 /**
52 * Enable a plugin module by key.
53 * @param completeKey The "complete key" of the plugin module.
54 */
55 void enablePluginModule(String completeKey);
56
57 /**
58 * Disable a plugin module by key.
59 * @param completeKey The "complete key" of the plugin module.
60 */
61 void disablePluginModule(String completeKey);
62
63 /**
64 * Installs a plugin and returns the plugin key
65 * @param pluginArtifact The plugin artifact to install
66 * @throws com.atlassian.plugin.PluginParseException if the plugin is not a valid plugin
67 * @return The plugin key
68 * @deprecated Since 2.3.0, use {@link #installPlugins(PluginArtifact...)} instead
69 */
70 String installPlugin(PluginArtifact pluginArtifact) throws PluginParseException;
71
72 /**
73 * Installs multiple plugins and returns the list of plugin keys. All plugin artifacts must be for valid plugins
74 * or none will be installed.
75 *
76 * @param pluginArtifacts The list of plugin artifacts to install
77 * @return A list of plugin keys
78 * @throws com.atlassian.plugin.PluginParseException if any plugin is not a valid plugin
79 * @since 2.3.0
80 */
81 Set<String> installPlugins(PluginArtifact... pluginArtifacts) throws PluginParseException;
82
83 /**
84 * Uninstall the plugin, disabling it first.
85 * @param plugin The plugin.
86 * @throws PluginException if there was some problem uninstalling the plugin.
87 */
88 void uninstall(Plugin plugin) throws PluginException;
89
90 /**
91 * Restores the state of any plugin requiring a restart that had been removed, upgraded, or installed. If marked
92 * as removed, the mark will be deleted. If marked as upgrade, an attempt to restore the original plugin artifact
93 * will be made. If marked as install, the artifact will be deleted.
94 *
95 * @param pluginKey The plugin key
96 * @throws PluginException if there was some problem reverting the plugin state.
97 * @throws IllegalArgumentException if the plugin key is null or cannot be resolved to a plugin
98 * @since 2.5.0
99 */
100 void revertRestartRequiredChange(String pluginKey) throws PluginException;
101
102 /**
103 * Search all loaders and add any new plugins you find.
104 * @return The number of new plugins found.
105 */
106 int scanForNewPlugins() throws PluginParseException;
107 }