hudson.model

Class UpdateCenter

java.lang.Object

hudson.model.AbstractModelObject

hudson.model.UpdateCenter

All Implemented Interfaces:

ModelObject, Saveable, SearchableModelObject, SearchItem, OnMaster, org.kohsuke.stapler.StaplerProxy

@ExportedBean
public class UpdateCenter
extends AbstractModelObject
implements Saveable, OnMaster, org.kohsuke.stapler.StaplerProxy

Controls update center capability.

The main job of this class is to keep track of the latest update center metadata file, and perform installations. Much of the UI about choosing plugins to install is done in PluginManager.

The update center can be configured to contact alternate servers for updates and plugins, and to use alternate strategies for downloading, installing and updating components. See the Javadocs for UpdateCenter.UpdateCenterConfiguration for more information.

Extending Update Centers. The update center in Jenkins can be replaced by defining a System Property (hudson.model.UpdateCenter.className). See createUpdateCenter(hudson.model.UpdateCenter.UpdateCenterConfiguration). This className should be available on early startup, so it cannot come only from a library (e.g. Jenkins module or Extra library dependency in the WAR file project). Plugins cannot be used for such purpose. In order to be correctly instantiated, the class definition must have two constructors: UpdateCenter() and UpdateCenter(hudson.model.UpdateCenter.UpdateCenterConfiguration). If the class does not comply with the requirements, a fallback to the default UpdateCenter will be performed.

Since:

1.220

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	UpdateCenter.CompleteBatchJob
class	UpdateCenter.ConnectionCheckJob Tests the internet connectivity.
static class	UpdateCenter.CoreUpdateMonitor AdministrativeMonitor that checks if there's Jenkins update.
class	UpdateCenter.DownloadJob Base class for a job that downloads a file from the Jenkins project.
class	UpdateCenter.EnableJob Enables a required plugin, provides feedback in the update center
class	UpdateCenter.HudsonDowngradeJob
class	UpdateCenter.HudsonUpgradeJob Represents the state of the upgrade activity of Jenkins core.
class	UpdateCenter.InstallationJob Represents the state of the installation activity of one plugin.
class	UpdateCenter.NoOpJob A no-op, e.g.
class	UpdateCenter.PluginDowngradeJob Represents the state of the downgrading activity of plugin.
static class	UpdateCenter.PluginEntry Deprecated.
class	UpdateCenter.RestartJenkinsJob Restarts jenkins.
static class	UpdateCenter.UpdateCenterConfiguration Strategy object for controlling the update center's behaviors.
class	UpdateCenter.UpdateCenterJob Things that installerService executes.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ID_DEFAULT ID of the default update site.
static String	ID_UPLOAD
static boolean	neverUpdate Deprecated. as of 1.333 Use UpdateSite.neverUpdate
static String	PREDEFINED_UPDATE_SITE_ID
static boolean	SKIP_PERMISSION_CHECK Escape hatch for StaplerProxy-based access control
protected ExecutorService	updateService An ExecutorService for updating UpdateSites.
static XStream2	XSTREAM

Fields inherited from interface hudson.model.Saveable

NOOP

Constructor Summary

Constructors

Constructor and Description
UpdateCenter()

Method Summary

