public interface

Plugin

implements Resourced Comparable<T>
com.atlassian.plugin.Plugin
Known Indirect Subclasses

Summary

Fields
public static final Comparator<Plugin> NAME_COMPARATOR This field is deprecated. since 2.2.0. This comparator only takes into account the plugin name and assumes it is not null, yet a) that constraint is not validated anywhere in plugin loading and b) the plugin could have used the i18n name, and only the application can resolve that to a name useful for comparisons.
Public Methods
void addModuleDescriptor(ModuleDescriptor<?> moduleDescriptor)
void close()
This method is deprecated. Since 2.2.0, use uninstall() instead
boolean containsSystemModule()
void disable()
Disables the plugin.
void enable()
Enables the plugin.
ClassLoader getClassLoader()
Get the classloader for the plugin.
Date getDateLoaded()
The date this plugin was loaded into the system.
String getI18nNameKey()
Returns the i18nKey used to get an internationalised name for this plugin.
String getKey()
ModuleDescriptor<?> getModuleDescriptor(String key)
Get the ModuleDescriptor for a particular key.
Collection<ModuleDescriptor<?>> getModuleDescriptors()
<M> List<ModuleDescriptor<M>> getModuleDescriptorsByModuleClass(Class<M> moduleClass)
Get the descriptors whose module class implements or is assignable from the supplied Class.
String getName()
Returns the non-localised name of this plugin if defined.
PluginInformation getPluginInformation()
PluginState getPluginState()
Returns this plugin's current state.
int getPluginsVersion()
Gets the version of the plugins system to handle this plugin
Set<String> getRequiredPlugins()
URL getResource(String path)
Retrieve the URL of the resource from the plugin.
InputStream getResourceAsStream(String name)
Load a given resource from the plugin.
void install()
Installs the plugin into any internal, managing container.
boolean isBundledPlugin()
Whether the plugin is a "bundled" plugin that can't be removed.
boolean isDeleteable()
Should the plugin file be deleted on unistall?
boolean isDynamicallyLoaded()
Whether or not this plugin is loaded dynamically at runtime.
boolean isEnabled()
This method is deprecated. since 2.2.0, use getPluginState() instead
boolean isEnabledByDefault()
boolean isSystemPlugin()
This method is deprecated. since 2.6.0 use isSystemProvided(Plugin)} instead.
boolean isUninstallable()
Whether or not this plugin can be 'uninstalled'.
<T> Class<T> loadClass(String clazz, Class<?> callingClass)
Get the plugin to load a specific class.
void setEnabled(boolean enabled)
This method is deprecated. Since 2.2.0, use enable() or disable() instead
void setEnabledByDefault(boolean enabledByDefault)
void setI18nNameKey(String i18nNameKey)
Sets the i18nKey used to get an internationalised name for this plugin.
void setKey(String aPackage)
void setName(String name)
Sets the non-localised name of this plugin.
void setPluginInformation(PluginInformation pluginInformation)
void setPluginsVersion(int version)
Sets the version of the plugins system
void setResources(Resourced resources)
void setSystemPlugin(boolean system)
This method is deprecated. since 2.6.0 provide PluginMetadataManager with information about the plugin instead. There is no way to programatically set this value now.
void uninstall()
Uninstalls the plugin from any internal container.
[Expand]
Inherited Methods
From interface com.atlassian.plugin.Resourced
From interface java.lang.Comparable

Fields

public static final Comparator<Plugin> NAME_COMPARATOR

This field is deprecated.
since 2.2.0. This comparator only takes into account the plugin name and assumes it is not null, yet a) that constraint is not validated anywhere in plugin loading and b) the plugin could have used the i18n name, and only the application can resolve that to a name useful for comparisons.

Public Methods

public void addModuleDescriptor (ModuleDescriptor<?> moduleDescriptor)

public void close ()

This method is deprecated.
Since 2.2.0, use uninstall() instead

Free any resources held by this plugin. To be called during uninstallation of the Plugin.

public boolean containsSystemModule ()

public void disable ()

Disables the plugin. Unless an exception is thrown, the plugin should be in the DISABLED state. If the plugin is already in the DISABLED state, nothing will happen.

Throws
PluginException If the plugin could not be disabled

public void enable ()

Enables the plugin. Unless an exception is thrown, the plugin should then be in either the ENABLING or ENABLED state. If the plugin is already in the ENABLING or ENABLED state, nothing will happen.

Throws
PluginException If the plugin could not be enabled

public ClassLoader getClassLoader ()

Get the classloader for the plugin.

Returns
  • The classloader used to load classes for this plugin

public Date getDateLoaded ()

The date this plugin was loaded into the system.

Returns
  • The date this plugin was loaded into the system.

public String getI18nNameKey ()

Returns the i18nKey used to get an internationalised name for this plugin.

This corresponds to the value of the i18n-name-key field in the plugin's XML configuration file.

You would expect a plugin developer to fill in one of either name, or i18n-name-key, but the framework does no validation and makes no guarantees that this is the case.

Returns
  • the i18n Name Key for this plugin if defined, or null.
See Also

public String getKey ()

