Package hudson

Class PluginWrapper

java.lang.Object
hudson.PluginWrapper
All Implemented Interfaces:
ModelObject, Comparable<PluginWrapper>
@ExportedBean public class PluginWrapper extends Object implements Comparable<PluginWrapper>, ModelObject
Represents a Jenkins plug-in and associated control information for Jenkins to control Plugin.

A plug-in is packaged into a jar file whose extension is ".jpi" (or ".hpi" for backward compatibility), A plugin needs to have a special manifest entry to identify what it is.

At the runtime, a plugin has two distinct state axis.

  1. Enabled/Disabled. If enabled, Jenkins is going to use it next time Jenkins runs. Otherwise the next run will ignore it.
  2. Activated/Deactivated. If activated, that means Jenkins is using the plugin in this session. Otherwise it's not.

For example, an activated but disabled plugin is still running but the next time it won't.

Author:
Kohsuke Kawaguchi

  • Field Details

  • Constructor Details

    • PluginWrapper

      public PluginWrapper(PluginManager parent, File archive, Manifest manifest, URL baseResourceURL, ClassLoader classLoader, File disableFile, List<PluginWrapper.Dependency> dependencies, List<PluginWrapper.Dependency> optionalDependencies)
      Parameters:
      archive - A .jpi archive file jar file, or a .jpl linked plugin.
      manifest - The manifest for the plugin
      baseResourceURL - A URL pointing to the resources for this plugin
      classLoader - a classloader that loads classes from this plugin and its dependencies
      disableFile - if this file exists on startup, the plugin will not be activated
      dependencies - a list of mandatory dependencies
      optionalDependencies - a list of optional dependencies

  • Method Details

    • getDependencyErrors

      public List<String> getDependencyErrors()

    • getOriginalDependencyErrors

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<String> getOriginalDependencyErrors()

    • hasOriginalDependencyErrors

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean hasOriginalDependencyErrors()

    • getDerivedDependencyErrors

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<String> getDerivedDependencyErrors()

    • hasDerivedDependencyErrors

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean hasDerivedDependencyErrors()

    • setDependents

      public void setDependents(@NonNull Set<String> dependents)
      Set the list of components that depend on this plugin.
      Parameters:
      dependents - The list of components that depend on this plugin.

    • setDependants

      @Deprecated public void setDependants(@NonNull Set<String> dependents)
      Deprecated.
      Please use setDependents(java.util.Set<java.lang.String>).

    • setOptionalDependents

      public void setOptionalDependents(@NonNull Set<String> optionalDependents)
      Set the list of components that depend optionally on this plugin.
      Parameters:
      optionalDependents - The list of components that depend optionally on this plugin.

    • setOptionalDependants

      @Deprecated public void setOptionalDependants(@NonNull Set<String> optionalDependents)
      Deprecated.
      Please use setOptionalDependents(java.util.Set<java.lang.String>).

    • getDependents

      @NonNull public Set<String> getDependents()
      Get the list of components that depend on this plugin. Note that the list will include elements of getOptionalDependents().
      Returns:
      The list of components that depend on this plugin.

    • getDependants

      @Deprecated @NonNull public Set<String> getDependants()
      Deprecated.
      Please use getDependents().

    • getMandatoryDependents

      @NonNull public Set<String> getMandatoryDependents()
      Like getDependents() but excluding optional dependencies.
      Since:
      2.181

    • getOptionalDependents

      @NonNull public Set<String> getOptionalDependents()
      Returns:
      The list of components that depend optionally on this plugin.

    • getOptionalDependants

      @Deprecated @NonNull public Set<String> getOptionalDependants()
      Deprecated.
      Please use getOptionalDependents().

    • hasDependents

      public boolean hasDependents()
      Does this plugin have anything that depends on it. Note that optional dependents are included.
      Returns:
      true if something (Jenkins core, or another plugin) depends on this plugin, otherwise false.

    • hasMandatoryDependents

      public boolean hasMandatoryDependents()
      Like hasDependents() but excluding optional dependencies.
      Since:
      2.181

    • hasDependants

      @Deprecated public boolean hasDependants()
      Deprecated.
      Please use hasDependents().

    • hasOptionalDependents

      public boolean hasOptionalDependents()
      Does this plugin have anything that depends optionally on it.
      Returns:
      true if something (Jenkins core, or another plugin) depends optionally on this plugin, otherwise false.

    • hasOptionalDependants

      @Deprecated public boolean hasOptionalDependants()
      Deprecated.
      Please use hasOptionalDependents().

    • hasDependencies

      public boolean hasDependencies()
      Does this plugin depend on any other plugins. Note that this include optional dependencies.
      Returns:
      true if this plugin depends on other plugins, otherwise false.

    • hasMandatoryDependencies

      public boolean hasMandatoryDependencies()
      Like hasDependencies() but omitting optional dependencies.
      Since:
      2.181

    • isDeprecated

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean isDeprecated()
      Is this plugin deprecated?
      Returns:
      true if and only if an update site reports deprecations for this plugin.
      Since:
      2.246

    • injectJarsToClasspath

      @Restricted(org.kohsuke.accmod.restrictions.Beta.class) public void injectJarsToClasspath(File... jars) throws Exception
      Inject the specified jar file(s) to the plugins classpath.

      Warning: This is advanced usage that you should not be needed in 99.9% of all cases, any jar insertion should happen early into the plugins lifecycle to prevent classloading issues in dependent plugins.

      Rather than use this functionality it is to have co-operative behaviour between any consumer of the libraries and load the classes in a separate ClassLoader. you can expose third-party libraries from a dynamic location in various ways, such as:

      • You could split your plugin into two modules:
        • regular Jenkins plugin code, plus some interface encapsulating access to the lib via a minimal, simplified API
        • an implementation of that interface which compiles against a provided static reference copy of the library, and which is packaged in your plugin as a resource (not in WEB-INF/lib/*.jar)
      • with coordination:
        • dynamically find some JAR(s) on the controller (or perhaps even agent)
        • find the bridge JAR in your plugin’s resources area
        • create some URLClassLoader loading them both, parented to the plugin ClassLoader
        • use reflection to load & instantiate the class of the bridge implementation, casting to the interface from the plugin
      For a concrete example see the database plugin. *
      Throws:
      Exception - if the File could not be inserted into the classpath for some reason.
      Since:
      2.313

    • getDisplayName

      public String getDisplayName()
      Specified by:
      getDisplayName in interface ModelObject

    • getApi

      public Api getApi()

    • getIndexPage

      public URL getIndexPage()
      Returns the URL of the index page jelly script.

    • getDependencies

      @Exported public List<PluginWrapper.Dependency> getDependencies()
      Gets all dependencies of this plugin on other plugins. Note that the list will usually include the members of getOptionalDependencies() (missing optional dependencies will however be omitted).

    • getMandatoryDependencies

      public List<PluginWrapper.Dependency> getMandatoryDependencies()
      Like getDependencies() but omits optional dependencies.
      Since:
      2.181

    • getOptionalDependencies

      public List<PluginWrapper.Dependency> getOptionalDependencies()

    • getShortName

      @Exported public String getShortName()
      Returns the short name suitable for URL.

    • getPlugin

      @CheckForNull public Plugin getPlugin()
      Gets the instance of Plugin contributed by this plugin.
      Returns:
      Plugin instace or null if it is not present in the plugin instance store.

    • getPluginOrFail

      @NonNull public Plugin getPluginOrFail() throws Exception
      Gets the instance of Plugin contributed by this plugin.
      Throws:
      Exception - no plugin in the PluginManager.PluginInstanceStore

    • getUrl

      @Exported public String getUrl()
      Gets the URL that shows more information about this plugin.
      Returns:
      null if this information is unavailable.
      Since:
      1.283

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getLongName

      @Exported @Deprecated public String getLongName()
      Deprecated.
      For most purposes, use getDisplayName().
      Returns a one-line descriptive name of this plugin.

    • supportsDynamicLoad

      @Exported public YesNoMaybe supportsDynamicLoad()
      Does this plugin supports dynamic loading?

    • getVersion

      @Exported public String getVersion()
      Returns the version number of this plugin

    • getRequiredCoreVersion

      @Exported @CheckForNull public String getRequiredCoreVersion()
      Returns the required Jenkins core version of this plugin.
      Returns:
      the required Jenkins core version of this plugin.
      Since:
      2.16

    • getVersionNumber

      public VersionNumber getVersionNumber()
      Returns the version number of this plugin

    • isOlderThan

      public boolean isOlderThan(VersionNumber v)
      Returns true if the version of this plugin is older than the given version.

    • stop

      public void stop()
      Terminates the plugin.

    • releaseClassLoader

      public void releaseClassLoader()

    • enable

      public void enable() throws IOException
      Enables this plugin next time Jenkins runs.
      Throws:
      IOException

    • disable

      @Deprecated public void disable() throws IOException
      Deprecated.
      use disable(PluginDisableStrategy)
      Disables this plugin next time Jenkins runs. As it doesn't check anything, it's recommended to use the method disable(PluginDisableStrategy)
      Throws:
      IOException

    • disable

      @NonNull public PluginWrapper.PluginDisableResult disable(@NonNull PluginWrapper.PluginDisableStrategy strategy)
      Disable this plugin using a strategy.
      Parameters:
      strategy - strategy to use
      Returns:
      an object representing the result of the disablement of this plugin and its dependents plugins.

    • isActive

      @Exported public boolean isActive()
      Returns true if this plugin is enabled for this session.

    • hasCycleDependency

      public boolean hasCycleDependency()

    • setHasCycleDependency

      public void setHasCycleDependency(boolean hasCycle)

    • isBundled

      @Exported public boolean isBundled()
      Is this plugin bundled in the WAR? Normally false as noted in PluginManager.loadBundledPlugins(): this does not apply to “detached” plugins.

    • isEnabled

      @Exported public boolean isEnabled()
      If true, the plugin is going to be activated next time Jenkins runs.

    • getManifest

      public Manifest getManifest()

    • setPlugin

      public void setPlugin(Plugin plugin)

    • getPluginClass

      public String getPluginClass()

    • hasLicensesXml

      public boolean hasLicensesXml()

    • getUpdateInfo

      public UpdateSite.Plugin getUpdateInfo()
      If the plugin has an update, returns the UpdateSite.Plugin object.
      Returns:
      This method may return null — for example, the user may have installed a plugin locally developed.

    • getInfo

      public UpdateSite.Plugin getInfo()
      returns the UpdateSite.Plugin object, or null.

    • hasUpdate

      @Exported public boolean hasUpdate()
      Returns true if this plugin has update in the update center.

      This method is conservative in the sense that if the version number is incomprehensible, it always returns false.

    • isPinned

      @Exported @Deprecated public boolean isPinned()
      Deprecated.

    • isDeleted

      @Exported public boolean isDeleted()
      Returns true if this plugin is deleted. The plugin continues to function in this session, but in the next session it'll disappear.

    • isDetached

      @Exported public boolean isDetached()
      Same as DetachedPluginsUtil.isDetachedPlugin(java.lang.String).
      Since:
      2.185

    • hasImpliedDependents

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean hasImpliedDependents()

    • getImpliedDependents

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) @NonNull public Set<String> getImpliedDependents()
      Get list of implied dependencies.
      Since:
      2.296

    • compareTo

      public int compareTo(PluginWrapper pw)
      Sort by short name.
      Specified by:
      compareTo in interface Comparable<PluginWrapper>

    • isDowngradable

      @Exported public boolean isDowngradable()
      returns true if backup of previous version of plugin exists

    • getBackupFile

      public File getBackupFile()
      Where is the backup file?

    • getBackupVersion

      @Exported public String getBackupVersion()
      returns the version of the backed up plugin, or null if there's no back up.

    • isPinningForcingOldVersion

      @Deprecated public boolean isPinningForcingOldVersion()
      Deprecated.
      removed without replacement
      Checks if this plugin is pinned and that's forcing us to use an older version than the bundled one.

    • doMakeEnabled

      public org.kohsuke.stapler.HttpResponse doMakeEnabled() throws IOException
      Throws:
      IOException

    • doMakeDisabled

      public org.kohsuke.stapler.HttpResponse doMakeDisabled() throws IOException
      Throws:
      IOException

    • doPin

      @Deprecated public org.kohsuke.stapler.HttpResponse doPin() throws IOException
      Deprecated.
      Throws:
      IOException

    • doUnpin

      @Deprecated public org.kohsuke.stapler.HttpResponse doUnpin() throws IOException
      Deprecated.
      Throws:
      IOException

    • doDoUninstall

      public org.kohsuke.stapler.HttpResponse doDoUninstall() throws IOException
      Throws:
      IOException

    • getActiveWarnings

      @Restricted(org.kohsuke.accmod.restrictions.DoNotUse.class) public List<UpdateSite.Warning> getActiveWarnings()

    • getDeprecations

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public List<UpdateSite.Deprecation> getDeprecations()

    • getIssueTrackerReportUrl

      @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) public String getIssueTrackerReportUrl()