1 package com.atlassian.plugin;
2
3 import com.atlassian.util.concurrent.NotNull;
4 import org.dom4j.Element;
5
6 import java.util.Map;
7
8 public interface ModuleDescriptor<T> extends Resourced
9 {
10 /**
11 * The complete key for this module, including the plugin key.
12 * <p>
13 * Format is plugin.key:module.key
14 * </p>
15 *
16 * @return The complete key for this module.
17 * @see #getKey()
18 * @see #getPluginKey()
19 */
20 String getCompleteKey();
21
22 /**
23 * The plugin key for this module, derived from the complete key.
24 *
25 * @return The plugin key for this module.
26 * @see #getKey()
27 * @see #getCompleteKey()
28 */
29 String getPluginKey();
30
31 /**
32 * The key for this module, unique within the plugin.
33 *
34 * @return The key for this module.
35 * @see #getCompleteKey()
36 * @see #getPluginKey()
37 */
38 String getKey();
39
40 /**
41 * A simple string name for this descriptor.
42 *
43 * @return The name for this ModuleDescriptor.
44 */
45 String getName();
46
47 /**
48 * A simple description of this descriptor.
49 *
50 * @return The description for this ModuleDescriptor.
51 */
52 String getDescription();
53
54 /**
55 * The class of the module this descriptor creates.
56 *
57 * @return The class of the module this descriptor creates.
58 * @see #getModule()
59 */
60 Class<T> getModuleClass();
61
62 /**
63 * The particular module object created by this plugin.
64 *
65 * @return The module object created by this plugin.
66 * @see #getModuleClass()
67 */
68 T getModule();
69
70 /**
71 * Initialise a module given it's parent plugin and the XML element
72 * representing the module.
73 * <p>
74 * Since atlassian-plugins v2.2, you can no longer load classes from the
75 * plugin in this method, because the OSGi bundle that they will live in is
76 * not built yet. Load classes in the
77 * {@link com.atlassian.plugin.descriptors.AbstractModuleDescriptor#enabled()}
78 * method instead.
79 *
80 * @param plugin The plugin that the module belongs to. Must not be null.
81 * @param element XML element representing the module. Must not be null.
82 * @throws PluginParseException Can be thrown if an error occurs while
83 * parsing the XML element.
84 */
85 void init(@NotNull Plugin plugin, @NotNull Element element) throws PluginParseException;
86
87 /**
88 * Whether or not this plugin module is enabled by default.
89 *
90 * @return {@code true} if this plugin module is enabled by default.
91 */
92 boolean isEnabledByDefault();
93
94 /**
95 * Whether or not this plugin module is a "system" module that shouldn't be
96 * made visible/disable-able to the user. System plugin modules also don't
97 * have their permissions checked, as they may be created dynamically in
98 * response to another, more safe module
99 *
100 * @return {@code true} if this plugin module is a "system" plugin that
101 * shouldn't be made visible/disable-able to the user.
102 */
103 boolean isSystemModule();
104
105 /**
106 * @deprecated The plugin parameter is redundant. Override {@link #destroy()}.
107 */
108 void destroy(Plugin plugin);
109
110 /**
111 * Override this if your plugin needs to clean up when it's been removed.
112 */
113 void destroy();
114
115 Float getMinJavaVersion();
116
117 /**
118 * If a min java version has been specified this will return true if the
119 * running jvm is >= to the specified version. If this is not set then it is
120 * treated as not having a preference.
121 *
122 * @return true if satisfied, false otherwise.
123 */
124 boolean satisfiesMinJavaVersion();
125
126 Map<String, String> getParams();
127
128 /**
129 * Key used to override {@link #getName()} when using internationalisation.
130 *
131 * @return the i18n key. May be null.
132 */
133 String getI18nNameKey();
134
135 /**
136 * Key used to override {@link #getDescription()} when using
137 * internationalisation.
138 *
139 * @return the i18n key. May be null.
140 */
141 String getDescriptionKey();
142
143 /**
144 * @return The plugin this module descriptor is associated with
145 */
146 Plugin getPlugin();
147
148 /**
149 * <p>Compares the specified object with this module descriptor for equality.</p>
150 *
151 * <p>Returns <tt>true</tt> if the given object is also a module descriptor and the two descriptors have the same
152 * "complete key" as determined by {@link #getCompleteKey()}.</p>
153 *
154 * This ensures that the <tt>equals</tt> method works properly across
155 * different implementations of the <tt>ModuleDescriptor</tt> interface.
156 *
157 * @param obj object to be compared for equality with this module descriptor.
158 * @return <tt>true</tt> if the specified object is equal to this module descriptor.
159 * @since 2.8.0
160 */
161 boolean equals(Object obj);
162
163 /**
164 * Returns the hash code value for this module descriptor. The hash code
165 * of a module descriptor <tt>d</tt> is defined to be: <pre>
166 * getCompleteKey() == null ? 0 : getCompleteKey().hashCode()
167 * </pre>
168 * This ensures that <tt>d1.equals(d2)</tt> implies that
169 * <tt>d1.hashCode()==d2.hashCode()</tt> for any two Module Descriptors
170 * <tt>d1</tt> and <tt>d2</tt>, as required by the general
171 * contract of <tt>Object.hashCode</tt>.
172 *
173 * @return the hash code value for this module descriptor.
174 * @see Object#hashCode()
175 * @see Object#equals(Object)
176 * @see #equals(Object)
177 * @since 2.8.0
178 */
179 int hashCode();
180
181 /**
182 * Get whether this plugin module is enabled.
183 *
184 * @return If this module is enabled
185 * @since 3.1
186 */
187 public boolean isEnabled();
188 }