com.atlassian.plugin.descriptors

Class AbstractModuleDescriptor<T>

java.lang.Object

com.atlassian.plugin.descriptors.AbstractModuleDescriptor<T>

All Implemented Interfaces:

ModuleDescriptor<T>, Resourced, ScopeAware, StateAware

Direct Known Subclasses:

BaseServletModuleDescriptor, ComponentImportModuleDescriptor, ComponentModuleDescriptor, DescribedModuleTypeModuleDescriptor, DownloadStrategyModuleDescriptor, EventListenerModuleDescriptor, ModuleTypeModuleDescriptor, ServletContextListenerModuleDescriptor, ServletContextParamModuleDescriptor, UnloadableModuleDescriptor, UnrecognisedModuleDescriptor

public abstract class AbstractModuleDescriptor<T>
extends Object
implements ModuleDescriptor<T>, StateAware

Field Summary

Fields

Modifier and Type	Field and Description
protected String	key
protected Class<T>	moduleClass
protected String	moduleClassName
protected ModuleFactory	moduleFactory
protected String	name
protected Plugin	plugin
protected Resources	resources

Constructor Summary

Constructors

Constructor and Description
AbstractModuleDescriptor(ModuleFactory moduleFactory)

Method Summary

Modifier and Type	Method and Description
protected void	assertModuleClassImplements(Class<T> requiredModuleClazz) Check that the module class of this descriptor implements a given interface, or extends a given class.
protected void	checkPermissions() This is a method that module should call (in their init method implementation to check that permissions are correctly set on the plugin.
void	destroy() The default implementation disables the module if it's still enabled, and unreference the plugin.
void	disabled() Disables the module descriptor.
void	enabled() Enables the descriptor by loading the module class.
boolean	equals(Object obj) Compares the specified object with this module descriptor for equality.
String	getCompleteKey() The complete key for this module, including the plugin key.
String	getDescription() A simple description of this descriptor.
String	getDescriptionKey() Key used to override ModuleDescriptor.getDescription() when using internationalisation.
String	getI18nNameKey() Key used to override ModuleDescriptor.getName() when using internationalisation.
String	getKey() The key for this module, unique within the plugin.
Float	getMinJavaVersion()
abstract T	getModule() The particular module object created by this plugin.
Class<T>	getModuleClass() The class of the module this descriptor creates.
protected String	getModuleClassName()
String	getName() A simple string name for this descriptor.
Map<String,String>	getParams()
Plugin	getPlugin()
String	getPluginKey() The plugin key for this module, derived from the complete key.
protected Set<String>	getRequiredPermissions() The set of additionally required permissions.
ResourceDescriptor	getResourceDescriptor(String type, String name) Get a ResourceDescriptor of a particular type and name.
List<ResourceDescriptor>	getResourceDescriptors() Get a List of all the descriptors .
ResourceLocation	getResourceLocation(String type, String name) Get a ResourceLocation of a particular type and name.
Optional<String>	getScopeKey()
int	hashCode() Returns the hash code value for this module descriptor.
void	init(Plugin plugin, org.dom4j.Element element) Initialise a module given it's parent plugin and the XML element representing the module.
boolean	isBroken() Returns true if this Module is "broken".
boolean	isEnabled() Get whether this plugin module is enabled.
boolean	isEnabledByDefault() Whether or not this plugin module is enabled by default.
boolean	isSystemModule() Whether or not this plugin module is a "system" module that shouldn't be made visible/disable-able to the user.
protected void	loadClass(Plugin plugin, String clazz) Loads the module class that this descriptor provides, and will not necessarily be the implementation class.
protected void	provideValidationRules(ValidationPattern pattern) Provides validation rules for the pattern
boolean	satisfiesMinJavaVersion() If a min java version has been specified this will return true if the running jvm is >= to the specified version.
void	setBroken() Changes state to "broken"
void	setPlugin(Plugin plugin) Sets the plugin for the ModuleDescriptor
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.atlassian.plugin.ModuleDescriptor

getDisplayName

Field Detail

plugin

protected Plugin plugin

key

protected String key

name

protected String name

moduleClassName

protected String moduleClassName

moduleClass

protected Class<T> moduleClass

resources

protected Resources resources

moduleFactory

protected final ModuleFactory moduleFactory

Constructor Detail

AbstractModuleDescriptor

public AbstractModuleDescriptor(ModuleFactory moduleFactory)

Method Detail

init

public void init(@Nonnull
                 Plugin plugin,
                 @Nonnull
                 org.dom4j.Element element)
          throws PluginParseException

Description copied from interface: ModuleDescriptor

Initialise a module given it's parent plugin and the XML element representing the module.

Since atlassian-plugins v2.2, you can no longer load classes from the plugin in this method, because the OSGi bundle that they will live in is not built yet. Load classes in the StateAware.enabled() method instead.

Specified by:

init in interface ModuleDescriptor<T>

Parameters:

plugin - The plugin that the module belongs to. Must not be null.

element - XML element representing the module. Must not be null.

Throws:

PluginParseException - Can be thrown if an error occurs while parsing the XML element.

checkPermissions

protected final void checkPermissions()
                               throws ModulePermissionException

This is a method that module should call (in their init method implementation to check that permissions are correctly set on the plugin. Use the RequirePermission annotation to add permissions to a module, and/or getRequiredPermissions() if you need more dynamic permissions. If either all permissions are allowed or this is a system module, we don't bother to check permissions

Throws:

ModulePermissionException - if the plugin doesn't require the necessary permissions for the module to work.

Since:

3.0

See Also:

RequirePermission, getRequiredPermissions()

getRequiredPermissions

protected Set<String> getRequiredPermissions()

The set of additionally required permissions. This is useful for dynamic permissions depending on module configuration. One might prefer the RequirePermission annotation otherwise for 'static' permissions.

Default implementation returns an empty set

Returns:

the set of additionally required permissions.

Since:

3.0

See Also:

RequirePermission, checkPermissions()

provideValidationRules

protected void provideValidationRules(ValidationPattern pattern)

Provides validation rules for the pattern

Parameters:

pattern - The validation pattern

Since:

2.2.0

loadClass

protected void loadClass(Plugin plugin,
                         String clazz)
                  throws PluginParseException

Loads the module class that this descriptor provides, and will not necessarily be the implementation class. Override this for module descriptors whose type cannot be determined via generics.

Parameters:

clazz - The module class name to load

Throws:

IllegalStateException - If the module class cannot be determined and the descriptor doesn't define a module type via generics

PluginParseException

destroy

public void destroy()

The default implementation disables the module if it's still enabled, and unreference the plugin. Override this if your plugin needs to clean up when it's been removed, and call super.destroy(Plugin) before returning.

Specified by:

destroy in interface ModuleDescriptor<T>

isEnabledByDefault

public boolean isEnabledByDefault()

Description copied from interface: ModuleDescriptor

Whether or not this plugin module is enabled by default.

Specified by:

isEnabledByDefault in interface ModuleDescriptor<T>

Returns:

true if this plugin module is enabled by default.

isSystemModule

public boolean isSystemModule()

Description copied from interface: ModuleDescriptor

Whether or not this plugin module is a "system" module that shouldn't be made visible/disable-able to the user. System plugin modules also don't have their permissions checked, as they may be created dynamically in response to another, more safe module

Specified by:

isSystemModule in interface ModuleDescriptor<T>

Returns:

true if this plugin module is a "system" plugin that shouldn't be made visible/disable-able to the user.

assertModuleClassImplements

protected final void assertModuleClassImplements(Class<T> requiredModuleClazz)
                                          throws PluginParseException

Check that the module class of this descriptor implements a given interface, or extends a given class.

Parameters:

requiredModuleClazz - The class this module's class must implement or extend.

Throws:

PluginParseException - If the module class does not implement or extend the given class.

getCompleteKey

public String getCompleteKey()

Description copied from interface: ModuleDescriptor

The complete key for this module, including the plugin key.

Format is plugin.key:module.key

Specified by:

getCompleteKey in interface ModuleDescriptor<T>

Returns:

The complete key for this module.

See Also:

ModuleDescriptor.getKey(), ModuleDescriptor.getPluginKey()

getPluginKey

public String getPluginKey()

Description copied from interface: ModuleDescriptor

The plugin key for this module, derived from the complete key.

Specified by:

getPluginKey in interface ModuleDescriptor<T>

Returns:

The plugin key for this module.

See Also:

ModuleDescriptor.getKey(), ModuleDescriptor.getCompleteKey()

getKey

public String getKey()

Description copied from interface: ModuleDescriptor

The key for this module, unique within the plugin.

Specified by:

getKey in interface ModuleDescriptor<T>

Returns:

The key for this module.

See Also:

ModuleDescriptor.getCompleteKey(), ModuleDescriptor.getPluginKey()

getName

public String getName()

Description copied from interface: ModuleDescriptor

A simple string name for this descriptor.

Specified by:

getName in interface ModuleDescriptor<T>

Returns:

The name for this ModuleDescriptor.

getModuleClass

public Class<T> getModuleClass()

Description copied from interface: ModuleDescriptor

The class of the module this descriptor creates.

Specified by:

getModuleClass in interface ModuleDescriptor<T>

Returns:

The class of the module this descriptor creates.

See Also:

ModuleDescriptor.getModule()

getModule

public abstract T getModule()

Description copied from interface: ModuleDescriptor

The particular module object created by this plugin.

Specified by:

getModule in interface ModuleDescriptor<T>

Returns:

The module object created by this plugin.

See Also:

ModuleDescriptor.getModuleClass()

getScopeKey

public Optional<String> getScopeKey()

Specified by:

getScopeKey in interface ScopeAware

Returns:

scope set or Optional.empty() if not defined

getDescription

public String getDescription()

Description copied from interface: ModuleDescriptor

A simple description of this descriptor.

Specified by:

getDescription in interface ModuleDescriptor<T>

Returns:

The description for this ModuleDescriptor.

getParams

public Map<String,String> getParams()

Specified by:

getParams in interface ModuleDescriptor<T>

getI18nNameKey

public String getI18nNameKey()

Description copied from interface: ModuleDescriptor

Key used to override ModuleDescriptor.getName() when using internationalisation.

Specified by:

getI18nNameKey in interface ModuleDescriptor<T>

Returns:

the i18n key. May be null.

getDescriptionKey

public String getDescriptionKey()

Description copied from interface: ModuleDescriptor

Key used to override ModuleDescriptor.getDescription() when using internationalisation.

Specified by:

getDescriptionKey in interface ModuleDescriptor<T>

Returns:

the i18n key. May be null.

getResourceDescriptors

public List<ResourceDescriptor> getResourceDescriptors()

Description copied from interface: Resourced

Get a List of all the descriptors .

Note: since 2.2 this list must be immutable, previously modifying this list could modify the underlying list.

Specified by:

getResourceDescriptors in interface Resourced

Returns:

all resource descriptors this object supports.

getResourceLocation

public ResourceLocation getResourceLocation(String type,
                                            String name)

Description copied from interface: Resourced

Get a ResourceLocation of a particular type and name.

Specified by:

getResourceLocation in interface Resourced

Returns:

the specified resource location if found, null otherwise.

getResourceDescriptor

public ResourceDescriptor getResourceDescriptor(String type,
                                                String name)

Description copied from interface: Resourced

Get a ResourceDescriptor of a particular type and name.

Specified by:

getResourceDescriptor in interface Resourced

Returns:

the specified resource descriptor if found, null otherwise.

getMinJavaVersion

public Float getMinJavaVersion()

Specified by:

getMinJavaVersion in interface ModuleDescriptor<T>

satisfiesMinJavaVersion

public boolean satisfiesMinJavaVersion()

Description copied from interface: ModuleDescriptor

If a min java version has been specified this will return true if the running jvm is >= to the specified version. If this is not set then it is treated as not having a preference.

Specified by:

satisfiesMinJavaVersion in interface ModuleDescriptor<T>

Returns:

true if satisfied, false otherwise.

setPlugin

public void setPlugin(Plugin plugin)

Sets the plugin for the ModuleDescriptor

Parameters:

plugin - The plugin to set for this descriptor.

getPlugin

public Plugin getPlugin()

Specified by:

getPlugin in interface ModuleDescriptor<T>

Returns:

The plugin this module descriptor is associated with.

equals

public boolean equals(Object obj)

Description copied from interface: ModuleDescriptor

Compares the specified object with this module descriptor for equality.

Returns true if the given object is also a module descriptor and the two descriptors have the same "complete key" as determined by ModuleDescriptor.getCompleteKey().

This ensures that the equals method works properly across different implementations of the ModuleDescriptor interface.

Specified by:

equals in interface ModuleDescriptor<T>

Overrides:

equals in class Object

Parameters:

obj - object to be compared for equality with this module descriptor.

Returns:

true if the specified object is equal to this module descriptor.

hashCode

public int hashCode()

Description copied from interface: ModuleDescriptor

Returns the hash code value for this module descriptor. The hash code of a module descriptor d is defined to be:

     getCompleteKey() == null ? 0 : getCompleteKey().hashCode()
 

This ensures that d1.equals(d2) implies that d1.hashCode()==d2.hashCode() for any two Module Descriptors d1 and d2, as required by the general contract of Object.hashCode.

Specified by:

hashCode in interface ModuleDescriptor<T>

Overrides:

hashCode in class Object

Returns:

the hash code value for this module descriptor.

See Also:

Object.hashCode(), Object.equals(Object), ModuleDescriptor.equals(Object)

toString

public String toString()

Overrides:

toString in class Object

enabled

public void enabled()

Enables the descriptor by loading the module class. Classes overriding this method MUST call super.enabled() before their own enabling code.

Specified by:

enabled in interface StateAware

Since:

2.1.0

disabled

public void disabled()

Disables the module descriptor. Classes overriding this method MUST call super.disabled() after their own disabling code.

Specified by:

disabled in interface StateAware

getModuleClassName

protected String getModuleClassName()

Returns:

The defined module class name

Since:

3.0

isEnabled

public boolean isEnabled()

Get whether this plugin module is enabled.

Specified by:

isEnabled in interface ModuleDescriptor<T>

Returns:

If this module is enabled

Since:

3.1

setBroken

public void setBroken()

Description copied from interface: ModuleDescriptor

Changes state to "broken"

Being breakable is something subclasses can opt in to, therefore by default ModuleDescriptors are unbreakable, this is a no-op, and ModuleDescriptor.isBroken() returns false

Specified by:

setBroken in interface ModuleDescriptor<T>

isBroken

public boolean isBroken()

Description copied from interface: ModuleDescriptor

Returns true if this Module is "broken".

A "broken" module means that even though this ModuleDescriptor is enabled, calling getModule() results in an error. This typically occurs when the plugin version is not compatible with the version of the host product.

Note that some modules are lazy-loaded, and so this method is optimistic: it will return false until we discover that the Module is not loadable.

Specified by:

isBroken in interface ModuleDescriptor<T>

Returns:

true if broken, false otherwise