Package com.atlassian.plugin

Interface Plugin

All Superinterfaces:
Comparable<Plugin>, Resourced, ScopeAware
All Known Subinterfaces:
ContainerManagedPlugin
All Known Implementing Classes:
DummyPlugin
public interface Plugin extends ScopeAware, Resourced, Comparable<Plugin>

  • Field Details

    • 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:

    • 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:

    • 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:

  • Method Details

    • 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

      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:

    • setName

      void setName(String name)
      Sets the non-localised name of this plugin.
      Parameters:
      name - the name.
      See Also:

    • getI18nNameKey

      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:

    • setI18nNameKey

      void setI18nNameKey(String i18nNameKey)
      Sets the i18nKey used to get an internationalised name for this plugin.
      Parameters:
      i18nNameKey - the i18n Name Key.
      See Also:

    • getKey

      String getKey()

    • setKey

      void setKey(String aPackage)

    • addModuleDescriptor

      void addModuleDescriptor(ModuleDescriptor<?> moduleDescriptor)

    • getModuleDescriptors

      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(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> List<ModuleDescriptor<M>> getModuleDescriptorsByModuleClass(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

    • isSystemPlugin

      @Deprecated 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

      @Deprecated 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

      Date getDateLoaded()
      The date this plugin was loaded into the system.
      Returns:
      The date this plugin was loaded into the system.

    • getDateInstalled

      Date getDateInstalled()
      The date this plugin was installed into the system, is the same as the loaded date for non artifact backed plugins
      Returns:
      The date this plugin was installed into the system
      Since:
      3.0.0

    • 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 uninstall?
      Returns:
      true if this plugin file should be deleted on uninstall.

    • 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> Class<T> loadClass(String clazz, Class<?> callingClass) throws 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:
      ClassNotFoundException - if the class cannot be located.

    • getClassLoader

      ClassLoader getClassLoader()
      Get the classloader for the plugin.
      Returns:
      The classloader used to load classes for this plugin

    • getResource

      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

    • getResourceAsStream

      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.

    • install

      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 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()
      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()
      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()
      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

    • getDependencies

      @Nonnull PluginDependencies getDependencies()
      Determines which plugin keys are dependencies, categorising them as mandatory, optional or dynamic.
      Returns:
      not null, possibly empty
      Since:
      4.0

    • getActivePermissions

      Set<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

    • resolve

      void resolve()
      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.
      Since:
      4.0.0

    • getDateEnabling

      @Nullable Date getDateEnabling()
      Obtain the date that the plugin system most recently commenced enabling this plugin. This may return null if the plugin has never commenced enabling, or if the value is unavailable for other reasons, such as wrappers around legacy implementations.
      Returns:
      the date that the plugin most recently entered PluginState.ENABLING.
      Since:
      4.0.0

    • getDateEnabled

      @Nullable Date getDateEnabled()
      Obtain the date that the plugin system most recently completed enabling of this plugin. This will return null if the plugin has never been enabled, has not completed enabling since it most recently started enabling, or if the value is unavailable for any other reason, such as wrappers around legacy implementations.
      Returns:
      the date that the plugin most recently entered PluginState.ENABLED, if this was not before the most recent PluginState.ENABLING, otherwise null.
      Since:
      4.0.0

    • getPluginArtifact

      @Internal PluginArtifact getPluginArtifact()
      Retrieve the original, unprocessed or transformed PluginArtifact used to create this plugin instance.

      Note that this method may be removed without notice; it is for use only by the host application.

      This method was originally part of the internal PluginArtifactBackedPlugin interface that is no longer present.

      Returns:
      null if this plugin has no artifact
      Since:
      4.0.0