com.atlassian.plugin.osgi.factory

Class OsgiPlugin

java.lang.Object

com.atlassian.plugin.impl.AbstractPlugin

com.atlassian.plugin.osgi.factory.OsgiPlugin

All Implemented Interfaces:

ContainerManagedPlugin, OsgiBackedPlugin, Plugin, PluginInternal, Resourced, ScopeAware, Comparable<Plugin>

public class OsgiPlugin
extends AbstractPlugin
implements OsgiBackedPlugin, ContainerManagedPlugin

Plugin that wraps an OSGi bundle that does contain a plugin descriptor. The actual bundle is not created until the AbstractPlugin.install() method is invoked. Any attempt to access a method that requires a bundle will throw an IllegalPluginStateException.

This class uses a OsgiPluginHelper to represent different behaviors of key methods in different states. OsgiPluginUninstalledHelper implements the methods when the plugin hasn't yet been installed into the OSGi container, while OsgiPluginInstalledHelper implements the methods when the bundle is available. This leaves this class to manage the PluginState and interactions with the event system.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ATLASSIAN_PLUGIN_KEY Manifest key for the Atlassian plugin key entry
static String	ATLASSIAN_SCAN_FOLDERS Manifest key for additional scan folders
static String	REMOTE_PLUGIN_KEY Manifest key denoting Atlassian remote plugins

Fields inherited from class com.atlassian.plugin.impl.AbstractPlugin

pluginArtifact

Fields inherited from interface com.atlassian.plugin.Plugin

VERSION_1, VERSION_2, VERSION_3

Constructor Summary

Constructors

Constructor and Description
OsgiPlugin(String key, OsgiContainerManager mgr, PluginArtifact artifact, PluginArtifact originalPluginArtifact, PluginEventManager pluginEventManager)

Method Summary

Modifier and Type	Method and Description
protected void	disableInternal() Disables the plugin by changing the bundle state back to resolved
protected PluginState	enableInternal() Enables the plugin by setting the OSGi bundle state to enabled.
org.osgi.framework.Bundle	getBundle() Returns OSGi Bundle that corresponds to the current plugin
ClassLoader	getClassLoader() Get the classloader for the plugin.
ContainerAccessor	getContainerAccessor()
Date	getDateInstalled() The date this plugin was installed into the system, is the same as the loaded date for non artifact backed plugins
PluginDependencies	getDependencies() Determines which plugin keys are dependencies based on tracing the wires, categorising them as mandatory, optional or dynamic.
InstallationMode	getInstallationMode() Gets the installation mode
URL	getResource(String name) Retrieve the URL of the resource from the plugin.
InputStream	getResourceAsStream(String name) Load a given resource from the plugin.
protected void	installInternal() Installs the plugin artifact into OSGi
boolean	isDeleteable() Should the plugin file be deleted on uninstall?
boolean	isDynamicallyLoaded() Whether or not this plugin is loaded dynamically at runtime.
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	onPluginContainerFailed(PluginContainerFailedEvent event) Called when the plugin container for the bundle has failed to be created.
void	onPluginContainerRefresh(PluginContainerRefreshedEvent event) Called when the plugin container for the bundle has been created or refreshed.
void	onPluginFrameworkShutdownEvent(PluginFrameworkShutdownEvent event)
void	onPluginFrameworkShuttingDownEvent(PluginFrameworkShuttingDownEvent event)
void	onPluginFrameworkStartedEvent(PluginFrameworkStartedEvent event)
void	onServiceDependencyWaitEnded(PluginServiceDependencyWaitEndedEvent event)
void	onServiceDependencyWaitEnded(PluginServiceDependencyWaitTimedOutEvent event)
void	onServiceDependencyWaitStarting(PluginServiceDependencyWaitStartingEvent event)
void	resolve() Perform any required resolution.
void	setKey(String key) Sets key to the specified value.
String	toString()
protected void	uninstallInternal() Uninstalls the bundle from the OSGi container

Methods inherited from class com.atlassian.plugin.impl.AbstractPlugin

addDynamicModuleDescriptor, addModuleDescriptor, cleanVersionString, close, compareAndSetPluginState, compareTo, containsSystemModule, disable, enable, getActivePermissions, getDateEnabled, getDateEnabling, getDateLoaded, getDynamicModuleDescriptors, getI18nNameKey, getKey, getLog, getModuleDescriptor, getModuleDescriptors, getModuleDescriptorsByModuleClass, getName, getPluginArtifact, getPluginInformation, getPluginState, getPluginsVersion, getRequiredPlugins, getResourceDescriptor, getResourceDescriptors, getResourceLocation, getScopeKey, hasAllPermissions, install, isBundledPlugin, isEnabledByDefault, isSystemPlugin, removeDynamicModuleDescriptor, removeModuleDescriptor, setBundledPlugin, setEnabledByDefault, setI18nNameKey, setName, setPluginInformation, setPluginState, setPluginsVersion, setResources, setSystemPlugin, uninstall

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface com.atlassian.plugin.Plugin