Modifier and Type	Method and Description
Future<UpdateCenter.UpdateCenterJob>	addJob(UpdateCenter.UpdateCenterJob job)
void	configure(UpdateCenter.UpdateCenterConfiguration config) Configures update center to get plugins/updates from alternate servers, and optionally using alternate strategies for downloading, installing and upgrading.
protected UpdateSite	createDefaultUpdateSite()
static UpdateCenter	createUpdateCenter(UpdateCenter.UpdateCenterConfiguration config) Creates an update center.
void	doCancelRestart(org.kohsuke.stapler.StaplerResponse response) Cancel all scheduled jenkins restarts
org.kohsuke.stapler.HttpResponse	doConnectionStatus(org.kohsuke.stapler.StaplerRequest request) Get the current connection status.
void	doDowngrade(org.kohsuke.stapler.StaplerResponse rsp) Performs hudson downgrade.
org.kohsuke.stapler.HttpResponse	doIncompleteInstallStatus() Called to determine if there was an incomplete installation, what the statuses of the plugins are
org.kohsuke.stapler.HttpResponse	doInstallStatus(org.kohsuke.stapler.StaplerRequest request) Get the current installation status of a plugin set.
org.kohsuke.stapler.HttpResponse	doInvalidateData() Invalidates the update center JSON data for all the sites and force re-retrieval.
void	doRestart(org.kohsuke.stapler.StaplerResponse rsp) Performs hudson downgrade.
void	doSafeRestart(org.kohsuke.stapler.StaplerRequest request, org.kohsuke.stapler.StaplerResponse response) Schedules a Jenkins restart.
void	doUpgrade(org.kohsuke.stapler.StaplerResponse rsp) Schedules a Jenkins upgrade.
Api	getApi()
List<UpdateSite.Plugin>	getAvailables()
String	getBackupVersion() Returns String with version of backup .war file, if the file does not exists returns null
UpdateSite	getById(String id) Gets UpdateSite by its ID.
UpdateCenter.PluginEntry[]	getCategorizedAvailables() Deprecated.
static String	getCategoryDisplayName(String category)
UpdateSite	getCoreSource() Gets the UpdateSite from which we receive updates for jenkins.war.
String	getDefaultBaseUrl() Deprecated. TODO: revisit tool update mechanism, as that should be de-centralized, too. In the mean time, please try not to use this method, and instead ping us to get this part completed.
String	getDisplayName()
UpdateCenter.HudsonUpgradeJob	getHudsonJob() Returns latest Jenkins upgrade job.
UpdateCenter.UpdateCenterJob	getJob(int id) Gets a job by its ID.
UpdateCenter.InstallationJob	getJob(UpdateSite.Plugin plugin) Returns latest install/upgrade job for the given plugin.
List<UpdateCenter.UpdateCenterJob>	getJobs() Returns the list of UpdateCenter.UpdateCenterJob representing scheduled installation attempts.
String	getLastUpdatedString() Gets the string representing how long ago the data was obtained.
UpdateSite.Plugin	getPlugin(String artifactId) Gets the plugin with the given name from the first UpdateSite to contain it.
UpdateSite.Plugin	getPlugin(String artifactId, VersionNumber minVersion) Gets the plugin with the given name from the first UpdateSite to contain it.
List<UpdateSite.Plugin>	getPluginFromAllSites(String artifactId, VersionNumber minVersion) Gets plugin info from all available sites
List<UpdateSite.Plugin>	getPluginsWithUnavailableUpdates()
String	getSearchUrl() Returns the URL of this item relative to the parent SearchItem.
UpdateSite	getSite(String id) Alias for getById(java.lang.String).
List<UpdateSite>	getSiteList() The same as getSites() but for REST API.
PersistedList<UpdateSite>	getSites() Returns the list of UpdateSites to be used.
Object	getTarget()
List<UpdateSite.Plugin>	getUpdates()
static void	init(Jenkins h) Initializes the update center.
boolean	isDowngradable() Returns true if backup of jenkins.war exists on the hard drive
boolean	isRestartRequiredForCompletion() If any of the executed UpdateCenter.UpdateCenterJobs requires a restart to take effect, this method returns true.
boolean	isRestartScheduled() Checks if the restart operation is scheduled (which means in near future Jenkins will restart by itself)
boolean	isSiteDataReady() Whether it is probably safe to call all UpdateSite.getData() without blocking.
void	load() Loads the data from the disk into this object.
void	persistInstallStatus() Called to persist the currently installing plugin states.
void	save() Saves the configuration info to the disk.
List<FormValidation>	updateAllSites() Ensure that all UpdateSites are up to date, without requiring a user to browse to the instance.
static void	updateDefaultSite()

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

PREDEFINED_UPDATE_SITE_ID

public static final String PREDEFINED_UPDATE_SITE_ID

See Also:

Constant Field Values

ID_DEFAULT

public static final String ID_DEFAULT

ID of the default update site.

Since:

1.483; configurable via system property since 2.4

ID_UPLOAD

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static final String ID_UPLOAD

See Also:

Constant Field Values

updateService

protected final ExecutorService updateService

An ExecutorService for updating UpdateSites.

SKIP_PERMISSION_CHECK

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static boolean SKIP_PERMISSION_CHECK

Escape hatch for StaplerProxy-based access control

neverUpdate

@Deprecated
public static boolean neverUpdate

Deprecated. as of 1.333 Use UpdateSite.neverUpdate

XSTREAM

public static final XStream2 XSTREAM

Constructor Detail

UpdateCenter

public UpdateCenter()

Method Detail

createUpdateCenter