public ModuleDescriptor<?> getModuleDescriptor (String key)

Get the ModuleDescriptor for a particular key. Returns null if the plugin does not exist.

Note: The getModule() may throw ClassCastException if the expected type is incorrect.

Parameters
key the String complete key of the module, in the form "org.example.plugin:module-key".
Returns

public Collection<ModuleDescriptor<?>> getModuleDescriptors ()

Get the Collection of descriptors.

The iteration order of the collection is the order that the modules will be enabled, and should be the same order that the modules appear in the plugin descriptor.

Returns
  • the modules contained by this plugin in the order they are to be enabled

public List<ModuleDescriptor<M>> getModuleDescriptorsByModuleClass (Class<M> moduleClass)

Get the descriptors whose module class implements or is assignable from the supplied Class.

Note: The getModule() may throw ClassCastException if the expected type is incorrect. Normally this method would not be supplied with anything other than Object or <?>, unless you are confident in the super type of the module classes this Plugin provides.

Parameters
moduleClass the super class the descriptors return.
Returns

public String getName ()

Returns the non-localised name of this plugin if defined.

This corresponds to the value of the name field in the plugin's XML configuration file.

You would expect a plugin developer to fill in one of either name, or i18n-name-key, but the framework does no validation and makes no guarantees that this is the case.

Returns
  • the non-localised name of this plugin if defined, or null.
See Also

public PluginInformation getPluginInformation ()

public PluginState getPluginState ()

Returns this plugin's current state.

Returns
  • the current state of the plugin.

public int getPluginsVersion ()

Gets the version of the plugins system to handle this plugin

Returns
  • The plugins version. If undefined, assumed to be 1.

public Set<String> getRequiredPlugins ()

Returns
  • A list of plugin keys that this plugin is dependent upon, or an empty list if none

public URL getResource (String path)

Retrieve the URL of the resource from the plugin.

Parameters
path the name of the resource to be loaded
Returns
  • The URL to the resource, or null if the resource is not found

public InputStream getResourceAsStream (String name)

Load a given resource from the plugin. Plugins that are loaded dynamically will need to implement this in a way that loads the resource from the same context as the plugin. Static plugins can just pull them from their own classloader.

Parameters
name The name of the resource to be loaded.
Returns
  • An InputStream for the resource, or null if the resource is not found.

public void install ()

Installs the plugin into any internal, managing container. This method will be called on every startup. Unless an exception is thrown, the plugin should be in the INSTALLED state. If the plugin is already in the INSTALLED state, nothing will happen.

Throws
PluginException If the plugin could not be installed

public boolean isBundledPlugin ()

Whether the plugin is a "bundled" plugin that can't be removed.

Returns
  • true if this plugin is a "bundled" plugin.

public boolean isDeleteable ()

Should the plugin file be deleted on unistall?

Returns
  • true if this plugin file should be deleted on unistall.

public boolean isDynamicallyLoaded ()

Whether or not this plugin is loaded dynamically at runtime.

Returns
  • true if this plugin is loaded dynamically at runtime.

public boolean isEnabled ()

This method is deprecated.
since 2.2.0, use getPluginState() instead

Returns
  • true if this plugin is enabled.

public boolean isEnabledByDefault ()

public boolean isSystemPlugin ()

This method is deprecated.
since 2.6.0 use isSystemProvided(Plugin)} instead.

Whether the plugin is a "system" plugin that shouldn't be made visible to the user.

Returns
  • true if this plugin is a "system" plugin.

public boolean isUninstallable ()

Whether or not this plugin can be 'uninstalled'.

Returns
  • true if this plugin can be 'uninstalled'.

public Class<T> loadClass (String clazz, Class<?> callingClass)

Get the plugin to load a specific class.

Parameters
clazz The name of the class to be loaded
callingClass The class calling the loading (used to help find a classloader)
Returns
  • The loaded class.
Throws
ClassNotFoundException if the class cannot be located.

public void setEnabled (boolean enabled)

This method is deprecated.
Since 2.2.0, use enable() or disable() instead

Parameters
enabled new enabled state

public void setEnabledByDefault (boolean enabledByDefault)

public void setI18nNameKey (String i18nNameKey)

Sets the i18nKey used to get an internationalised name for this plugin.

Parameters
i18nNameKey the i18n Name Key.
See Also

public void setKey (String aPackage)

public void setName (String name)

Sets the non-localised name of this plugin.

Parameters
name the name.
See Also

public void setPluginInformation (PluginInformation pluginInformation)

public void setPluginsVersion (int version)

Sets the version of the plugins system

Parameters
version The version

public void setResources (Resourced resources)

public void setSystemPlugin (boolean system)

This method is deprecated.
since 2.6.0 provide PluginMetadataManager with information about the plugin instead. There is no way to programatically set this value now.

Parameters
system whether the plugin is a "system" plugin that shouldn't be made visible to the user.

public void uninstall ()

Uninstalls the plugin from any internal container. This method will be called on every shutdown. Unless an exception is thrown, the plugin should be in the UNINSTALLED state. If the plugin is already in the UNINSTALLED state, nothing will happen.

Throws
PluginException If the plugin could not be uninstalled