addModuleDescriptor, containsSystemModule, disable, enable, getActivePermissions, getDateEnabled, getDateEnabling, getDateLoaded, getI18nNameKey, getKey, getModuleDescriptor, getModuleDescriptors, getModuleDescriptorsByModuleClass, getName, getPluginArtifact, getPluginInformation, getPluginState, getPluginsVersion, hasAllPermissions, install, isBundledPlugin, isEnabledByDefault, isSystemPlugin, setEnabledByDefault, setI18nNameKey, setName, setPluginInformation, setPluginsVersion, setResources, setSystemPlugin, uninstall

Methods inherited from interface com.atlassian.plugin.ScopeAware

getScopeKey

Methods inherited from interface com.atlassian.plugin.Resourced

getResourceDescriptor, getResourceDescriptors, getResourceLocation

Methods inherited from interface java.lang.Comparable

compareTo

Field Detail

ATLASSIAN_PLUGIN_KEY

public static final String ATLASSIAN_PLUGIN_KEY

Manifest key for the Atlassian plugin key entry

See Also:

Constant Field Values

ATLASSIAN_SCAN_FOLDERS

public static final String ATLASSIAN_SCAN_FOLDERS

Manifest key for additional scan folders

See Also:

Constant Field Values

REMOTE_PLUGIN_KEY

public static final String REMOTE_PLUGIN_KEY

Manifest key denoting Atlassian remote plugins

See Also:

Constant Field Values

Constructor Detail

OsgiPlugin

public OsgiPlugin(String key,
                  OsgiContainerManager mgr,
                  PluginArtifact artifact,
                  PluginArtifact originalPluginArtifact,
                  PluginEventManager pluginEventManager)

Method Detail

getBundle

public org.osgi.framework.Bundle getBundle()
                                    throws IllegalPluginStateException

Description copied from interface: OsgiBackedPlugin

Returns OSGi Bundle that corresponds to the current plugin

Note that Bundle could be not available on some of Plugin lifecycle stages. In that case method call results in IllegalPluginStateException

Specified by:

getBundle in interface OsgiBackedPlugin

Returns:

OSGi representation of the current plugin

Throws:

IllegalPluginStateException - if plugin has no OSGi representation yet

getInstallationMode

public InstallationMode getInstallationMode()

Description copied from interface: Plugin

Gets the installation mode

Specified by:

getInstallationMode in interface Plugin

Overrides:

getInstallationMode in class AbstractPlugin

Returns:

the plugin's installation mode, local or remote.

isUninstallable

public boolean isUninstallable()

Description copied from interface: Plugin

Whether or not this plugin can be 'uninstalled'.

Specified by:

isUninstallable in interface Plugin

Returns:

true

isDynamicallyLoaded

public boolean isDynamicallyLoaded()

Description copied from interface: Plugin

Whether or not this plugin is loaded dynamically at runtime.

Specified by:

isDynamicallyLoaded in interface Plugin

Returns:

true

isDeleteable

public boolean isDeleteable()

Description copied from interface: Plugin

Should the plugin file be deleted on uninstall?

Specified by:

isDeleteable in interface Plugin

Returns:

true

getDateInstalled

public Date getDateInstalled()

Description copied from interface: Plugin

The date this plugin was installed into the system, is the same as the loaded date for non artifact backed plugins

Specified by:

getDateInstalled in interface Plugin

Overrides:

getDateInstalled in class AbstractPlugin

Returns:

The date this plugin was installed into the system

setKey

public void setKey(String key)

Sets key to the specified value. This mutator is inherited from Plugin, but should not be used as OsgiPlugin does not support having its key modified after initialization.

Specified by:

setKey in interface Plugin

Overrides:

setKey in class AbstractPlugin

loadClass

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

Description copied from interface: Plugin

Get the plugin to load a specific class.

Specified by:

loadClass in interface Plugin

Type Parameters:

T - The class type

Parameters:

clazz - The name of the class to be loaded

callingClass - The class calling the loading (used to help find a classloader)

Returns:

The class instance, loaded from the OSGi bundle

Throws:

ClassNotFoundException - If the class cannot be found

IllegalPluginStateException - if the bundle hasn't been created yet

getResource

public URL getResource(String name)
                throws IllegalPluginStateException

Description copied from interface: Plugin

Retrieve the URL of the resource from the plugin.

Specified by:

getResource in interface Plugin

Parameters:

name - The resource name

Returns:

The resource URL, null if not found

Throws:

IllegalPluginStateException - if the bundle hasn't been created yet

getResourceAsStream

public InputStream getResourceAsStream(String name)
                                throws IllegalPluginStateException

Description copied from interface: Plugin

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.

Specified by:

