com.atlassian.plugin
Interface Plugin

All Superinterfaces:

java.lang.Comparable<Plugin>, Resourced

All Known Subinterfaces:

ContainerManagedPlugin, DynamicPlugin, PluginArtifactBackedPlugin

All Known Implementing Classes:

AbstractDelegatingPlugin, AbstractPlugin, DefaultDynamicPlugin, OsgiBundlePlugin, OsgiPlugin, StaticPlugin, UnloadablePlugin, XmlDynamicPlugin

public interface Plugin
extends Resourced, java.lang.Comparable<Plugin>

Field Summary

static java.util.Comparator<Plugin>	NAME_COMPARATOR 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.
static int	VERSION_1 This is the historical version of plugins.
static int	VERSION_2 This is the version of plugins which introduced dynamic plugins for all.
static int	VERSION_3 This is the versions of plugins that adds remotes plugins (developed outside of the plugin framework itself).

Method Summary

void	addModuleDescriptor(ModuleDescriptor<?> moduleDescriptor)
void	close() Deprecated. Since 2.2.0, use uninstall() instead
boolean	containsSystemModule()
void	disable() Disables the plugin.
void	enable() Enables the plugin.
java.util.Set<java.lang.String>	getActivePermissions()
java.lang.ClassLoader	getClassLoader() Get the classloader for the plugin.
java.util.Date	getDateLoaded() The date this plugin was loaded into the system.
java.lang.String	getI18nNameKey() Returns the i18nKey used to get an internationalised name for this plugin.
InstallationMode	getInstallationMode() Gets the installation mode
java.lang.String	getKey()
ModuleDescriptor<?>	getModuleDescriptor(java.lang.String key) Get the ModuleDescriptor for a particular key.
java.util.Collection<ModuleDescriptor<?>>	getModuleDescriptors() Get the Collection of descriptors.
<M> java.util.List<ModuleDescriptor<M>>	getModuleDescriptorsByModuleClass(java.lang.Class<M> moduleClass) Get the descriptors whose module class implements or is assignable from the supplied Class.
java.lang.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
java.util.Set<java.lang.String>	getRequiredPlugins()
java.net.URL	getResource(java.lang.String path) Retrieve the URL of the resource from the plugin.
java.io.InputStream	getResourceAsStream(java.lang.String name) Load a given resource from the plugin.
boolean	hasAllPermissions()
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() Deprecated. since 2.2.0, use getPluginState() instead
boolean	isEnabledByDefault()
boolean	isSystemPlugin() Deprecated. since 2.6.0 use PluginMetadataManager.isSystemProvided(Plugin)} instead.
boolean	isUninstallable() Whether or not this plugin can be 'uninstalled'.
<T> java.lang.Class<T>	loadClass(java.lang.String clazz, java.lang.Class<?> callingClass) Get the plugin to load a specific class.
void	setEnabled(boolean enabled) Deprecated. Since 2.2.0, use enable() or disable() instead
void	setEnabledByDefault(boolean enabledByDefault)
void	setI18nNameKey(java.lang.String i18nNameKey) Sets the i18nKey used to get an internationalised name for this plugin.
void	setKey(java.lang.String aPackage)
void	setName(java.lang.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) 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.

Methods inherited from interface com.atlassian.plugin.Resourced

getResourceDescriptor, getResourceDescriptors, getResourceDescriptors, getResourceLocation

Methods inherited from interface java.lang.Comparable

compareTo

Field Detail

VERSION_1

static final int VERSION_1

This is the historical version of plugins. Which is mostly static plugins loaded from the same classpath to the application.

See Also:

Constant Field Values

VERSION_2

static final int VERSION_2

This is the version of plugins which introduced dynamic plugins for all. Based on OSGi and Spring DM. Those plugins undergo some transformations to make the plugin artifact compatible with the OSGi + Spring DM container.

See Also:

Constant Field Values

VERSION_3

static final int VERSION_3

This is the versions of plugins that adds remotes plugins (developed outside of the plugin framework itself). Plugins version 3 don't undergo any transformation so it is up to the plugin developer to write their own Spring configuration files if this is their chosen framework, but other frameworks can be introduced.

See Also:

Constant Field Values

NAME_COMPARATOR

static final java.util.Comparator<Plugin> NAME_COMPARATOR

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.

Method Detail

getPluginsVersion

int getPluginsVersion()

Gets the version of the plugins system to handle this plugin

Returns:

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

setPluginsVersion

void setPluginsVersion(int version)

Sets the version of the plugins system

Parameters:

version - The version

getName

java.lang.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:

getI18nNameKey()

setName

void setName(java.lang.String name)

Sets the non-localised name of this plugin.

Parameters:

name - the name.

See Also:

getName()

getI18nNameKey

