hudson
Class PluginManager

java.lang.Object
  hudson.model.AbstractModelObject
      hudson.PluginManager

All Implemented Interfaces:

ModelObject, SearchableModelObject, SearchItem, OnMaster

Direct Known Subclasses:

LocalPluginManager, TestPluginManager

@ExportedBean
public abstract class PluginManager
extends AbstractModelObject
implements OnMaster

Manages PluginWrappers.

Author:

Kohsuke Kawaguchi

Nested Class Summary

static class	PluginManager.FailedPlugin Remembers why a plugin failed to deploy.
static class	PluginManager.PluginCycleDependenciesMonitor AdministrativeMonitor that checks if there are any plugins with cycle dependencies.
static class	PluginManager.PluginUpdateMonitor AdministrativeMonitor that informs the administrator about a required plugin update.
class	PluginManager.UberClassLoader ClassLoader that can see all plugins.

Field Summary

protected List<PluginWrapper>	activePlugins All active plugins, topologically sorted so that when X depends on Y, Y appears in the list before X does.
static Permission	CONFIGURE_UPDATECENTER
javax.servlet.ServletContext	context Deprecated. as of 1.355 PluginManager can now live longer than Jenkins instance, so use Hudson.getInstance().servletContext instead.
protected List<PluginManager.FailedPlugin>	failedPlugins
static boolean	FAST_LOOKUP
protected List<PluginWrapper>	plugins All discovered plugins.
boolean	pluginUploaded Once plugin is uploaded, this flag becomes true.
File	rootDir Plug-in root directory.
ClassLoader	uberClassLoader PluginManager.UberClassLoader that can load all the publicly visible classes from plugins (and including the classloader that loads Hudson itself.)
static Permission	UPLOAD_PLUGINS

Constructor Summary

PluginManager(javax.servlet.ServletContext context, File rootDir)

Method Summary

protected void	copyBundledPlugin(URL src, String fileName) Copies the bundled plugin from the given URL to the destination of the given file name (like 'abc.jpi'), with a reasonable up-to-date check.
protected PluginStrategy	createPluginStrategy() Creates a hudson.PluginStrategy, looking at the corresponding system property.
<T> Collection<Class<? extends T>>	discover(Class<T> spi) Discover all the service provider implementations of the given class, via META-INF/services.
void	doInstall(org.kohsuke.stapler.StaplerRequest req, org.kohsuke.stapler.StaplerResponse rsp) Performs the installation of the plugins.
org.kohsuke.stapler.HttpResponse	doInstallNecessaryPlugins(org.kohsuke.stapler.StaplerRequest req) Runs prevalidateConfig(java.io.InputStream) on posted XML and redirects to the UpdateCenter.
net.sf.json.JSONArray	doPrevalidateConfig(org.kohsuke.stapler.StaplerRequest req) Like doInstallNecessaryPlugins(StaplerRequest) but only checks if everything is installed or if some plugins need updates or installation.
org.kohsuke.stapler.HttpResponse	doProxyConfigure(org.kohsuke.stapler.StaplerRequest req)
org.kohsuke.stapler.HttpResponse	doSiteConfigure(String site) Bare-minimum configuration mechanism to change the update center.
org.kohsuke.stapler.HttpResponse	doUpdateSources(org.kohsuke.stapler.StaplerRequest req)
org.kohsuke.stapler.HttpResponse	doUploadPlugin(org.kohsuke.stapler.StaplerRequest req) Uploads a plugin.
void	dynamicLoad(File arc) TODO: revisit where/how to expose this.
Api	getApi()
String	getDisplayName()
List<PluginManager.FailedPlugin>	getFailedPlugins()
PluginWrapper	getPlugin(Class<? extends Plugin> pluginClazz) Get the plugin instance that implements a specific class, use to find your plugin singleton.
PluginWrapper	getPlugin(String shortName) Get the plugin instance with the given short name.
List<PluginWrapper>	getPlugins() All discovered plugins.
List<PluginWrapper>	getPlugins(Class<? extends Plugin> pluginSuperclass) Get the plugin instances that extend a specific class, use to find similar plugins.
PluginStrategy	getPluginStrategy()
Descriptor<ProxyConfiguration>	getProxyDescriptor()
String	getSearchUrl() Returns the URL of this item relative to the parent SearchItem.
org.jvnet.hudson.reactor.TaskBuilder	initTasks(InitStrategy initStrategy) Called immediately after the construction.
boolean	isPluginUploaded() Returns true if any new plugin was added.
protected abstract Collection<String>	loadBundledPlugins() If the war file has any "/WEB-INF/plugins/[*.jpi | *.hpi]", extract them into the plugin directory.
Map<String,hudson.util.VersionNumber>	parseRequestedPlugins(InputStream configXml) Parses configuration XML files and picks up references to XML files.
List<Future<UpdateCenter.UpdateCenterJob>>	prevalidateConfig(InputStream configXml) Prepares plugins for some expected XML configuration.
void	stop() Orderly terminates all the plugins.
PluginWrapper	whichPlugin(Class c) Return the PluginWrapper that loaded the given class 'c'.

