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 public static final Comparator<Plugin> NAME_COMPARATOR = new PluginNameComparator();
10
11 /**
12 * Gets the version of the plugins system to handle this plugin
13 * @return The plugins version. If undefined, assumed to be 1.
14 */
15 int getPluginsVersion();
16
17 /**
18 * Sets the version of the plugins system
19 * @param version The version
20 */
21 void setPluginsVersion(int version);
22
23 String getName();
24
25 void setName(String name);
26
27 String getI18nNameKey();
28
29 void setI18nNameKey(String i18nNameKey);
30
31 String getKey();
32
33 void setKey(String aPackage);
34
35 void addModuleDescriptor(ModuleDescriptor<?> moduleDescriptor);
36
37 /**
38 * Get the {@link Collection} of {@link ModuleDescriptor descriptors}. The iteration order of the collection is
39 * the order that the modules will be enabled, and should be the same order that the modules appear in the
40 * plugin descriptor.
41 *
42 * @return the modules contained by this plugin in the order they are to be enabled
43 */
44 Collection<ModuleDescriptor<?>> getModuleDescriptors();
45
46 /**
47 * Get the {@link ModuleDescriptor} for a particular key. Returns <tt>null</tt> if the plugin does not exist.
48 * <p>
49 * Note: The {@link ModuleDescriptor#getModule()} may throw {@link ClassCastException} if the expected type is incorrect.
50 *
51 * @param key the {@link String} complete key of the module, in the form "org.example.plugin:module-key".
52 * @return the {@link ModuleDescriptor} of the expected type.
53 */
54 ModuleDescriptor<?> getModuleDescriptor(String key);
55
56 /**
57 * Get the {@link ModuleDescriptor descriptors} whose module class implements or is assignable from the supplied {@link Class}.
58 * <p>
59 * Note: The {@link ModuleDescriptor#getModule()} may throw {@link ClassCastException} if the expected type is incorrect.
60 * Normally this method would not be supplied with anything other than {@link Object} or <?>, unless you are
61 * confident in the super type of the module classes this {@link Plugin} provides.
62 *
63 * @param <M> The expected module type of the returned {@link ModuleDescriptor descriptors}.
64 * @param moduleClass the {@link Class super class} the {@link ModuleDescriptor descriptors} return.
65 * @return the {@link List} of {@link ModuleDescriptor descriptors} of the expected type.
66 */
67 <M> List<ModuleDescriptor<M>> getModuleDescriptorsByModuleClass(Class<M> moduleClass);
68
69 boolean isEnabledByDefault();
70
71 void setEnabledByDefault(boolean enabledByDefault);
72
73 PluginInformation getPluginInformation();
74
75 void setPluginInformation(PluginInformation pluginInformation);
76
77 void setResources(Resourced resources);
78
79 /**
80 * @return the current state of the plugin
81 * @since 2.2.0
82 */
83 PluginState getPluginState();
84
85 /**
86 * @deprecated since 2.2.0, use {@link #getPluginState()} instead
87 * @return
88 */
89 boolean isEnabled();
90
91
92 /**
93 * Whether the plugin is a "system" plugin that shouldn't be made visible to the user
94 */
95 boolean isSystemPlugin();
96
97 boolean containsSystemModule();
98
99 void setSystemPlugin(boolean system);
100
101 /**
102 * Whether the plugin is a "bundled" plugin that can't be removed.
103 */
104 boolean isBundledPlugin();
105
106 /**
107 * The date this plugin was loaded into the system.
108 */
109 Date getDateLoaded();
110
111 /**
112 * Whether or not this plugin can be 'uninstalled'.
113 */
114 boolean isUninstallable();
115
116 /**
117 * Should the plugin file be deleted on unistall?
118 */
119 boolean isDeleteable();
120
121 /**
122 * Whether or not this plugin is loaded dynamically at runtime
123 */
124 boolean isDynamicallyLoaded();
125
126 /**
127 * Get the plugin to load a specific class.
128 *
129 * @param clazz The name of the class to be loaded
130 * @param callingClass The class calling the loading (used to help find a classloader)
131 * @return The loaded class.
132 * @throws ClassNotFoundException
133 */
134 <T> Class<T> loadClass(String clazz, Class<?> callingClass) throws ClassNotFoundException;
135
136 /**
137 * Get the classloader for the plugin.
138 *
139 * @return The classloader used to load classes for this plugin
140 */
141 ClassLoader getClassLoader();
142
143 /**
144 * Retrieve the URL of the resource from the plugin.
145 *
146 * @param path the name of the resource to be loaded
147 * @return The URL to the resource, or null if the resource is not found
148 */
149 URL getResource(String path);
150
151 /**
152 * Load a given resource from the plugin. Plugins that are loaded dynamically will need
153 * to implement this in a way that loads the resource from the same context as the plugin.
154 * Static plugins can just pull them from their own classloader.
155 *
156 * @param name The name of the resource to be loaded.
157 * @return An InputStream for the resource, or null if the resource is not found.
158 */
159 InputStream getResourceAsStream(String name);
160
161 /**
162 * @deprecated Since 2.2.0, use {@link #enable()} or {@link #disable()} instead
163 */
164 void setEnabled(boolean enabled);
165
166 /**
167 * Free any resources held by this plugin. To be called during uninstallation of the {@link Plugin}.
168 * @deprecated Since 2.2.0, use {@link #uninstall()} instead
169 */
170 void close();
171
172 /**
173 * Installs the plugin into any internal, managing container. This method will be called on every startup. Unless
174 * an exception is thrown, the plugin should be in the {@link PluginState#INSTALLED} state. If the plugin is already
175 * in the {@link PluginState#INSTALLED} state, nothing will happen.
176 *
177 * @since 2.2.0
178 * @throws PluginException If the plugin could not be installed
179 */
180 void install() throws PluginException;
181
182 /**
183 * Uninstalls the plugin from any internal container. This method will be called on every shutdown. Unless an
184 * exception is thrown, the plugin should be in the {@link PluginState#UNINSTALLED} state. If the plugin is already
185 * in the {@link PluginState#UNINSTALLED} state, nothing will happen.
186 *
187 * @since 2.2.0
188 * @throws PluginException If the plugin could not be uninstalled
189 */
190 void uninstall() throws PluginException;
191
192 /**
193 * Enables the plugin. Unless an exception is thrown, the plugin should then be in either the
194 * {@link PluginState#ENABLING} or {@link PluginState#ENABLED} state. If the plugin is already in the
195 * {@link PluginState#ENABLING} or {@link PluginState#ENABLED} state, nothing will happen.
196 *
197 *
198 * @since 2.2.0
199 * @throws PluginException If the plugin could not be enabled
200 */
201 void enable() throws PluginException;
202
203 /**
204 * Disables the plugin. Unless an exception is thrown, the plugin should be in the {@link PluginState#DISABLED}
205 * state. If the plugin is already in the {@link PluginState#DISABLED} state, nothing will happen.
206 *
207 * @since 2.2.0 If the plugin could not be disabled
208 * @throws PluginException
209 */
210 void disable() throws PluginException;
211
212 /**
213 * @return A list of plugin keys that this plugin is dependent upon, or an empty list if none
214 * @since 2.2.0
215 */
216 Set<String> getRequiredPlugins();
217 }