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