Package hudson

Class 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

    • Constructor Detail

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

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

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

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

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

      • 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

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

      • 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

      • 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).

      • 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

      • 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

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

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

      • 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

      • 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

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