@NonNull
public static UpdateCenter createUpdateCenter(@CheckForNull
                                                       UpdateCenter.UpdateCenterConfiguration config)

Creates an update center.

Parameters:

config - Requested configuration. May be null if defaults should be used

Returns:

Created Update center. UpdateCenter by default, but may be overridden

Since:

2.4

getApi

public Api getApi()

configure

public void configure(UpdateCenter.UpdateCenterConfiguration config)

Configures update center to get plugins/updates from alternate servers, and optionally using alternate strategies for downloading, installing and upgrading.

Parameters:

config - Configuration data

See Also:

UpdateCenter.UpdateCenterConfiguration

getJobs

@Exported
 @StaplerDispatchable
public List<UpdateCenter.UpdateCenterJob> getJobs()

Returns the list of UpdateCenter.UpdateCenterJob representing scheduled installation attempts.

Returns:

can be empty but never null. Oldest entries first.

getJob

public UpdateCenter.UpdateCenterJob getJob(int id)

Gets a job by its ID. Primarily to make UpdateCenter.UpdateCenterJob bound to URL.

getJob

public UpdateCenter.InstallationJob getJob(UpdateSite.Plugin plugin)

Returns latest install/upgrade job for the given plugin.

Returns:

InstallationJob or null if not found

doConnectionStatus

@Restricted(value=org.kohsuke.accmod.restrictions.DoNotUse.class)
public org.kohsuke.stapler.HttpResponse doConnectionStatus(org.kohsuke.stapler.StaplerRequest request)

Get the current connection status.

Supports a "siteId" request parameter, defaulting to ID_DEFAULT for the default update site.

Returns:

The current connection status.

doIncompleteInstallStatus

@Restricted(value=org.kohsuke.accmod.restrictions.DoNotUse.class)
public org.kohsuke.stapler.HttpResponse doIncompleteInstallStatus()

Called to determine if there was an incomplete installation, what the statuses of the plugins are

persistInstallStatus

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public void persistInstallStatus()

Called to persist the currently installing plugin states. This allows us to support install resume if Jenkins is restarted while plugins are being installed.

doInstallStatus

@Restricted(value=org.kohsuke.accmod.restrictions.DoNotUse.class)
public org.kohsuke.stapler.HttpResponse doInstallStatus(org.kohsuke.stapler.StaplerRequest request)

Get the current installation status of a plugin set.

Supports a "correlationId" request parameter if you only want to get the install status of a set of plugins requested for install through PluginManager.doInstallPlugins(org.kohsuke.stapler.StaplerRequest).

Returns:

The current installation status of a plugin set.

getHudsonJob

public UpdateCenter.HudsonUpgradeJob getHudsonJob()

Returns latest Jenkins upgrade job.

Returns:

HudsonUpgradeJob or null if not found

getSites

@StaplerDispatchable
public PersistedList<UpdateSite> getSites()

Returns the list of UpdateSites to be used. This is a live list, whose change will be persisted automatically.

Returns:

can be empty but never null.

isSiteDataReady

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean isSiteDataReady()

Whether it is probably safe to call all UpdateSite.getData() without blocking.

Returns:

true if all data is currently ready (or absent); false if some is not ready now (but it will be loaded in the background)

getSiteList

@Exported(name="sites")
public List<UpdateSite> getSiteList()

The same as getSites() but for REST API.

getSite

@CheckForNull
public UpdateSite getSite(String id)

Alias for getById(java.lang.String).

Parameters:

id - ID of the update site to be retrieved

Returns:

Discovered UpdateSite. null if it cannot be found

getLastUpdatedString

public String getLastUpdatedString()

Gets the string representing how long ago the data was obtained. Will be the newest of all UpdateSites.

getById

@CheckForNull
public UpdateSite getById(String id)

Gets UpdateSite by its ID. Used to bind them to URL.

Parameters:

id - ID of the update site to be retrieved

Returns:

Discovered UpdateSite. null if it cannot be found

getCoreSource

@CheckForNull
public UpdateSite getCoreSource()

Gets the UpdateSite from which we receive updates for jenkins.war.

Returns:

null if no such update center is provided.

getDefaultBaseUrl

@Deprecated
public String getDefaultBaseUrl()

Deprecated. TODO: revisit tool update mechanism, as that should be de-centralized, too. In the mean time, please try not to use this method, and instead ping us to get this part completed.

Gets the default base URL.

