1 package com.atlassian.plugin;
2
3 import java.io.InputStream;
4 import java.net.URL;
5 import java.util.Collection;
6 import java.util.Comparator;
7 import java.util.Date;
8 import java.util.List;
9
10 public interface Plugin extends Resourced, Comparable<Plugin>
11 {
12 public static final Comparator<Plugin> NAME_COMPARATOR = new PluginNameComparator();
13
14 /**
15 * Gets the version of the plugins system to handle this plugin
16 * @return The plugins version. If undefined, assumed to be 1.
17 */
18 int getPluginsVersion();
19
20 /**
21 * Sets the version of the plugins system
22 * @param version The version
23 */
24 void setPluginsVersion(int version);
25
26 String getName();
27
28 void setName(String name);
29
30 String getI18nNameKey();
31
32 void setI18nNameKey(String i18nNameKey);
33
34 String getKey();
35
36 void setKey(String aPackage);
37
38 void addModuleDescriptor(ModuleDescriptor<?> moduleDescriptor);
39
40 /**
41 * Get the {@link Collection} of {@link ModuleDescriptor descriptors}. The iteration order of the collection is
42 * the order that the modules will be enabled, and should be the same order that the modules appear in the
43 * plugin descriptor.
44 *
45 * @return the modules contained by this plugin in the order they are to be enabled
46 */
47 Collection<ModuleDescriptor<?>> getModuleDescriptors();
48
49 /**
50 * Get the {@link ModuleDescriptor} for a particular key. Returns <tt>null</tt> if the plugin does not exist.
51 * <p>
52 * Note: The {@link ModuleDescriptor#getModule()} may throw {@link ClassCastException} if the expected type is incorrect.
53 *
54 * @param key the {@link String} complete key of the module, in the form "org.example.plugin:module-key".
55 * @return the {@link ModuleDescriptor} of the expected type.
56 */
57 ModuleDescriptor<?> getModuleDescriptor(String key);
58
59 /**
60 * Get the {@link ModuleDescriptor descriptors} whose module class implements or is assignable from the supplied {@link Class}.
61 * <p>
62 * Note: The {@link ModuleDescriptor#getModule()} may throw {@link ClassCastException} if the expected type is incorrect.
63 * Normally this method would not be supplied with anything other than {@link Object} or <?>, unless you are
64 * confident in the super type of the module classes this {@link Plugin} provides.
65 *
66 * @param <M> The expected module type of the returned {@link ModuleDescriptor descriptors}.
67 * @param moduleClass the {@link Class super class} the {@link ModuleDescriptor descriptors} return.
68 * @return the {@link List} of {@link ModuleDescriptor descriptors} of the expected type.
69 */
70 <M> List<ModuleDescriptor<M>> getModuleDescriptorsByModuleClass(Class<M> moduleClass);
71
72 boolean isEnabledByDefault();
73
74 void setEnabledByDefault(boolean enabledByDefault);
75
76 PluginInformation getPluginInformation();
77
78 void setPluginInformation(PluginInformation pluginInformation);
79
80 void setResources(Resourced resources);
81
82 /**
83 * @return the current state of the plugin
84 * @since 2.2.0
85 */
86 PluginState getPluginState();
87
88 /**
89 * @deprecated since 2.2.0, use {@link #getPluginState()} instead
90 * @return
91 */
92 boolean isEnabled();
93
94 void setEnabled(boolean enabled);
95
96 /**
97 * Whether the plugin is a "system" plugin that shouldn't be made visible to the user
98 */
99 boolean isSystemPlugin();
100
101 boolean containsSystemModule();
102
103 void setSystemPlugin(boolean system);
104
105 /**
106 * Whether the plugin is a "bundled" plugin that can't be removed.
107 */
108 boolean isBundledPlugin();
109
110 /**
111 * The date this plugin was loaded into the system.
112 */
113 Date getDateLoaded();
114
115 /**
116 * Whether or not this plugin can be 'uninstalled'.
117 */
118 boolean isUninstallable();
119
120 /**
121 * Should the plugin file be deleted on unistall?
122 */
123 boolean isDeleteable();
124
125 /**
126 * Whether or not this plugin is loaded dynamically at runtime
127 */
128 boolean isDynamicallyLoaded();
129
130 /**
131 * Get the plugin to load a specific class.
132 *
133 * @param clazz The name of the class to be loaded
134 * @param callingClass The class calling the loading (used to help find a classloader)
135 * @return The loaded class.
136 * @throws ClassNotFoundException
137 */
138 <T> Class<T> loadClass(String clazz, Class<?> callingClass) throws ClassNotFoundException;
139
140 /**
141 * Get the classloader for the plugin.
142 *
143 * @return The classloader used to load classes for this plugin
144 */
145 ClassLoader getClassLoader();
146
147 /**
148 * Retrieve the URL of the resource from the plugin.
149 *
150 * @param path the name of the resource to be loaded
151 * @return The URL to the resource, or null if the resource is not found
152 */
153 URL getResource(String path);
154
155 /**
156 * Load a given resource from the plugin. Plugins that are loaded dynamically will need
157 * to implement this in a way that loads the resource from the same context as the plugin.
158 * Static plugins can just pull them from their own classloader.
159 *
160 * @param name The name of the resource to be loaded.
161 * @return An InputStream for the resource, or null if the resource is not found.
162 */
163 InputStream getResourceAsStream(String name);
164
165 /**
166 * Free any resources held by this plugin. To be called during uninstallation of the {@link Plugin}.
167 */
168 void close();
169 }