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
abstract void addModuleDescriptor(ModuleDescriptor<?> moduleDescriptor)
abstract void close()
This method is deprecated. Since 2.2.0, use uninstall() instead
abstract boolean containsSystemModule()
abstract void disable()
Disables the plugin.
abstract void enable()
Enables the plugin.
abstract ClassLoader getClassLoader()
Get the classloader for the plugin.
abstract Date getDateLoaded()
The date this plugin was loaded into the system.
abstract String getI18nNameKey()
Returns the i18nKey used to get an internationalised name for this plugin.
abstract String getKey()
abstract ModuleDescriptor<?> getModuleDescriptor(String key)
Get the ModuleDescriptor for a particular key.
abstract Collection<ModuleDescriptor<?>> getModuleDescriptors()
Get the Collection of descriptors.
abstract <M> List<ModuleDescriptor<M>> getModuleDescriptorsByModuleClass(Class<M> moduleClass)
Get the descriptors whose module class implements or is assignable from the supplied Class.
abstract String getName()
Returns the non-localised name of this plugin if defined.
abstract PluginInformation getPluginInformation()
abstract PluginState getPluginState()
Returns this plugin's current state.
abstract int getPluginsVersion()
Gets the version of the plugins system to handle this plugin
abstract Set<String> getRequiredPlugins()
abstract URL getResource(String path)
Retrieve the URL of the resource from the plugin.
abstract InputStream getResourceAsStream(String name)
Load a given resource from the plugin.
abstract void install()
Installs the plugin into any internal, managing container.
abstract boolean isBundledPlugin()
Whether the plugin is a "bundled" plugin that can't be removed.
abstract boolean isDeleteable()
Should the plugin file be deleted on unistall?
abstract boolean isDynamicallyLoaded()
Whether or not this plugin is loaded dynamically at runtime.
abstract boolean isEnabled()
This method is deprecated. since 2.2.0, use getPluginState() instead
abstract boolean isEnabledByDefault()
abstract boolean isSystemPlugin()
Whether the plugin is a "system" plugin that shouldn't be made visible to the user.
abstract boolean isUninstallable()
Whether or not this plugin can be 'uninstalled'.
abstract <T> Class<T> loadClass(String clazz, Class<?> callingClass)
Get the plugin to load a specific class.
abstract void setEnabled(boolean enabled)
This method is deprecated. Since 2.2.0, use enable() or disable() instead
abstract void setEnabledByDefault(boolean enabledByDefault)
abstract void setI18nNameKey(String i18nNameKey)
Sets the i18nKey used to get an internationalised name for this plugin.
abstract void setKey(String aPackage)
abstract void setName(String name)
Sets the non-localised name of this plugin.
abstract void setPluginInformation(PluginInformation pluginInformation)
abstract void setPluginsVersion(int version)
Sets the version of the plugins system
abstract void setResources(Resourced resources)
abstract void setSystemPlugin(boolean system)
abstract 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 abstract void addModuleDescriptor (ModuleDescriptor<?> moduleDescriptor)

public abstract 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 abstract boolean containsSystemModule ()

public abstract 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 abstract 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 abstract ClassLoader getClassLoader ()

Get the classloader for the plugin.

Returns
  • The classloader used to load classes for this plugin

public abstract Date getDateLoaded ()

The date this plugin was loaded into the system.

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

public abstract 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 abstract String getKey ()

public abstract 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 abstract 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 abstract 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 abstract 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 abstract PluginInformation getPluginInformation ()

public abstract PluginState getPluginState ()

Returns this plugin's current state.

Returns
  • the current state of the plugin.

public abstract int getPluginsVersion ()

Gets the version of the plugins system to handle this plugin

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

public abstract Set<String> getRequiredPlugins ()

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

public abstract 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 abstract 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 abstract 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 abstract boolean isBundledPlugin ()

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

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

public abstract boolean isDeleteable ()

Should the plugin file be deleted on unistall?

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

public abstract boolean isDynamicallyLoaded ()

Whether or not this plugin is loaded dynamically at runtime.

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

public abstract boolean isEnabled ()

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

Returns
  • true if this plugin is enabled.

public abstract boolean isEnabledByDefault ()

public abstract boolean isSystemPlugin ()

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 abstract boolean isUninstallable ()

Whether or not this plugin can be 'uninstalled'.

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

public abstract 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 abstract void setEnabled (boolean enabled)

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

Parameters
enabled new enabled state

public abstract void setEnabledByDefault (boolean enabledByDefault)

public abstract 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 abstract void setKey (String aPackage)

public abstract void setName (String name)

Sets the non-localised name of this plugin.

Parameters
name the name.
See Also

public abstract void setPluginInformation (PluginInformation pluginInformation)

public abstract void setPluginsVersion (int version)

Sets the version of the plugins system

Parameters
version The version

public abstract void setResources (Resourced resources)

public abstract void setSystemPlugin (boolean system)

public abstract 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