1 package com.atlassian.plugin;
2
3 import org.dom4j.Element;
4
5 import java.util.Map;
6
7 public interface ModuleDescriptor<T> extends Resourced
8 {
9 /**
10 * The complete key for this module, including the plugin key.
11 * <p>
12 * Format is plugin.key:module.key
13 * </p>
14 *
15 * @return The complete key for this module.
16 * @see #getKey()
17 * @see #getPluginKey()
18 */
19 String getCompleteKey();
20
21 /**
22 * The plugin key for this module, derived from the complete key.
23 *
24 * @return The plugin key for this module.
25 * @see #getKey()
26 * @see #getCompleteKey()
27 */
28 String getPluginKey();
29
30 /**
31 * The key for this module, unique within the plugin.
32 *
33 * @return The key for this module.
34 * @see #getCompleteKey()
35 * @see #getPluginKey()
36 */
37 String getKey();
38
39 /**
40 * A simple string name for this descriptor.
41 *
42 * @return The name for this ModuleDescriptor.
43 */
44 String getName();
45
46 /**
47 * A simple description of this descriptor.
48 *
49 * @return The description for this ModuleDescriptor.
50 */
51 String getDescription();
52
53 /**
54 * The class of the module this descriptor creates.
55 *
56 * @return The class of the module this descriptor creates.
57 * @see #getModule()
58 */
59 Class<T> getModuleClass();
60
61 /**
62 * The particular module object created by this plugin.
63 *
64 * @return The module object created by this plugin.
65 * @see #getModuleClass()
66 */
67 T getModule();
68
69 /**
70 * Initialise a module given it's parent plugin and the XML element representing the module.
71 *
72 * <p> Since atlassian-plugins v2.2, you can no longer load classes from the plugin in this method, because the OSGi
73 * bundle that they will live in is not built yet.
74 * Load classes in the {@link com.atlassian.plugin.descriptors.AbstractModuleDescriptor#enabled()} method instead.
75 *
76 * @param plugin The plugin that the module belongs to.
77 * @param element XML element representing the module.
78 * @throws PluginParseException Can be thrown if an error occurs while parsing the XML element.
79 */
80 void init(Plugin plugin, Element element) throws PluginParseException;
81
82 /**
83 * Whether or not this plugin module is enabled by default.
84 * @return {@code true} if this plugin module is enabled by default.
85 */
86 boolean isEnabledByDefault();
87
88 /**
89 * Whether or not this plugin module is a "system" plugin that shouldn't be made visible/disableable to the user.
90 * @return {@code true} if this plugin module is a "system" plugin that shouldn't be made visible/disableable to the user.
91 */
92 boolean isSystemModule();
93
94 /**
95 * Override this if your plugin needs to clean up when it's been removed.
96 * @param plugin
97 * TODO: The plugin parameter is redundant. The ModuleDescriptor must know its parent plugin in order to implement getPlugin()
98 */
99 void destroy(Plugin plugin);
100
101 Float getMinJavaVersion();
102
103 /**
104 * If a min java version has been specified this will return true if the running jvm
105 * is >= to the specified version. If this is not set then it is treated as not having
106 * a preference.
107 *
108 * @return true if satisfied, false otherwise.
109 */
110 boolean satisfiesMinJavaVersion();
111
112 Map<String, String> getParams();
113
114 /**
115 * Key used to override {@link #getName()} when using internationalisation.
116 *
117 * @return the i18n key. May be null.
118 */
119 String getI18nNameKey();
120
121 /**
122 * Key used to override {@link #getDescription()} when using internationalisation.
123 *
124 * @return the i18n key. May be null.
125 */
126 String getDescriptionKey();
127
128 /**
129 * @return The plugin this module descriptor is associated with
130 */
131 Plugin getPlugin();
132 }