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 import java.util.function.Predicate;
10
11 /**
12 * Allows access to the current plugin system state
13 */
14 public interface PluginAccessor {
15 /**
16 * The plugin descriptor file.
17 *
18 * @since 2.2
19 */
20 final class Descriptor {
21 /**
22 * The default filename.
23 */
24 public static final String FILENAME = "atlassian-plugin.xml";
25
26 private Descriptor() {
27 }
28 }
29
30 /**
31 * Gets all of the currently installed plugins.
32 *
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 *
40 * @param pluginPredicate the {@link PluginPredicate} to match.
41 * @return a collection of {@link Plugin}s that match the given predicate.
42 * @since 0.17
43 * @deprecated in 5.0 for removal in 6.0, use {@link #getPlugins(Predicate)} instead
44 */
45 @Deprecated
46 default Collection<Plugin> getPlugins(final PluginPredicate pluginPredicate) {
47 return getPlugins((Predicate<Plugin>) pluginPredicate::matches);
48 }
49
50 /**
51 * Gets all installed plugins that match the given predicate.
52 *
53 * @param pluginPredicate the {@link Predicate} describing which plugins to match.
54 * @return a collection of {@link Plugin}s that match the given predicate.
55 * @since 5.0
56 */
57 Collection<Plugin> getPlugins(Predicate<Plugin> pluginPredicate);
58
59 /**
60 * Get all of the currently enabled plugins.
61 *
62 * @return a collection of installed and enabled {@link Plugin}s.
63 */
64 Collection<Plugin> getEnabledPlugins();
65
66 /**
67 * Gets all installed modules that match the given predicate.
68 *
69 * @param moduleDescriptorPredicate the {@link com.atlassian.plugin.predicate.ModuleDescriptorPredicate} to match.
70 * @return a collection of modules as per {@link ModuleDescriptor#getModule()} that match the given predicate.
71 * @since 0.17
72 * @deprecated in 5.0 for removal in 6.0. Use {@link #getModules(Predicate)} instead.
73 */
74 @Deprecated
75 default <M> Collection<M> getModules(final ModuleDescriptorPredicate<M> moduleDescriptorPredicate) {
76 return getModules((Predicate<ModuleDescriptor<M>>) moduleDescriptorPredicate::matches);
77 }
78
79 /**
80 * Gets all module descriptors of installed modules that match the given predicate.
81 *
82 * @param moduleDescriptorPredicate the {@link com.atlassian.plugin.predicate.ModuleDescriptorPredicate} to match.
83 * @return a collection of {@link ModuleDescriptor}s that match the given predicate.
84 * @since 0.17
85 * @deprecated in 5.0 for removal in 6.0. Use {@link #getModuleDescriptors(Predicate)} instead.
86 */
87 @Deprecated
88 default <M> Collection<ModuleDescriptor<M>> getModuleDescriptors(final ModuleDescriptorPredicate<M> moduleDescriptorPredicate) {
89 return getModuleDescriptors((Predicate<ModuleDescriptor<M>>) moduleDescriptorPredicate::matches);
90 }
91
92 /**
93 * Gets all installed modules that match the given predicate.
94 *
95 * @param moduleDescriptorPredicate describes which modules to match
96 * @return a collection of modules as per {@link ModuleDescriptor#getModule()} that match the given predicate.
97 * @since 5.0
98 */
99 <M> Collection<M> getModules(Predicate<ModuleDescriptor<M>> moduleDescriptorPredicate);
100
101 /**
102 * Gets all module descriptors of installed modules that match the given predicate.
103 *
104 * @param moduleDescriptorPredicate describes which modules to match
105 * @return a collection of {@link ModuleDescriptor}s that match the given predicate.
106 * @since 5.0
107 */
108 <M> Collection<ModuleDescriptor<M>> getModuleDescriptors(Predicate<ModuleDescriptor<M>> moduleDescriptorPredicate);
109
110 /**
111 * Retrieve a given plugin (whether enabled or not).
112 *
113 * @param key The plugin key. Cannot be null.
114 * @return The enabled plugin, or null if that plugin does not exist.
115 * @throws IllegalArgumentException If the plugin key is null
116 */
117 Plugin getPlugin(String key) throws IllegalArgumentException;
118
119 /**
120 * Retrieve a given plugin if it is enabled.
121 *
122 * @return The enabled plugin, or null if that plugin does not exist or is disabled.
123 * @throws IllegalArgumentException If the plugin key is null
124 */
125 Plugin getEnabledPlugin(String pluginKey) throws IllegalArgumentException;
126
127 /**
128 * Retrieve any plugin module by complete module key.
129 * <p>
130 * Note: the module may or may not be disabled.
131 */
132 ModuleDescriptor<?> getPluginModule(String completeKey);
133
134 /**
135 * Retrieve an enabled plugin module by complete module key.
136 */
137 ModuleDescriptor<?> getEnabledPluginModule(String completeKey);
138
139 /**
140 * Whether or not a given plugin is currently enabled.
141 *
142 * @throws IllegalArgumentException If the plugin key is null
143 */
144 boolean isPluginEnabled(String key) throws IllegalArgumentException;
145
146 /**
147 * Whether or not a given plugin module is currently enabled. This also checks
148 * if the plugin it is contained within is enabled also
149 *
150 * @see #isPluginEnabled(String)
151 */
152 boolean isPluginModuleEnabled(String completeKey);
153
154 /**
155 * Retrieve all plugin modules that implement or extend a specific class.
156 *
157 * @return List of modules that implement or extend the given class.
158 */
159 <M> List<M> getEnabledModulesByClass(Class<M> moduleClass);
160
161 /**
162 * Get all enabled module descriptors that have a specific descriptor class.
163 *
164 * @param descriptorClazz module descriptor class
165 * @return List of {@link ModuleDescriptor}s that implement or extend the given class.
166 */
167 <D extends ModuleDescriptor<?>> List<D> getEnabledModuleDescriptorsByClass(Class<D> descriptorClazz);
168
169 /**
170 * Get all enabled module descriptors that have a specific descriptor class and are considered active for
171 * the current request.
172 *<p>
173 * Result of this method should not be cached across requests.
174 *
175 * @see com.atlassian.plugin.scope.ScopeManager
176 * @param descriptorClazz module descriptor class
177 * @return List of {@link ModuleDescriptor}s that implement or extend the given class and active for the current request.
178 * @deprecated in 5.0 for removal in 6.0 when {@link com.atlassian.plugin.scope.ScopeManager} is removed. Use
179 * {@link #getEnabledModuleDescriptorsByClass(Class)} instead.
180 */
181 @Deprecated
182 default <D extends ModuleDescriptor<?>> List<D> getActiveModuleDescriptorsByClass(Class<D> descriptorClazz) {
183 return getEnabledModuleDescriptorsByClass(descriptorClazz);
184 }
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 erratically.
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 the class loader responsible for loading classes and resources from plugins.
197 *
198 * @return the class loader
199 * @since 0.21
200 */
201 ClassLoader getClassLoader();
202
203 /**
204 * @return true if the plugin is a system plugin.
205 */
206 boolean isSystemPlugin(String key);
207
208 /**
209 * Gets the state of the plugin upon restart. Only useful for plugins that contain module descriptors with the
210 * \@RestartRequired annotation, and therefore, cannot be dynamically installed, upgraded, or removed at runtime
211 *
212 * @param key The plugin key
213 * @return The state of the plugin on restart
214 */
215 PluginRestartState getPluginRestartState(String key);
216
217 /**
218 * Retrieve all currently registered dynamic modules i.e. any module that has been added to <code>plugin</code> via
219 * {@link com.atlassian.plugin.PluginController#addDynamicModule(Plugin, org.dom4j.Element)} during the lifetime of
220 * this plugin, but not removed via {@link com.atlassian.plugin.PluginController#removeDynamicModule(Plugin, ModuleDescriptor)}.
221 *
222 * @param plugin to query
223 * @return modules added, may be empty
224 * @see com.atlassian.plugin.PluginController#addDynamicModule(Plugin, org.dom4j.Element)
225 * @see com.atlassian.plugin.PluginController#removeDynamicModule(Plugin, ModuleDescriptor)
226 */
227 Iterable<ModuleDescriptor<?>> getDynamicModules(Plugin plugin);
228 }