getPlugin

@CheckForNull
public UpdateSite.Plugin getPlugin(String artifactId)

Gets the plugin with the given name from the first UpdateSite to contain it.

Returns:

Discovered UpdateSite.Plugin. null if it cannot be found

getPlugin

@CheckForNull
public UpdateSite.Plugin getPlugin(String artifactId,
                                                 @CheckForNull
                                                 VersionNumber minVersion)

Gets the plugin with the given name from the first UpdateSite to contain it.

Returns:

Discovered UpdateSite.Plugin. null if it cannot be found

getPluginFromAllSites

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
 @NonNull
public List<UpdateSite.Plugin> getPluginFromAllSites(String artifactId,
                                                                                                                                      @CheckForNull
                                                                                                                                      VersionNumber minVersion)

Gets plugin info from all available sites

Returns:

list of plugins

doUpgrade

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

Schedules a Jenkins upgrade.

Throws:

IOException

javax.servlet.ServletException

doInvalidateData

public org.kohsuke.stapler.HttpResponse doInvalidateData()

Invalidates the update center JSON data for all the sites and force re-retrieval.

Since:

1.432

doSafeRestart

public void doSafeRestart(org.kohsuke.stapler.StaplerRequest request,
                          org.kohsuke.stapler.StaplerResponse response)
                   throws IOException,
                          javax.servlet.ServletException

Schedules a Jenkins restart.

Throws:

IOException

javax.servlet.ServletException

doCancelRestart

public void doCancelRestart(org.kohsuke.stapler.StaplerResponse response)
                     throws IOException,
                            javax.servlet.ServletException

Cancel all scheduled jenkins restarts

Throws:

IOException

javax.servlet.ServletException

isRestartRequiredForCompletion

@Exported
public boolean isRestartRequiredForCompletion()

If any of the executed UpdateCenter.UpdateCenterJobs requires a restart to take effect, this method returns true.

This doesn't necessarily mean the user has scheduled or initiated the restart operation.

See Also:

isRestartScheduled()

isRestartScheduled

public boolean isRestartScheduled()

Checks if the restart operation is scheduled (which means in near future Jenkins will restart by itself)

See Also:

isRestartRequiredForCompletion()

isDowngradable

public boolean isDowngradable()

Returns true if backup of jenkins.war exists on the hard drive

doDowngrade

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

Performs hudson downgrade.

Throws:

IOException

javax.servlet.ServletException

doRestart

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

Performs hudson downgrade.

Throws:

IOException

javax.servlet.ServletException

getBackupVersion

public String getBackupVersion()

Returns String with version of backup .war file, if the file does not exists returns null

addJob

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public Future<UpdateCenter.UpdateCenterJob> addJob(UpdateCenter.UpdateCenterJob job)

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

save

public void save()

Saves the configuration info to the disk.

Specified by:

save in interface Saveable

load

public void load()
          throws IOException

Loads the data from the disk into this object.

Throws:

IOException

createDefaultUpdateSite

protected UpdateSite createDefaultUpdateSite()

getAvailables

@Exported
public List<UpdateSite.Plugin> getAvailables()

getCategorizedAvailables

@Deprecated
public UpdateCenter.PluginEntry[] getCategorizedAvailables()

Deprecated.

Returns a list of plugins that should be shown in the "available" tab, grouped by category. A plugin with multiple categories will appear multiple times in the list.

getCategoryDisplayName

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static String getCategoryDisplayName(String category)

getUpdates

public List<UpdateSite.Plugin> getUpdates()

getPluginsWithUnavailableUpdates

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public List<UpdateSite.Plugin> getPluginsWithUnavailableUpdates()

updateAllSites

public List<FormValidation> updateAllSites()
                                    throws InterruptedException,
                                           ExecutionException

Ensure that all UpdateSites are up to date, without requiring a user to browse to the instance.

Returns:

a list of FormValidation for each updated Update Site

Throws:

ExecutionException

InterruptedException

Since:

1.501

init

@Initializer(after=PLUGINS_STARTED,
             fatal=false)
public static void init(Jenkins h)
                                                                               throws IOException

Initializes the update center. This has to wait until after all plugins load, to let custom UpdateCenterConfiguration take effect first.

Throws:

IOException

updateDefaultSite

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static void updateDefaultSite()

getTarget

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public Object getTarget()

Specified by:

getTarget in interface org.kohsuke.stapler.StaplerProxy