1 package com.atlassian.plugin;
2
3 import java.io.InputStream;
4 import java.net.URL;
5 import java.util.*;
6
7 public interface Plugin extends Resourced, Comparable<Plugin>
8 {
9 /**
10 * @deprecated since 2.2.0. This comparator only takes into account the plugin name and assumes it is not null,
11 * yet a) that constraint is not validated anywhere in plugin loading and b) the plugin could have used the i18n
12 * name, and only the application can resolve that to a name useful for comparisons.
13 */
14 public static final Comparator<Plugin> NAME_COMPARATOR = new PluginNameComparator();
15
16 /**
17 * Gets the version of the plugins system to handle this plugin
18 * @return The plugins version. If undefined, assumed to be 1.
19 */
20 int getPluginsVersion();
21
22 /**
23 * Sets the version of the plugins system
24 * @param version The version
25 */
26 void setPluginsVersion(int version);
27
28 /**
29 * Returns the non-localised name of this plugin if defined.
30 *
31 * <p> This corresponds to the value of the {@code name} field in the plugin's XML configuration file.
32 *
33 * <p> You would expect a plugin developer to fill in one of either {@code name}, or {@code i18n-name-key},
34 * but the framework does no validation and makes no guarantees that this is the case.
35 *
36 * @return the non-localised name of this plugin if defined, or null.
37 * @see #getI18nNameKey()
38 */
39 String getName();
40
41 /**
42 * Sets the non-localised name of this plugin.
43 *
44 * @param name the name.
45 * @see #getName()
46 */
47 void setName(String name);
48
49 /**
50 * Returns the i18nKey used to get an internationalised name for this plugin.
51 *
52 * <p> This corresponds to the value of the {@code i18n-name-key} field in the plugin's XML configuration file.
53 *
54 * <p> You would expect a plugin developer to fill in one of either {@code name}, or {@code i18n-name-key},
55 * but the framework does no validation and makes no guarantees that this is the case.
56 *
57 * @return the i18n Name Key for this plugin if defined, or null.
58 * @see #getName()
59 */
60 String getI18nNameKey();
61
62 /**
63 * Sets the i18nKey used to get an internationalised name for this plugin.
64 *
65 * @param i18nNameKey the i18n Name Key.
66 * @see #getI18nNameKey()
67 */
68 void setI18nNameKey(String i18nNameKey);
69
70 String getKey();
71
72 void setKey(String aPackage);
73
74 void addModuleDescriptor(ModuleDescriptor<?> moduleDescriptor);
75
76 /**
77 * Get the {@link Collection} of {@link ModuleDescriptor descriptors}.
78 *
79 * <p> The iteration order of the collection is
80 * the order that the modules will be enabled, and should be the same order that the modules appear in the
81 * plugin descriptor.
82 *
83 * @return the modules contained by this plugin in the order they are to be enabled
84 */
85 Collection<ModuleDescriptor<?>> getModuleDescriptors();
86
87 /**
88 * Get the {@link ModuleDescriptor} for a particular key. Returns <tt>null</tt> if the plugin does not exist.
89 * <p>
90 * Note: The {@link ModuleDescriptor#getModule()} may throw {@link ClassCastException} if the expected type is incorrect.
91 *
92 * @param key the {@link String} complete key of the module, in the form "org.example.plugin:module-key".
93 * @return the {@link ModuleDescriptor} of the expected type.
94 */
95 ModuleDescriptor<?> getModuleDescriptor(String key);
96
97 /**
98 * Get the {@link ModuleDescriptor descriptors} whose module class implements or is assignable from the supplied {@link Class}.
99 * <p>
100 * Note: The {@link ModuleDescriptor#getModule()} may throw {@link ClassCastException} if the expected type is incorrect.
101 * Normally this method would not be supplied with anything other than {@link Object} or <?>, unless you are
102 * confident in the super type of the module classes this {@link Plugin} provides.
103 *
104 * @param <M> The expected module type of the returned {@link ModuleDescriptor descriptors}.
105 * @param moduleClass the {@link Class super class} the {@link ModuleDescriptor descriptors} return.
106 * @return the {@link List} of {@link ModuleDescriptor descriptors} of the expected type.
107 */
108 <M> List<ModuleDescriptor<M>> getModuleDescriptorsByModuleClass(Class<M> moduleClass);
109
110 boolean isEnabledByDefault();
111
112 void setEnabledByDefault(boolean enabledByDefault);
113
114 PluginInformation getPluginInformation();
115
116 void setPluginInformation(PluginInformation pluginInformation);
117
118 void setResources(Resourced resources);
119
120 /**
121 * Returns this plugin's current state.
122 *
123 * @return the current state of the plugin.
124 * @since 2.2.0
125 */
126 PluginState getPluginState();
127
128 /**
129 * @deprecated since 2.2.0, use {@link #getPluginState()} instead
130 * @return {@code true} if this plugin is enabled.
131 */
132 boolean isEnabled();
133
134
135 /**
136 * Whether the plugin is a "system" plugin that shouldn't be made visible to the user.
137 *
138 * @return {@code true} if this plugin is a "system" plugin.
139 * @deprecated since 2.6.0 use {@link com.atlassian.plugin.metadata.PluginMetadataManager#isSystemProvided(Plugin)}}
140 * instead.
141 */
142 boolean isSystemPlugin();
143
144 /**
145 * @param system whether the plugin is a "system" plugin that shouldn't be made visible to the user.
146 * @deprecated since 2.6.0 provide {@link com.atlassian.plugin.metadata.PluginMetadataManager} with information about the
147 * plugin instead. There is no way to programatically set this value now.
148 */
149 void setSystemPlugin(boolean system);
150
151 boolean containsSystemModule();
152
153 /**
154 * Whether the plugin is a "bundled" plugin that can't be removed.
155 *
156 * @return {@code true} if this plugin is a "bundled" plugin.
157 */
158 boolean isBundledPlugin();
159
160 /**
161 * The date this plugin was loaded into the system.
162 *
163 * @return The date this plugin was loaded into the system.
164 */
165 Date getDateLoaded();
166
167 /**
168 * Whether or not this plugin can be 'uninstalled'.
169 *
170 * @return {@code true} if this plugin can be 'uninstalled'.
171 */
172 boolean isUninstallable();
173
174 /**
175 * Should the plugin file be deleted on unistall?
176 *
177 * @return {@code true} if this plugin file should be deleted on unistall.
178 */
179 boolean isDeleteable();
180
181 /**
182 * Whether or not this plugin is loaded dynamically at runtime.
183 *
184 * @return {@code true} if this plugin is loaded dynamically at runtime.
185 */
186 boolean isDynamicallyLoaded();
187
188 /**
189 * Get the plugin to load a specific class.
190 *
191 * @param clazz The name of the class to be loaded
192 * @param callingClass The class calling the loading (used to help find a classloader)
193 * @return The loaded class.
194 * @throws ClassNotFoundException if the class cannot be located.
195 */
196 <T> Class<T> loadClass(String clazz, Class<?> callingClass) throws ClassNotFoundException;
197
198 /**
199 * Get the classloader for the plugin.
200 *
201 * @return The classloader used to load classes for this plugin
202 */
203 ClassLoader getClassLoader();
204
205 /**
206 * Retrieve the URL of the resource from the plugin.
207 *
208 * @param path the name of the resource to be loaded
209 * @return The URL to the resource, or null if the resource is not found
210 */
211 URL getResource(String path);
212
213 /**
214 * Load a given resource from the plugin. Plugins that are loaded dynamically will need
215 * to implement this in a way that loads the resource from the same context as the plugin.
216 * Static plugins can just pull them from their own classloader.
217 *
218 * @param name The name of the resource to be loaded.
219 * @return An InputStream for the resource, or null if the resource is not found.
220 */
221 InputStream getResourceAsStream(String name);
222
223 /**
224 * @param enabled new enabled state
225 * @deprecated Since 2.2.0, use {@link #enable()} or {@link #disable()} instead
226 */
227 void setEnabled(boolean enabled);
228
229 /**
230 * Free any resources held by this plugin. To be called during uninstallation of the {@link Plugin}.
231 * @deprecated Since 2.2.0, use {@link #uninstall()} instead
232 */
233 void close();
234
235 /**
236 * Installs the plugin into any internal, managing container. This method will be called on every startup. Unless
237 * an exception is thrown, the plugin should be in the {@link PluginState#INSTALLED} state. If the plugin is already
238 * in the {@link PluginState#INSTALLED} state, nothing will happen.
239 *
240 * @since 2.2.0
241 * @throws PluginException If the plugin could not be installed
242 */
243 void install() throws PluginException;
244
245 /**
246 * Uninstalls the plugin from any internal container. This method will be called on every shutdown. Unless an
247 * exception is thrown, the plugin should be in the {@link PluginState#UNINSTALLED} state. If the plugin is already
248 * in the {@link PluginState#UNINSTALLED} state, nothing will happen.
249 *
250 * @since 2.2.0
251 * @throws PluginException If the plugin could not be uninstalled
252 */
253 void uninstall() throws PluginException;
254
255 /**
256 * Enables the plugin. Unless an exception is thrown, the plugin should then be in either the
257 * {@link PluginState#ENABLING} or {@link PluginState#ENABLED} state. If the plugin is already in the
258 * {@link PluginState#ENABLING} or {@link PluginState#ENABLED} state, nothing will happen.
259 *
260 *
261 * @since 2.2.0
262 * @throws PluginException If the plugin could not be enabled
263 */
264 void enable() throws PluginException;
265
266 /**
267 * Disables the plugin. Unless an exception is thrown, the plugin should be in the {@link PluginState#DISABLED}
268 * state. If the plugin is already in the {@link PluginState#DISABLED} state, nothing will happen.
269 *
270 * @since 2.2.0 If the plugin could not be disabled
271 * @throws PluginException If the plugin could not be disabled
272 */
273 void disable() throws PluginException;
274
275 /**
276 * @return A list of plugin keys that this plugin is dependent upon, or an empty list if none
277 * @since 2.2.0
278 */
279 Set<String> getRequiredPlugins();
280
281 /**
282 * @return the list of permissions currently valid for the plugin
283 * @since 2.14
284 */
285 Set<String> getPermissions();
286 }