Methods inherited from class hudson.model.AbstractModelObject

getSearch, getSearchIndex, getSearchName, makeSearchIndex, requirePOST, sendError, sendError, sendError, sendError, sendError

Methods inherited from class java.lang.Object

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

Field Detail

plugins

protected final List<PluginWrapper> plugins

All discovered plugins.

activePlugins

protected final List<PluginWrapper> activePlugins

All active plugins, topologically sorted so that when X depends on Y, Y appears in the list before X does.

failedPlugins

protected final List<PluginManager.FailedPlugin> failedPlugins

rootDir

public final File rootDir

Plug-in root directory.

context

public final javax.servlet.ServletContext context

Deprecated. as of 1.355 PluginManager can now live longer than Jenkins instance, so use Hudson.getInstance().servletContext instead.

uberClassLoader

public final ClassLoader uberClassLoader

PluginManager.UberClassLoader that can load all the publicly visible classes from plugins (and including the classloader that loads Hudson itself.)

pluginUploaded

public volatile boolean pluginUploaded

Once plugin is uploaded, this flag becomes true. This is used to report a message that Jenkins needs to be restarted for new plugins to take effect.

FAST_LOOKUP

public static boolean FAST_LOOKUP

UPLOAD_PLUGINS

public static final Permission UPLOAD_PLUGINS

CONFIGURE_UPDATECENTER

public static final Permission CONFIGURE_UPDATECENTER

Constructor Detail

PluginManager

public PluginManager(javax.servlet.ServletContext context,
                     File rootDir)

Method Detail

getApi

public Api getApi()

initTasks

public org.jvnet.hudson.reactor.TaskBuilder initTasks(InitStrategy initStrategy)

Called immediately after the construction. This is a separate method so that code executed from here will see a valid value in Jenkins.pluginManager.

dynamicLoad

public void dynamicLoad(File arc)
                 throws IOException,
                        InterruptedException,
                        RestartRequiredException

TODO: revisit where/how to expose this. This is an experiment.

Throws:

IOException

InterruptedException

RestartRequiredException

loadBundledPlugins

protected abstract Collection<String> loadBundledPlugins()
                                                  throws Exception

If the war file has any "/WEB-INF/plugins/[*.jpi | *.hpi]", extract them into the plugin directory.

Returns:

File names of the bundled plugins. Like {"ssh-slaves.hpi","subvesrion.jpi"}

Throws:

Exception - Any exception will be reported and halt the startup.

copyBundledPlugin

protected void copyBundledPlugin(URL src,
                                 String fileName)
                          throws IOException

Copies the bundled plugin from the given URL to the destination of the given file name (like 'abc.jpi'), with a reasonable up-to-date check. A convenience method to be used by the loadBundledPlugins().

Throws:

IOException

createPluginStrategy

protected PluginStrategy createPluginStrategy()

Creates a hudson.PluginStrategy, looking at the corresponding system property.

getPluginStrategy

public PluginStrategy getPluginStrategy()

isPluginUploaded

public boolean isPluginUploaded()

Returns true if any new plugin was added.

getPlugins

@Exported
public List<PluginWrapper> getPlugins()

All discovered plugins.

getFailedPlugins

public List<PluginManager.FailedPlugin> getFailedPlugins()

getPlugin

public PluginWrapper getPlugin(String shortName)

Get the plugin instance with the given short name.

Parameters:

shortName - the short name of the plugin

Returns:

The plugin singleton or null if a plugin with the given short name does not exist.

getPlugin

public PluginWrapper getPlugin(Class<? extends Plugin> pluginClazz)

Get the plugin instance that implements a specific class, use to find your plugin singleton. Note: beware the classloader fun.

Parameters:

pluginClazz - The class that your plugin implements.

Returns:

The plugin singleton or null if for some reason the plugin is not loaded.

getPlugins

