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