java.lang.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:

getName()

setI18nNameKey

void setI18nNameKey(java.lang.String i18nNameKey)

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

Parameters:

i18nNameKey - the i18n Name Key.

See Also:

getI18nNameKey()

getKey

java.lang.String getKey()

setKey

void setKey(java.lang.String aPackage)

addModuleDescriptor

void addModuleDescriptor(ModuleDescriptor<?> moduleDescriptor)

getModuleDescriptors

java.util.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

getModuleDescriptor

ModuleDescriptor<?> getModuleDescriptor(java.lang.String key)

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

Note: The ModuleDescriptor.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:

the ModuleDescriptor of the expected type.

getModuleDescriptorsByModuleClass

<M> java.util.List<ModuleDescriptor<M>> getModuleDescriptorsByModuleClass(java.lang.Class<M> moduleClass)

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

Note: The ModuleDescriptor.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.

Type Parameters:

M - The expected module type of the returned descriptors.

Parameters:

moduleClass - the super class the descriptors return.

Returns:

the List of descriptors of the expected type.

getInstallationMode

InstallationMode getInstallationMode()

Gets the installation mode

Returns:

the plugin's installation mode, local or remote.

Since:

3.0

isEnabledByDefault

boolean isEnabledByDefault()

setEnabledByDefault

void setEnabledByDefault(boolean enabledByDefault)

getPluginInformation

PluginInformation getPluginInformation()

setPluginInformation

void setPluginInformation(PluginInformation pluginInformation)

setResources

void setResources(Resourced resources)

getPluginState

PluginState getPluginState()

Returns this plugin's current state.

Returns:

the current state of the plugin.

Since:

2.2.0

isEnabled

boolean isEnabled()

Deprecated. since 2.2.0, use getPluginState() instead

Returns:

true if this plugin is enabled.

isSystemPlugin

boolean isSystemPlugin()

Deprecated. since 2.6.0 use PluginMetadataManager.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.

setSystemPlugin

void setSystemPlugin(boolean system)

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.

containsSystemModule

boolean containsSystemModule()

isBundledPlugin

boolean isBundledPlugin()

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

Returns:

true if this plugin is a "bundled" plugin.

getDateLoaded

java.util.Date getDateLoaded()

The date this plugin was loaded into the system.

Returns:

The date this plugin was loaded into the system.

isUninstallable

boolean isUninstallable()

Whether or not this plugin can be 'uninstalled'.

Returns:

true if this plugin can be 'uninstalled'.

isDeleteable

boolean isDeleteable()

Should the plugin file be deleted on unistall?

Returns:

true if this plugin file should be deleted on unistall.

isDynamicallyLoaded

boolean isDynamicallyLoaded()

Whether or not this plugin is loaded dynamically at runtime.

Returns:

true if this plugin is loaded dynamically at runtime.

loadClass

<T> java.lang.Class<T> loadClass(java.lang.String clazz,
                                 java.lang.Class<?> callingClass)
                             throws java.lang.ClassNotFoundException

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:

java.lang.ClassNotFoundException - if the class cannot be located.

getClassLoader

java.lang.ClassLoader getClassLoader()

Get the classloader for the plugin.

Returns:

The classloader used to load classes for this plugin

getResource

java.net.URL getResource(java.lang.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

getResourceAsStream

java.io.InputStream getResourceAsStream(java.lang.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.

setEnabled

void setEnabled(boolean enabled)

Deprecated. Since 2.2.0, use enable() or disable() instead

Parameters:

enabled - new enabled state

close

void close()

Deprecated. Since 2.2.0, use uninstall() instead

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

install

void install()
             throws PluginException

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 PluginState.INSTALLED state. If the plugin is already in the PluginState.INSTALLED state, nothing will happen.

Throws:

PluginException - If the plugin could not be installed

Since:

2.2.0

uninstall

void uninstall()
               throws PluginException

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 PluginState.UNINSTALLED state. If the plugin is already in the PluginState.UNINSTALLED state, nothing will happen.

Throws:

PluginException - If the plugin could not be uninstalled

Since:

2.2.0

enable

void enable()
            throws PluginException

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

Throws:

PluginException - If the plugin could not be enabled

Since:

2.2.0

disable

void disable()
             throws PluginException

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

Throws:

PluginException - If the plugin could not be disabled

Since:

2.2.0 If the plugin could not be disabled

getRequiredPlugins

java.util.Set<java.lang.String> getRequiredPlugins()

Returns:

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

Since:

2.2.0

getActivePermissions

java.util.Set<java.lang.String> getActivePermissions()

Returns:

the list of permissions currently valid for the plugin

Since:

3.0

hasAllPermissions

boolean hasAllPermissions()

Returns:

true if the plugin has all the permissions

Since:

3.0