public List<PluginWrapper> getPlugins(Class<? extends Plugin> pluginSuperclass)

Get the plugin instances that extend a specific class, use to find similar plugins. Note: beware the classloader fun.

Parameters:

pluginSuperclass - The class that your plugin is derived from.

Returns:

The list of plugins implementing the specified class.

getDisplayName

public String getDisplayName()

Specified by:

getDisplayName in interface ModelObject

getSearchUrl

public String getSearchUrl()

Description copied from interface: SearchItem

Returns the URL of this item relative to the parent SearchItem.

Specified by:

getSearchUrl in interface SearchItem

Returns:

URL like "foo" or "foo/bar". The path can end with '/'. The path that starts with '/' will be interpreted as the absolute path (within the context path of Hudson.)

discover

public <T> Collection<Class<? extends T>> discover(Class<T> spi)

Discover all the service provider implementations of the given class, via META-INF/services.

whichPlugin

public PluginWrapper whichPlugin(Class c)

Return the PluginWrapper that loaded the given class 'c'.

Since:

1.402.

stop

public void stop()

Orderly terminates all the plugins.

doUpdateSources

public org.kohsuke.stapler.HttpResponse doUpdateSources(org.kohsuke.stapler.StaplerRequest req)
                                                 throws IOException

Throws:

IOException

doInstall

public void doInstall(org.kohsuke.stapler.StaplerRequest req,
                      org.kohsuke.stapler.StaplerResponse rsp)
               throws IOException,
                      javax.servlet.ServletException

Performs the installation of the plugins.

Throws:

IOException

javax.servlet.ServletException

doSiteConfigure

public org.kohsuke.stapler.HttpResponse doSiteConfigure(@QueryParameter
                                                        String site)
                                                 throws IOException

Bare-minimum configuration mechanism to change the update center.

Throws:

IOException

doProxyConfigure

public org.kohsuke.stapler.HttpResponse doProxyConfigure(org.kohsuke.stapler.StaplerRequest req)
                                                  throws IOException,
                                                         javax.servlet.ServletException

Throws:

IOException

javax.servlet.ServletException

doUploadPlugin

public org.kohsuke.stapler.HttpResponse doUploadPlugin(org.kohsuke.stapler.StaplerRequest req)
                                                throws IOException,
                                                       javax.servlet.ServletException

Uploads a plugin.

Throws:

IOException

javax.servlet.ServletException

getProxyDescriptor

public Descriptor<ProxyConfiguration> getProxyDescriptor()

prevalidateConfig

public List<Future<UpdateCenter.UpdateCenterJob>> prevalidateConfig(InputStream configXml)
                                                             throws IOException

Prepares plugins for some expected XML configuration. If the configuration (typically a job’s config.xml) needs some plugins to be installed (or updated), those jobs will be triggered. Plugins are dynamically loaded whenever possible. Requires Jenkins.ADMINISTER.

Parameters:

configXml - configuration that might be uploaded

Returns:

an empty list if all is well, else a list of submitted jobs which must be completed before this configuration can be fully read

Throws:

IOException - if loading or parsing the configuration failed

Since:

1.483

See Also:

ItemGroupMixIn.createProjectFromXML(java.lang.String, java.io.InputStream), AbstractItem.updateByXml(javax.xml.transform.Source), XStream2, UpdateSite.Plugin.deploy(boolean), PluginWrapper.supportsDynamicLoad(), UpdateCenter.DownloadJob.SuccessButRequiresRestart

doPrevalidateConfig

public net.sf.json.JSONArray doPrevalidateConfig(org.kohsuke.stapler.StaplerRequest req)
                                          throws IOException

Like doInstallNecessaryPlugins(StaplerRequest) but only checks if everything is installed or if some plugins need updates or installation. This method runs without side-effect. I'm still requiring the ADMINISTER permission since XML file can contain various external references and we don't configure parsers properly against that.

Throws:

IOException

Since:

1.483

doInstallNecessaryPlugins

public org.kohsuke.stapler.HttpResponse doInstallNecessaryPlugins(org.kohsuke.stapler.StaplerRequest req)
                                                           throws IOException

Runs prevalidateConfig(java.io.InputStream) on posted XML and redirects to the UpdateCenter.

Throws:

IOException

Since:

1.483

parseRequestedPlugins

public Map<String,hudson.util.VersionNumber> parseRequestedPlugins(InputStream configXml)
                                                            throws IOException

Parses configuration XML files and picks up references to XML files.

Throws:

IOException