src/site/apt/guides/introduction/introduction-to-plugin-registry.apt - maven-site - Git at Google

  ---
  Introduction to the Plugin Registry
  ---
  John Casey
  ---
  29-July-2005
  ---

 Introduction to the Plugin Registry

   The Maven 2 plugin registry (~/.m2/plugin-registry.xml) is a mechanism to
   help the user exert some control over their build environment. Rather than
   simply fetching the latest version of every plugin used in a given build,
   this registry allows the user to peg a plugin to a particular version, and
   only update to newer versions under certain restricted circumstances. There
   are various ways to configure or bypass this feature, and the feature itself
   can be managed on either a per-user or global level.

 * <<Warning!>>

   The plugin registry is currently in a semi-dormant state within Maven 2. This
   is because it has been shown to have some subtle behavior that is not quite
   intuitive. While we believe it's important to allow the user to pin down which
   version of a particular plugin is used across all builds, it's not clear that
   this type of information should be machine-specific (i.e. tied to something
   outside the project directory).

   Users should be cautious when attempting to use the <<<plugin-registry.xml>>>.
   Redesign of this feature in upcoming 2.1 and/or 2.2 is likely.

   For now, Maven <should> keep using the same version of a plugin - assuming a
   different version is not specified in the POM - until the user chooses to run
   with the <<<-U>>> option explicitly enabled.

 * A Tour of plugin-registry.xml

   The plugin registry file (per-user: ~/.m2/plugin-registry.xml, global:
   $M2_HOME/conf/plugin-registry.xml) contains a set of plugin-version
   registrations, along with some configuration parameters for the registry
   itself.

   Currently, the plugin registry supports configuration options for the
   following:

   * <<updateInterval>> - Determines how often (or whether) the registered
     plugins are checked for updates.

     Combined with the <<lastChecked>> plugin attribute, this determines whether
     a particular plugin will be checked for updates during a given build. Valid
     settings are: never, always, and interval:TTT (TTT is a short specification
     for a time interval, which follows the pattern /([0-9]+[wdhm])+/). Intervals
     are specified down to the minute resolution. An example of an interval
     specification might be:

     <<<interval:4w2h30m>>> (check every 4 weeks, 2 hours, and 30 minutes)

   * <<autoUpdate>> - Specifies whether the user should be prompted before
     registering plugin-version updates. This is a boolean value, accepting
     true/false.

   * <<checkLatest>> - Specifies whether the LATEST artifact metadata should
     be consulted while determining versions for <unregistered> plugins.

     LATEST metadata is always published when a plugin is installed or deployed
     to a repository, and so will always reference the newest copy of the plugin,
     regardless of whether this is a snapshot version or not.

     <NOTE:> Registered plugins will currently only ever be updated with the
     results of RELEASE metadata resolution.

   Obviously, the plugin registry also contains information about resolved plugin
   versions. The following information is tracked for each registered plugin:

   * <<groupId>> - The plugin's group id.

   * <<artifactId>> - The plugin's artifact id.

   * <<lastChecked>> - The timestamp from the last time updates were checked for
     this plugin.

   * <<useVersion>> - The currently registered version for this plugin. This is
     the version Maven will use when executing this plugin's mojos.

   * <<rejectedVersions>> - A list of versions discovered for this plugin which
     have been rejected by the user. This keeps Maven from continually prompting
     the user to update a given plugin to the same new version.

 * Using (or not) the Plugin Registry

   There are many ways you can override the default plugin registry settings.
   Often, this will be desirable for a single, one-off build of a project that
   deviates from your normal environment configuration. However, before discussing
   these options, it's important to understand how the plugin registry resolves
   versions for unregistered plugins, along with plugins in need of an update
   check.

 ** Resolving Plugin Versions

   The plugin registry uses a relatively straightforward algorithm for resolving
   plugin versions. However, considerations for when to check, when to prompt the
   user, and when to persist resolved plugin versions complicate this
   implementation considerably. In general, plugin versions are resolved using a
   four-step process:

   [[1]] Check for a plugin configuration in the MavenProject instance. Any
         plugin configuration found in the MavenProject is treated as authoritative,
         and will stop the plugin-version resolution/persistence process when
         found.

   [[2]] If the plugin registry is enabled, check it for an existing registered
         version. If the plugin has been registered, a combination of the
         updateInterval configuration and the lastChecked attribute (on the
         plugin) determine whether the plugin needs to be checked for updates.
         If the plugin doesn't need an update check, the registered version is
         used.

         If the plugin is due for an update check, the plugin-artifact's RELEASE
         metadata is resolved. Resolution of this metadata may trigger a prompt
         to notify the user of the new version, and/or persistence of the new
         version in the registry. If the update is performed, the lastChecked
         attribute is updated to reflect this.

   [[3]] <If> the <<checkLatest>> configuration is set to <<<true>>>, or the
         <<<'--check-plugin-latest'>>> CLI option (discussed later) is
         provided, then the LATEST artifact metadata is resolved for the plugin.

         If this metadata is resolved successfully, that version is used.
         This may trigger a prompt to ask the user whether to register the
         plugin, and a successive persistence step for the new plugin version.

   [[4]] If the version still has not been resolved, RELEASE artifact
         metadata is checked for the plugin. If this metadata resolves
         successfully, it is the version used. This may also trigger a prompt
         to ask the user whether to register the plugin, and a persistence step
         registering the new plugin version.

   I've alluded to prompting the user and persisting the plugin version into
   the registry. Now, let's examine the circumstances under which these steps
   actually take place.

   There are two cases where the user may be prompted to change the plugin
   registry; when the plugin is not registered, and when the plugin is registered,
   but an updated version is discovered. By default, the user is prompted to save
   the resolved version for each plugin, with the option of specifying that a
   decision should be remembered and applied to all (either yes to all, or no
   to all) plugins registry updates. However, it is also possible to bypass
   this behavior in the following ways:

   * Specify <<autoUpdate>> == <<<true>>> in the plugin-registry.xml. This
     configuration parameter means that the user is not prompted, and all
     updated/discovered versions are to be persisted.

   * Specify <<<'--batch-mode'>>> (or <<<'-B'>>>) from the command line.
     This functions in the same way as the <<autoUpdate>> config parameter
     above.

   * Specify <<<'--no-plugin-updates'>>> | <<<'-npu'>>> from the command line.
     This prevents any updates or new registrations from taking place, but
     existing plugin versions in the registry will be used when available.

   * Specify <<<'--check-plugin-updates'>>> | <<<'--update-plugins'>>> |
     <<<'-up'>>> | <<<'-cpu'>>> (synonyms) from the command line.

   * Specify <<<'--no-plugin-registry'>>> | <<<'-npr'>>> from the command line.
     This prevents resolution of plugin versions using the plugin-registry.xml
     file. The plugin version will be resolved either from the project or
     from the repository in this case.

   * Specify <<usePluginRegistry>> == <<<false>>> in the settings.xml. This
     configuration parameter will disable use of the plugin registry for the
     entire build environment, as opposed to the immediate build execution
     (as in the case of the corresponding command line switch above).

     These force all registered plugins to be updated. The user will still
     be prompted to approve plugin versions, unless one of the above switches
     is also provided.

 ** Summary of Command Line Options for the Plugin Registry

   The following summary of command line options is provided for quick reference:

   * <<<--no-plugin-registry>>> - Bypass the plugin registry.

     <Synonym:> <<<-npr>>>

   * <<<--no-plugin-latest>>> - Don't check the LATEST artifact metadata when
     resolving plugin versions, regardless of the value of <<useLatest>> in
     the plugin-registry.xml file.

     <Synonym:> <<<-npl>>>

   * <<<--check-plugin-latest>>> - Check the LATEST artifact metadata when
     resolving plugin versions, regardless of the value of <<useLatest>> in
     the plugin-registry.xml file.

     <Synonym:> <<<-cpl>>>

   * <<<--no-plugin-updates>>> - Do not search for updated versions of registered
     plugins. Only use the repository to resolve unregistered plugins.

     <Synonym:> <<<-npu>>>

   * <<<--check-plugin-updates>>> - Force the plugin version manager to check for
     updated versions of any registered plugins, currently using RELEASE metadata
     <<only>>.

     <Synonyms:> <<<--update-plugins>>> <<<-up>>> <<<-cpu>>>
	---
	Introduction to the Plugin Registry
	---
	John Casey
	---
	29-July-2005
	---

	Introduction to the Plugin Registry

	The Maven 2 plugin registry (~/.m2/plugin-registry.xml) is a mechanism to
	help the user exert some control over their build environment. Rather than
	simply fetching the latest version of every plugin used in a given build,
	this registry allows the user to peg a plugin to a particular version, and
	only update to newer versions under certain restricted circumstances. There
	are various ways to configure or bypass this feature, and the feature itself
	can be managed on either a per-user or global level.

	* <<Warning!>>

	The plugin registry is currently in a semi-dormant state within Maven 2. This
	is because it has been shown to have some subtle behavior that is not quite
	intuitive. While we believe it's important to allow the user to pin down which
	version of a particular plugin is used across all builds, it's not clear that
	this type of information should be machine-specific (i.e. tied to something
	outside the project directory).

	Users should be cautious when attempting to use the <<<plugin-registry.xml>>>.
	Redesign of this feature in upcoming 2.1 and/or 2.2 is likely.

	For now, Maven <should> keep using the same version of a plugin - assuming a
	different version is not specified in the POM - until the user chooses to run
	with the <<<-U>>> option explicitly enabled.

	* A Tour of plugin-registry.xml

	The plugin registry file (per-user: ~/.m2/plugin-registry.xml, global:
	$M2_HOME/conf/plugin-registry.xml) contains a set of plugin-version
	registrations, along with some configuration parameters for the registry
	itself.

	Currently, the plugin registry supports configuration options for the
	following:

	* <<updateInterval>> - Determines how often (or whether) the registered
	plugins are checked for updates.

	Combined with the <<lastChecked>> plugin attribute, this determines whether
	a particular plugin will be checked for updates during a given build. Valid
	settings are: never, always, and interval:TTT (TTT is a short specification
	for a time interval, which follows the pattern /([0-9]+[wdhm])+/). Intervals
	are specified down to the minute resolution. An example of an interval
	specification might be:

	<<<interval:4w2h30m>>> (check every 4 weeks, 2 hours, and 30 minutes)

	* <<autoUpdate>> - Specifies whether the user should be prompted before
	registering plugin-version updates. This is a boolean value, accepting
	true/false.

	* <<checkLatest>> - Specifies whether the LATEST artifact metadata should
	be consulted while determining versions for <unregistered> plugins.

	LATEST metadata is always published when a plugin is installed or deployed
	to a repository, and so will always reference the newest copy of the plugin,
	regardless of whether this is a snapshot version or not.

	<NOTE:> Registered plugins will currently only ever be updated with the
	results of RELEASE metadata resolution.

	Obviously, the plugin registry also contains information about resolved plugin
	versions. The following information is tracked for each registered plugin:

	* <<groupId>> - The plugin's group id.

	* <<artifactId>> - The plugin's artifact id.

	* <<lastChecked>> - The timestamp from the last time updates were checked for
	this plugin.

	* <<useVersion>> - The currently registered version for this plugin. This is
	the version Maven will use when executing this plugin's mojos.

	* <<rejectedVersions>> - A list of versions discovered for this plugin which
	have been rejected by the user. This keeps Maven from continually prompting
	the user to update a given plugin to the same new version.

	* Using (or not) the Plugin Registry

	There are many ways you can override the default plugin registry settings.
	Often, this will be desirable for a single, one-off build of a project that
	deviates from your normal environment configuration. However, before discussing
	these options, it's important to understand how the plugin registry resolves
	versions for unregistered plugins, along with plugins in need of an update
	check.

	** Resolving Plugin Versions

	The plugin registry uses a relatively straightforward algorithm for resolving
	plugin versions. However, considerations for when to check, when to prompt the
	user, and when to persist resolved plugin versions complicate this
	implementation considerably. In general, plugin versions are resolved using a
	four-step process:

	[[1]] Check for a plugin configuration in the MavenProject instance. Any
	plugin configuration found in the MavenProject is treated as authoritative,
	and will stop the plugin-version resolution/persistence process when
	found.

	[[2]] If the plugin registry is enabled, check it for an existing registered
	version. If the plugin has been registered, a combination of the
	updateInterval configuration and the lastChecked attribute (on the
	plugin) determine whether the plugin needs to be checked for updates.
	If the plugin doesn't need an update check, the registered version is
	used.

	If the plugin is due for an update check, the plugin-artifact's RELEASE
	metadata is resolved. Resolution of this metadata may trigger a prompt
	to notify the user of the new version, and/or persistence of the new
	version in the registry. If the update is performed, the lastChecked
	attribute is updated to reflect this.

	[[3]] <If> the <<checkLatest>> configuration is set to <<<true>>>, or the
	<<<'--check-plugin-latest'>>> CLI option (discussed later) is
	provided, then the LATEST artifact metadata is resolved for the plugin.

	If this metadata is resolved successfully, that version is used.
	This may trigger a prompt to ask the user whether to register the
	plugin, and a successive persistence step for the new plugin version.

	[[4]] If the version still has not been resolved, RELEASE artifact
	metadata is checked for the plugin. If this metadata resolves
	successfully, it is the version used. This may also trigger a prompt
	to ask the user whether to register the plugin, and a persistence step
	registering the new plugin version.

	I've alluded to prompting the user and persisting the plugin version into
	the registry. Now, let's examine the circumstances under which these steps
	actually take place.

	There are two cases where the user may be prompted to change the plugin
	registry; when the plugin is not registered, and when the plugin is registered,
	but an updated version is discovered. By default, the user is prompted to save
	the resolved version for each plugin, with the option of specifying that a
	decision should be remembered and applied to all (either yes to all, or no
	to all) plugins registry updates. However, it is also possible to bypass
	this behavior in the following ways:

	* Specify <<autoUpdate>> == <<<true>>> in the plugin-registry.xml. This
	configuration parameter means that the user is not prompted, and all
	updated/discovered versions are to be persisted.

	* Specify <<<'--batch-mode'>>> (or <<<'-B'>>>) from the command line.
	This functions in the same way as the <<autoUpdate>> config parameter
	above.

	* Specify <<<'--no-plugin-updates'>>> \| <<<'-npu'>>> from the command line.
	This prevents any updates or new registrations from taking place, but
	existing plugin versions in the registry will be used when available.

	* Specify <<<'--check-plugin-updates'>>> \| <<<'--update-plugins'>>> \|
	<<<'-up'>>> \| <<<'-cpu'>>> (synonyms) from the command line.

	* Specify <<<'--no-plugin-registry'>>> \| <<<'-npr'>>> from the command line.
	This prevents resolution of plugin versions using the plugin-registry.xml
	file. The plugin version will be resolved either from the project or
	from the repository in this case.

	* Specify <<usePluginRegistry>> == <<<false>>> in the settings.xml. This
	configuration parameter will disable use of the plugin registry for the
	entire build environment, as opposed to the immediate build execution
	(as in the case of the corresponding command line switch above).

	These force all registered plugins to be updated. The user will still
	be prompted to approve plugin versions, unless one of the above switches
	is also provided.

	** Summary of Command Line Options for the Plugin Registry

	The following summary of command line options is provided for quick reference:

	* <<<--no-plugin-registry>>> - Bypass the plugin registry.

	<Synonym:> <<<-npr>>>

	* <<<--no-plugin-latest>>> - Don't check the LATEST artifact metadata when
	resolving plugin versions, regardless of the value of <<useLatest>> in
	the plugin-registry.xml file.

	<Synonym:> <<<-npl>>>

	* <<<--check-plugin-latest>>> - Check the LATEST artifact metadata when
	resolving plugin versions, regardless of the value of <<useLatest>> in
	the plugin-registry.xml file.

	<Synonym:> <<<-cpl>>>

	* <<<--no-plugin-updates>>> - Do not search for updated versions of registered
	plugins. Only use the repository to resolve unregistered plugins.

	<Synonym:> <<<-npu>>>

	* <<<--check-plugin-updates>>> - Force the plugin version manager to check for
	updated versions of any registered plugins, currently using RELEASE metadata
	<<only>>.

	<Synonyms:> <<<--update-plugins>>> <<<-up>>> <<<-cpu>>>