Class AbstractUpgradeGoal

java.lang.Object
org.apache.maven.cling.invoker.mvnup.goals.AbstractUpgradeGoal
All Implemented Interfaces:
Goal
Direct Known Subclasses:
Apply, Check
public abstract class AbstractUpgradeGoal extends Object implements Goal
Base class for upgrade goals containing shared functionality. Subclasses only differ in whether they save modifications to disk.

Supported Upgrades

Model Version Upgrades

  • 4.0.0 → 4.1.0: Upgrades Maven 3.x POMs to Maven 4.1.0 format

4.0.0 → 4.1.0 Upgrade Process

  1. Namespace Update: Changes namespace from Maven 4.0.0 to 4.1.0 for all elements
  2. Schema Location Update: Updates xsi:schemaLocation to Maven 4.1.0 XSD
  3. Module Conversion: Converts <modules> to <subprojects> and <module> to <subproject>
  4. Model Version Update: Updates <modelVersion> to 4.1.0

Default Behavior

If no specific options are provided, the tool applies --fix-model and --plugins by default to ensure Maven 4 compatibility.

All-in-One Option

The --all option is a convenience flag equivalent to --model 4.1.0 --infer --fix-model --plugins. It performs a complete upgrade to Maven 4.1.0 with all optimizations, compatibility fixes, and plugin upgrades.

Maven 4 Compatibility Fixes

When --fix-model option is enabled (or by default), applies fixes for Maven 4 compatibility issues:
  • Unsupported combine.children Attributes: Changes 'override' to 'merge' (Maven 4 only supports 'append' and 'merge')
  • Unsupported combine.self Attributes: Changes 'append' to 'merge' (Maven 4 only supports 'override', 'merge', and 'remove')
  • Duplicate Dependencies: Removes duplicate dependency declarations that Maven 4 strictly validates
  • Duplicate Plugins: Removes duplicate plugin declarations that Maven 4 strictly validates
  • Unsupported Repository Expressions: Comments out repositories with expressions not supported by Maven 4
  • Incorrect Parent Relative Paths: Fixes parent.relativePath that point to non-existent POMs by searching the project structure
  • .mvn Directory Creation: Creates .mvn directory in root when not upgrading to 4.1.0 to avoid root directory warnings

Plugin Upgrades

When --plugins option is enabled (or by default), upgrades plugins known to fail with Maven 4:
  • maven-exec-plugin: Upgrades to version 3.2.0 or higher
  • maven-enforcer-plugin: Upgrades to version 3.0.0 or higher
  • flatten-maven-plugin: Upgrades to version 1.2.7 or higher
  • maven-shade-plugin: Upgrades to version 3.5.0 or higher
  • maven-remote-resources-plugin: Upgrades to version 3.0.0 or higher
Plugin versions are upgraded in both <build><plugins> and <build><pluginManagement><plugins> sections. If a plugin version is defined via a property, the property value is updated instead.

Inference Optimizations (Optional)

When --infer option is enabled, applies inference optimizations to remove redundant information:

Limited Inference for 4.0.0 Models (Maven 3.x POMs)

  • Child GroupId Removal: Removes child <groupId> when it matches parent groupId
  • Child Version Removal: Removes child <version> when it matches parent version

Full Inference for 4.1.0+ Models

  • ModelVersion Removal: Removes <modelVersion> element (inference enabled)
  • Root Attribute: Adds root="true" attribute to root project
  • Parent Element Trimming:
    • Removes parent <groupId> when child has no explicit groupId
    • Removes parent <version> when child has no explicit version
    • Removes parent <artifactId> when it can be inferred from relativePath
  • Managed Dependencies Cleanup: Removes managed dependencies pointing to project artifacts
  • Dependency Inference:
    • Removes dependency <version> when it points to a project artifact
    • Removes dependency <groupId> when it points to a project artifact
    • Applies to main dependencies, profile dependencies, and plugin dependencies
  • Subprojects List Removal: Removes redundant <subprojects> lists that match direct child directories

Multi-Module Project Support

  • POM Discovery: Recursively discovers all POM files in the project structure
  • GAV Resolution: Computes GroupId, ArtifactId, Version for all project artifacts with parent inheritance
  • Cross-Module Inference: Uses knowledge of all project artifacts for intelligent inference decisions
  • RelativePath Resolution: Resolves parent POMs via relativePath for artifactId inference

Format Preservation

  • Whitespace Preservation: Maintains original formatting when removing elements
  • Comment Preservation: Preserves XML comments and processing instructions
  • Line Separator Handling: Uses system-appropriate line separators

  • Constructor Details

  • Method Details

    • execute

      public int execute(UpgradeContext context) throws Exception
      Executes the upgrade goal. Template method that calls doUpgrade and optionally saves modifications.
      Specified by:
      execute in interface Goal
      Throws:
      Exception

    • doUpgrade

      protected int doUpgrade(UpgradeContext context, String targetModel, Map<Path, org.jdom2.Document> pomMap)
      Performs the upgrade logic using the strategy pattern. Delegates to StrategyOrchestrator for coordinated strategy execution.

    • shouldSaveModifications

      protected abstract boolean shouldSaveModifications()
      Determines whether modifications should be saved to disk. Apply goals return true, Check goals return false.

    • saveModifications

      protected void saveModifications(UpgradeContext context, Map<Path, org.jdom2.Document> pomMap)
      Saves the modified documents to disk.

    • createMvnDirectoryIfNeeded

      protected void createMvnDirectoryIfNeeded(UpgradeContext context)
      Creates .mvn directory in the root directory if it doesn't exist and the model isn't upgraded to 4.1.0. This avoids the warning about not being able to find the root directory.