1 package com.atlassian.plugin;
2
3 import com.atlassian.plugin.predicate.ModuleDescriptorPredicate;
4 import com.atlassian.plugin.predicate.PluginPredicate;
5
6 import java.io.InputStream;
7 import java.util.Collection;
8 import java.util.List;
9
10 /**
11 * Allows access to the current plugin system state
12 */
13 public interface PluginAccessor {
14 /**
15 * The plugin descriptor file.
16 *
17 * @since 2.2
18 */
19 public static final class Descriptor {
20 /**
21 * The default filename.
22 */
23 public static final String FILENAME = "atlassian-plugin.xml";
24
25 private Descriptor() {
26 }
27 }
28
29 /**
30 * Gets all of the currently installed plugins.
31 *
32 * @return a collection of installed {@link Plugin}s.
33 */
34 Collection<Plugin> getPlugins();
35
36 /**
37 * Gets all installed plugins that match the given predicate.
38 *
39 * @param pluginPredicate the {@link PluginPredicate} to match.
40 * @return a collection of {@link Plugin}s that match the given predicate.
41 * @since 0.17
42 */
43 Collection<Plugin> getPlugins(final PluginPredicate pluginPredicate);
44
45 /**
46 * Get all of the currently enabled plugins.
47 *
48 * @return a collection of installed and enabled {@link Plugin}s.
49 */
50 Collection<Plugin> getEnabledPlugins();
51
52 /**
53 * Gets all installed modules that match the given predicate.
54 *
55 * @param moduleDescriptorPredicate the {@link com.atlassian.plugin.predicate.ModuleDescriptorPredicate} to match.
56 * @return a collection of modules as per {@link ModuleDescriptor#getModule()} that match the given predicate.
57 * @since 0.17
58 */
59 <M> Collection<M> getModules(final ModuleDescriptorPredicate<M> moduleDescriptorPredicate);
60
61 /**
62 * Gets all module descriptors of installed modules that match the given predicate.
63 *
64 * @param moduleDescriptorPredicate the {@link com.atlassian.plugin.predicate.ModuleDescriptorPredicate} to match.
65 * @return a collection of {@link ModuleDescriptor}s that match the given predicate.
66 * @since 0.17
67 */
68 <M> Collection<ModuleDescriptor<M>> getModuleDescriptors(final ModuleDescriptorPredicate<M> moduleDescriptorPredicate);
69
70 /**
71 * Retrieve a given plugin (whether enabled or not).
72 *
73 * @param key The plugin key. Cannot be null.
74 * @return The enabled plugin, or null if that plugin does not exist.
75 * @throws IllegalArgumentException If the plugin key is null
76 */
77 Plugin getPlugin(String key) throws IllegalArgumentException;
78
79 /**
80 * Retrieve a given plugin if it is enabled.
81 *
82 * @return The enabled plugin, or null if that plugin does not exist or is disabled.
83 * @throws IllegalArgumentException If the plugin key is null
84 */
85 Plugin getEnabledPlugin(String pluginKey) throws IllegalArgumentException;
86
87 /**
88 * Retrieve any plugin module by complete module key.
89 * <p>
90 * Note: the module may or may not be disabled.
91 */
92 ModuleDescriptor<?> getPluginModule(String completeKey);
93
94 /**
95 * Retrieve an enabled plugin module by complete module key.
96 */
97 ModuleDescriptor<?> getEnabledPluginModule(String completeKey);
98
99 /**
100 * Whether or not a given plugin is currently enabled.
101 *
102 * @throws IllegalArgumentException If the plugin key is null
103 */
104 boolean isPluginEnabled(String key) throws IllegalArgumentException;
105
106 /**
107 * Whether or not a given plugin module is currently enabled. This also checks
108 * if the plugin it is contained within is enabled also
109 *
110 * @see #isPluginEnabled(String)
111 */
112 boolean isPluginModuleEnabled(String completeKey);
113
114 /**
115 * Retrieve all plugin modules that implement or extend a specific class.
116 *
117 * @return List of modules that implement or extend the given class.
118 */
119 <M> List<M> getEnabledModulesByClass(Class<M> moduleClass);
120
121 /**
122 * Retrieve all plugin modules that implement or extend a specific class, and has a descriptor class
123 * as one of descriptorClazz
124 *
125 * @param descriptorClazz @Nonnull
126 * @param moduleClass @Nonnull
127 * @return List of modules that implement or extend the given class. Empty list if none found
128 * @deprecated since 0.17, use {@link #getModules(com.atlassian.plugin.predicate.ModuleDescriptorPredicate)} with an appropriate predicate instead.
129 */
130 @Deprecated
131 <M> List<M> getEnabledModulesByClassAndDescriptor(Class<ModuleDescriptor<M>>[] descriptorClazz, Class<M> moduleClass);
132
133 /**
134 * Retrieve all plugin modules that implement or extend a specific class, and has a descriptor class
135 * as the descriptorClazz
136 *
137 * @param descriptorClass @Nonnull
138 * @param moduleClass @Nonnull
139 * @return List of modules that implement or extend the given class. Empty list if none found
140 * @deprecated since 0.17, use {@link #getModules(com.atlassian.plugin.predicate.ModuleDescriptorPredicate)} with an appropriate predicate instead.
141 */
142 @Deprecated
143 <M> List<M> getEnabledModulesByClassAndDescriptor(final Class<ModuleDescriptor<M>> descriptorClass, final Class<M> moduleClass);
144
145 /**
146 * Get all enabled module descriptors that have a specific descriptor class.
147 *
148 * @param descriptorClazz module descriptor class
149 * @return List of {@link ModuleDescriptor}s that implement or extend the given class.
150 */
151 <D extends ModuleDescriptor<?>> List<D> getEnabledModuleDescriptorsByClass(Class<D> descriptorClazz);
152
153 /**
154 * Get all enabled module descriptors that have a specific descriptor class and are considered active for the current request.
155 *
156 * Result of this method should not be cached across requests.
157 *
158 * @see com.atlassian.plugin.scope.ScopeManager
159 * @param descriptorClazz module descriptor class
160 * @return List of {@link ModuleDescriptor}s that implement or extend the given class and active for the current request.
161 */
162 default <D extends ModuleDescriptor<?>> List<D> getActiveModuleDescriptorsByClass(Class<D> descriptorClazz) {
163 return getEnabledModuleDescriptorsByClass(descriptorClazz);
164 }
165
166 /**
167 * Get all enabled module descriptors that have a specific descriptor class.
168 *
169 * @param descriptorClazz module descriptor class
170 * @param verbose log verbose messages flag
171 * @return List of {@link ModuleDescriptor}s that implement or extend the given class.
172 * @deprecated Since 2.3.0, use {@link #getEnabledModuleDescriptorsByClass(Class<D>)} instead
173 */
174 @Deprecated
175 <D extends ModuleDescriptor<?>> List<D> getEnabledModuleDescriptorsByClass(Class<D> descriptorClazz, boolean verbose);
176
177 /**
178 * Get all enabled module descriptors that have a specific descriptor type.
179 *
180 * @return List of {@link ModuleDescriptor}s that are of a given type.
181 * @deprecated since 0.17, use {@link #getModuleDescriptors(com.atlassian.plugin.predicate.ModuleDescriptorPredicate)} with an appropriate predicate instead.
182 */
183 @Deprecated
184 <M> List<ModuleDescriptor<M>> getEnabledModuleDescriptorsByType(String type) throws PluginParseException;
185
186 /**
187 * Retrieve a resource from a currently loaded (and active) dynamically loaded plugin. Will return the first resource
188 * found, so plugins with overlapping resource names will behave eratically.
189 *
190 * @param resourcePath the path to the resource to retrieve
191 * @return the dynamically loaded resource that matches that path, or null if no such resource is found
192 */
193 InputStream getDynamicResourceAsStream(String resourcePath);
194
195 /**
196 * Retrieve a resource from a currently loaded (and active) plugin. For statically loaded plugins, this just means
197 * pulling the resource from the PluginManager's classloader. For dynamically loaded plugins, this means retrieving
198 * the resource from the plugin's private classloader.
199 *
200 * @deprecated since 0.21 this method is not used, use
201 * {@link #getPlugin(String)}.{@link Plugin#getClassLoader() getClassLoader()}.{@link ClassLoader#getResourceAsStream(String) getResourceAsStream(String)}
202 */
203 @Deprecated
204 InputStream getPluginResourceAsStream(String pluginKey, String resourcePath);
205
206 /**
207 * Retrieve a class from a currently loaded (and active) dynamically loaded plugin. Will return the first class
208 * found, so plugins with overlapping class names will behave eratically.
209 *
210 * @param className the name of the class to retrieve
211 * @return the dynamically loaded class that matches that name
212 * @throws ClassNotFoundException thrown if no classes by that name could be found in any of the enabled dynamic plugins
213 * @deprecated since 0.21 this method is not used, use
214 * {@link #getPlugin(String)}.{@link Plugin#getClassLoader() getClassLoader()}.{@link ClassLoader#loadClass(String) loadClass(String)}
215 */
216 @Deprecated
217 Class<?> getDynamicPluginClass(String className) throws ClassNotFoundException;
218
219 /**
220 * Retrieve the class loader responsible for loading classes and resources from plugins.
221 *
222 * @return the class loader
223 * @since 0.21
224 */
225 ClassLoader getClassLoader();
226
227 /**
228 * @return true if the plugin is a system plugin.
229 */
230 boolean isSystemPlugin(String key);
231
232 /**
233 * Gets the state of the plugin upon restart. Only useful for plugins that contain module descriptors with the
234 * \@RestartRequired annotation, and therefore, cannot be dynamically installed, upgraded, or removed at runtime
235 *
236 * @param key The plugin key
237 * @return The state of the plugin on restart
238 */
239 PluginRestartState getPluginRestartState(String key);
240
241 /**
242 * Retrieve all currently registered dynamic modules i.e. any module that has been added to <code>plugin</code> via
243 * {@link com.atlassian.plugin.PluginController#addDynamicModule(Plugin, org.dom4j.Element)} during the lifetime of
244 * this plugin, but not removed via {@link com.atlassian.plugin.PluginController#removeDynamicModule(Plugin, ModuleDescriptor)}.
245 *
246 * @param plugin to query
247 * @return modules added, may be empty
248 * @see com.atlassian.plugin.PluginController#addDynamicModule(Plugin, org.dom4j.Element)
249 * @see com.atlassian.plugin.PluginController#removeDynamicModule(Plugin, ModuleDescriptor)
250 */
251 Iterable<ModuleDescriptor<?>> getDynamicModules(Plugin plugin);
252 }