getResourceAsStream in interface Plugin

Parameters:

name - The name of the resource to be loaded.

Returns:

Null if not found

Throws:

IllegalPluginStateException - if the bundle hasn't been created yet

getClassLoader

public ClassLoader getClassLoader()
                           throws IllegalPluginStateException

Description copied from interface: Plugin

Get the classloader for the plugin.

Specified by:

getClassLoader in interface Plugin

Returns:

The classloader to load classes and resources from the bundle

Throws:

IllegalPluginStateException - if the bundle hasn't been created yet

onPluginContainerFailed

public void onPluginContainerFailed(PluginContainerFailedEvent event)
                             throws IllegalPluginStateException

Called when the plugin container for the bundle has failed to be created. This means the bundle is still active, but the plugin container is not available, so the plugin will be disabled.

Parameters:

event - The plugin container failed event

Throws:

IllegalPluginStateException - If the plugin key hasn't been set yet

onPluginFrameworkStartedEvent

public void onPluginFrameworkStartedEvent(PluginFrameworkStartedEvent event)

onPluginFrameworkShutdownEvent

public void onPluginFrameworkShutdownEvent(PluginFrameworkShutdownEvent event)

onPluginFrameworkShuttingDownEvent

public void onPluginFrameworkShuttingDownEvent(PluginFrameworkShuttingDownEvent event)

onServiceDependencyWaitStarting

public void onServiceDependencyWaitStarting(PluginServiceDependencyWaitStartingEvent event)

onServiceDependencyWaitEnded

public void onServiceDependencyWaitEnded(PluginServiceDependencyWaitEndedEvent event)

onServiceDependencyWaitEnded

public void onServiceDependencyWaitEnded(PluginServiceDependencyWaitTimedOutEvent event)

onPluginContainerRefresh

public void onPluginContainerRefresh(PluginContainerRefreshedEvent event)
                              throws IllegalPluginStateException

Called when the plugin container for the bundle has been created or refreshed. If this is the first time the context has been refreshed, then it is a new context. Otherwise, this means that the bundle has been reloaded, usually due to a dependency upgrade.

Parameters:

event - The event

Throws:

IllegalPluginStateException - If the plugin key hasn't been set yet

getDependencies

@Nonnull
public PluginDependencies getDependencies()

Determines which plugin keys are dependencies based on tracing the wires, categorising them as mandatory, optional or dynamic. Namespace.RESOLUTION_OPTIONAL and PackageNamespace.RESOLUTION_DYNAMIC are mapped to optional and dynamic, respectively. Any others are mapped to mandatory.

Specified by:

getDependencies in interface Plugin

Overrides:

getDependencies in class AbstractPlugin

Returns:

not null, possibly empty

Since:

4.0

See Also:

Plugin.getDependencies()

toString

public String toString()

Overrides:

toString in class AbstractPlugin

installInternal

protected void installInternal()
                        throws IllegalPluginStateException

Installs the plugin artifact into OSGi

Overrides:

installInternal in class AbstractPlugin

Throws:

IllegalPluginStateException - if the bundle hasn't been created yet

enableInternal

protected PluginState enableInternal()
                              throws OsgiContainerException,
                                     IllegalPluginStateException

Enables the plugin by setting the OSGi bundle state to enabled.

Overrides:

enableInternal in class AbstractPlugin

Returns:

PluginState.ENABLEDif the container is being refreshed or PluginState.ENABLING if we are waiting on a plugin container (first time being activated, as all subsequent times are considered refreshes)

Throws:

OsgiContainerException - If the underlying OSGi system threw an exception or we tried to enable the bundle when it was in an invalid state

IllegalPluginStateException - if the bundle hasn't been created yet

disableInternal

protected void disableInternal()
                        throws OsgiContainerException,
                               IllegalPluginStateException

Disables the plugin by changing the bundle state back to resolved

Overrides:

disableInternal in class AbstractPlugin

Throws:

OsgiContainerException - If the OSGi system threw an exception

IllegalPluginStateException - if the bundle hasn't been created yet

uninstallInternal

protected void uninstallInternal()
                          throws OsgiContainerException,
                                 IllegalPluginStateException

Uninstalls the bundle from the OSGi container

Overrides:

uninstallInternal in class AbstractPlugin

Throws:

OsgiContainerException - If the underlying OSGi system threw an exception

IllegalPluginStateException - if the bundle hasn't been created yet

getContainerAccessor

public ContainerAccessor getContainerAccessor()

Specified by:

getContainerAccessor in interface ContainerManagedPlugin

Returns:

The object to use to access the plugin's container

resolve

public void resolve()

Description copied from interface: Plugin

Perform any required resolution. This is a hook to allow the plugin system to perform a resolution pass over a group of modules before the enable pass.

Specified by:

resolve in interface Plugin

Overrides:

resolve in class AbstractPlugin