Allow a Maven plugin to require a Java version

slawekjaranowski · slawekjaranowski · commit 3dd64abedbd7 · 2025-11-25T18:57:39.000+01:00
Introduced in Maven 4.0.0-alpha-3 - MNG-7566 Plugin tools generate it since 3.8.1 - MPLUGIN-425 As many plugins required newer JDK we can introduce it also for Maven 3.x for better error reporting
diff --git a/maven-core/src/main/java/org/apache/maven/lifecycle/internal/MojoExecutor.java b/maven-core/src/main/java/org/apache/maven/lifecycle/internal/MojoExecutor.java
@@ -184,7 +184,7 @@ private void execute(
         MojoDescriptor mojoDescriptor = mojoExecution.getMojoDescriptor();
 
         try {
-            mavenPluginManager.checkRequiredMavenVersion(mojoDescriptor.getPluginDescriptor());
+            mavenPluginManager.checkPrerequisites(mojoDescriptor.getPluginDescriptor());
         } catch (PluginIncompatibleException e) {
             throw new LifecycleExecutionException(mojoExecution, session.getCurrentProject(), e);
         }
diff --git a/maven-core/src/main/java/org/apache/maven/plugin/DefaultPluginDescriptorCache.java b/maven-core/src/main/java/org/apache/maven/plugin/DefaultPluginDescriptorCache.java
@@ -104,6 +104,7 @@ protected static PluginDescriptor clone(PluginDescriptor original) {
             clone.setName(original.getName());
             clone.setDescription(original.getDescription());
             clone.setRequiredMavenVersion(original.getRequiredMavenVersion());
+            clone.setRequiredJavaVersion(original.getRequiredJavaVersion());
 
             clone.setPluginArtifact(ArtifactUtils.copyArtifactSafe(original.getPluginArtifact()));
 
diff --git a/maven-core/src/main/java/org/apache/maven/plugin/MavenPluginManager.java b/maven-core/src/main/java/org/apache/maven/plugin/MavenPluginManager.java
@@ -71,9 +71,19 @@ MojoDescriptor getMojoDescriptor(
      * Verifies the specified plugin is compatible with the current Maven runtime.
      *
      * @param pluginDescriptor The descriptor of the plugin to check, must not be {@code null}.
+     * @deprecated Use {@link #checkPrerequisites(PluginDescriptor)} instead.
      */
+    @Deprecated
     void checkRequiredMavenVersion(PluginDescriptor pluginDescriptor) throws PluginIncompatibleException;
 
+    /**
+     * Verifies that the specified plugin's prerequisites are met.
+     *
+     * @param pluginDescriptor The descriptor of the plugin to check, must not be {@code null}.
+     * @since 3.9.12
+     */
+    void checkPrerequisites(PluginDescriptor pluginDescriptor) throws PluginIncompatibleException;
+
     /**
      * Sets up the class realm for the specified plugin. Both the class realm and the plugin artifacts that constitute
      * it will be stored in the plugin descriptor.
diff --git a/maven-core/src/main/java/org/apache/maven/plugin/MavenPluginPrerequisitesChecker.java b/maven-core/src/main/java/org/apache/maven/plugin/MavenPluginPrerequisitesChecker.java
@@ -0,0 +1,39 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.plugin;
+
+import java.util.function.Consumer;
+
+import org.apache.maven.plugin.descriptor.PluginDescriptor;
+
+/**
+ * Service responsible for checking if plugin's prerequisites are met.
+ *
+ * @since 3.9.12
+ */
+@FunctionalInterface
+public interface MavenPluginPrerequisitesChecker extends Consumer<PluginDescriptor> {
+    /**
+     *
+     * @param pluginDescriptor
+     * @throws IllegalStateException in case the checked prerequisites are not met
+     */
+    @Override
+    void accept(PluginDescriptor pluginDescriptor);
+}
diff --git a/maven-core/src/main/java/org/apache/maven/plugin/PluginIncompatibleException.java b/maven-core/src/main/java/org/apache/maven/plugin/PluginIncompatibleException.java
@@ -26,6 +26,10 @@
 public class PluginIncompatibleException extends PluginManagerException {
 
     public PluginIncompatibleException(Plugin plugin, String message) {
-        super(plugin, message, (Throwable) null);
+        this(plugin, message, null);
+    }
+
+    public PluginIncompatibleException(Plugin plugin, String message, Throwable cause) {
+        super(plugin, message, cause);
     }
 }
diff --git a/maven-core/src/main/java/org/apache/maven/plugin/internal/DefaultMavenPluginManager.java b/maven-core/src/main/java/org/apache/maven/plugin/internal/DefaultMavenPluginManager.java
@@ -35,6 +35,7 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.jar.JarFile;
+import java.util.stream.Collectors;
 import java.util.zip.ZipEntry;
 
 import org.apache.maven.RepositoryUtils;
@@ -49,6 +50,7 @@
 import org.apache.maven.plugin.ExtensionRealmCache;
 import org.apache.maven.plugin.InvalidPluginDescriptorException;
 import org.apache.maven.plugin.MavenPluginManager;
+import org.apache.maven.plugin.MavenPluginPrerequisitesChecker;
 import org.apache.maven.plugin.MavenPluginValidator;
 import org.apache.maven.plugin.Mojo;
 import org.apache.maven.plugin.MojoExecution;
@@ -169,6 +171,9 @@ public class DefaultMavenPluginManager implements MavenPluginManager {
     @Requirement
     private PluginValidationManager pluginValidationManager;
 
+    @Requirement
+    private List<MavenPluginPrerequisitesChecker> prerequisitesCheckers;
+
     private ExtensionDescriptorBuilder extensionDescriptorBuilder = new ExtensionDescriptorBuilder();
 
     private PluginDescriptorBuilder builder = new PluginDescriptorBuilder();
@@ -279,22 +284,37 @@ public MojoDescriptor getMojoDescriptor(
         return mojoDescriptor;
     }
 
-    public void checkRequiredMavenVersion(PluginDescriptor pluginDescriptor) throws PluginIncompatibleException {
-        String requiredMavenVersion = pluginDescriptor.getRequiredMavenVersion();
-        if (StringUtils.isNotBlank(requiredMavenVersion)) {
+    @Override
+    public void checkPrerequisites(PluginDescriptor pluginDescriptor) throws PluginIncompatibleException {
+        List<IllegalStateException> prerequisiteExceptions = new ArrayList<>();
+        prerequisitesCheckers.forEach(c -> {
             try {
-                if (!runtimeInformation.isMavenVersion(requiredMavenVersion)) {
-                    throw new PluginIncompatibleException(
-                            pluginDescriptor.getPlugin(),
-                            "The plugin " + pluginDescriptor.getId() + " requires Maven version "
-                                    + requiredMavenVersion);
-                }
-            } catch (RuntimeException e) {
-                logger.warn("Could not verify plugin's Maven prerequisite: " + e.getMessage());
+                c.accept(pluginDescriptor);
+            } catch (IllegalStateException e) {
+                prerequisiteExceptions.add(e);
             }
+        });
+        // aggregate all exceptions
+        if (!prerequisiteExceptions.isEmpty()) {
+            String messages = prerequisiteExceptions.stream()
+                    .map(IllegalStateException::getMessage)
+                    .collect(Collectors.joining(", "));
+            PluginIncompatibleException pie = new PluginIncompatibleException(
+                    pluginDescriptor.getPlugin(),
+                    "The plugin " + pluginDescriptor.getId() + " has unmet prerequisites: " + messages,
+                    prerequisiteExceptions.get(0));
+            // the first exception is added as cause, all other ones as suppressed exceptions
+            prerequisiteExceptions.stream().skip(1).forEach(pie::addSuppressed);
+            throw pie;
         }
     }
 
+    @Override
+    @Deprecated
+    public void checkRequiredMavenVersion(PluginDescriptor pluginDescriptor) throws PluginIncompatibleException {
+        checkPrerequisites(pluginDescriptor);
+    }
+
     public void setupPluginRealm(
             PluginDescriptor pluginDescriptor,
             MavenSession session,
diff --git a/maven-core/src/main/java/org/apache/maven/plugin/internal/MavenPluginJavaPrerequisiteChecker.java b/maven-core/src/main/java/org/apache/maven/plugin/internal/MavenPluginJavaPrerequisiteChecker.java
@@ -0,0 +1,67 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.plugin.internal;
+
+import javax.inject.Named;
+import javax.inject.Singleton;
+
+import org.apache.maven.plugin.MavenPluginPrerequisitesChecker;
+import org.apache.maven.plugin.descriptor.PluginDescriptor;
+import org.eclipse.aether.util.version.GenericVersionScheme;
+import org.eclipse.aether.version.InvalidVersionSpecificationException;
+import org.eclipse.aether.version.Version;
+import org.eclipse.aether.version.VersionConstraint;
+import org.eclipse.aether.version.VersionScheme;
+
+@Named
+@Singleton
+public class MavenPluginJavaPrerequisiteChecker implements MavenPluginPrerequisitesChecker {
+    private final VersionScheme versionScheme = new GenericVersionScheme();
+
+    @Override
+    public void accept(PluginDescriptor pluginDescriptor) {
+        String requiredJavaVersion = pluginDescriptor.getRequiredJavaVersion();
+        if (requiredJavaVersion != null && !requiredJavaVersion.isEmpty()) {
+            String currentJavaVersion = System.getProperty("java.version");
+            if (!matchesVersion(requiredJavaVersion, currentJavaVersion)) {
+                throw new IllegalStateException("Required Java version " + requiredJavaVersion
+                        + " is not met by current version: " + currentJavaVersion);
+            }
+        }
+    }
+
+    boolean matchesVersion(String requiredVersion, String currentVersion) {
+        VersionConstraint constraint;
+        try {
+            constraint = versionScheme.parseVersionConstraint(requiredVersion.equals("8") ? "1.8" : requiredVersion);
+        } catch (InvalidVersionSpecificationException e) {
+            throw new IllegalArgumentException("Invalid 'requiredJavaVersion' given in plugin descriptor", e);
+        }
+        Version current;
+        try {
+            current = versionScheme.parseVersion(currentVersion);
+        } catch (InvalidVersionSpecificationException e) {
+            throw new IllegalStateException("Could not parse current Java version", e);
+        }
+        if (constraint.getRange() == null) {
+            return constraint.getVersion().compareTo(current) <= 0;
+        }
+        return constraint.containsVersion(current);
+    }
+}
diff --git a/maven-core/src/main/java/org/apache/maven/plugin/internal/MavenPluginMavenPrerequisiteChecker.java b/maven-core/src/main/java/org/apache/maven/plugin/internal/MavenPluginMavenPrerequisiteChecker.java
@@ -0,0 +1,67 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.plugin.internal;
+
+import javax.inject.Inject;
+import javax.inject.Named;
+import javax.inject.Singleton;
+
+import org.apache.maven.plugin.MavenPluginPrerequisitesChecker;
+import org.apache.maven.plugin.descriptor.PluginDescriptor;
+import org.apache.maven.rtinfo.RuntimeInformation;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+@Named
+@Singleton
+public class MavenPluginMavenPrerequisiteChecker implements MavenPluginPrerequisitesChecker {
+    private final Logger logger = LoggerFactory.getLogger(getClass());
+    private final RuntimeInformation runtimeInformation;
+
+    @Inject
+    public MavenPluginMavenPrerequisiteChecker(RuntimeInformation runtimeInformation) {
+        super();
+        this.runtimeInformation = runtimeInformation;
+    }
+
+    @Override
+    public void accept(PluginDescriptor pluginDescriptor) {
+        String requiredMavenVersion = pluginDescriptor.getRequiredMavenVersion();
+
+        boolean isBlankVersion =
+                requiredMavenVersion == null || requiredMavenVersion.trim().isEmpty();
+
+        if (!isBlankVersion) {
+            boolean isRequirementMet = false;
+            try {
+                isRequirementMet = runtimeInformation.isMavenVersion(requiredMavenVersion);
+            } catch (IllegalArgumentException e) {
+                logger.warn(
+                        "Could not verify plugin's Maven prerequisite as an invalid version is given in "
+                                + requiredMavenVersion,
+                        e);
+                return;
+            }
+            if (!isRequirementMet) {
+                throw new IllegalStateException("Required Maven version " + requiredMavenVersion
+                        + " is not met by current version " + runtimeInformation.getMavenVersion());
+            }
+        }
+    }
+}
diff --git a/maven-core/src/main/java/org/apache/maven/plugin/version/internal/DefaultPluginVersionResolver.java b/maven-core/src/main/java/org/apache/maven/plugin/version/internal/DefaultPluginVersionResolver.java
@@ -273,7 +273,7 @@ private boolean isCompatible(PluginVersionRequest request, String version) {
         }
 
         try {
-            pluginManager.checkRequiredMavenVersion(pluginDescriptor);
+            pluginManager.checkPrerequisites(pluginDescriptor);
         } catch (PluginIncompatibleException e) {
             if (logger.isDebugEnabled()) {
                 logger.warn("Ignoring incompatible plugin version " + version, e);
diff --git a/maven-core/src/test/java/org/apache/maven/plugin/internal/MavenPluginJavaPrerequisiteCheckerTest.java b/maven-core/src/test/java/org/apache/maven/plugin/internal/MavenPluginJavaPrerequisiteCheckerTest.java
@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.plugin.internal;
+
+import org.junit.Test;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+public class MavenPluginJavaPrerequisiteCheckerTest {
+
+    @Test
+    public void testMatchesVersion() {
+        MavenPluginJavaPrerequisiteChecker checker = new MavenPluginJavaPrerequisiteChecker();
+        assertTrue(checker.matchesVersion("8", "1.8"));
+        assertTrue(checker.matchesVersion("8", "9.0.1+11"));
+        assertTrue(checker.matchesVersion("1.0", "1.8"));
+        assertTrue(checker.matchesVersion("1.8", "9.0.1+11"));
+        assertFalse(checker.matchesVersion("[1.0,2],[3,4]", "2.1"));
+        assertTrue(checker.matchesVersion("[1.0,2],[3,4]", "3.1"));
+        assertThrows(IllegalArgumentException.class, () -> checker.matchesVersion("(1.0,0)", "11"));
+    }
+}
diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/PluginDescriptor.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/PluginDescriptor.java
@@ -80,6 +80,8 @@ public class PluginDescriptor extends ComponentSetDescriptor implements Cloneabl
     // MNG-4840: set from plugin's pom.xml, not plugin.xml
     private String requiredMavenVersion;
 
+    private String requiredJavaVersion;
+
     private Plugin plugin;
 
     private Artifact pluginArtifact;
@@ -318,6 +320,14 @@ public String getRequiredMavenVersion() {
         return requiredMavenVersion;
     }
 
+    public void setRequiredJavaVersion(String requiredJavaVersion) {
+        this.requiredJavaVersion = requiredJavaVersion;
+    }
+
+    public String getRequiredJavaVersion() {
+        return requiredJavaVersion;
+    }
+
     public void setPlugin(Plugin plugin) {
         this.plugin = plugin;
     }
diff --git a/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/PluginDescriptorBuilder.java b/maven-plugin-api/src/main/java/org/apache/maven/plugin/descriptor/PluginDescriptorBuilder.java
@@ -22,6 +22,7 @@
 import java.io.Reader;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 
 import org.codehaus.plexus.component.repository.ComponentDependency;
 import org.codehaus.plexus.component.repository.ComponentRequirement;
@@ -104,6 +105,8 @@ public PluginDescriptor build(Reader reader, String source) throws PlexusConfigu
 
         pluginDescriptor.setDependencies(dependencies);
 
+        pluginDescriptor.setRequiredJavaVersion(extractRequiredJavaVersion(c).orElse(null));
+
         return pluginDescriptor;
     }
 
@@ -319,4 +322,8 @@ public PlexusConfiguration buildConfiguration(Reader configuration) throws Plexu
             throw new PlexusConfigurationException(e.getMessage(), e);
         }
     }
+
+    private Optional<String> extractRequiredJavaVersion(PlexusConfiguration c) {
+        return Optional.ofNullable(c.getChild("requiredJavaVersion")).map(PlexusConfiguration::getValue);
+    }
 }
diff --git a/maven-plugin-api/src/main/mdo/plugin.mdo b/maven-plugin-api/src/main/mdo/plugin.mdo

Original file line number	Diff line number	Diff line change
`@@ -184,7 +184,7 @@ private void execute(`
`184`	`184`	`MojoDescriptor mojoDescriptor = mojoExecution.getMojoDescriptor();`
`185`	`185`
`186`	`186`	`try {`
`187`		`- mavenPluginManager.checkRequiredMavenVersion(mojoDescriptor.getPluginDescriptor());`
	`187`	`+ mavenPluginManager.checkPrerequisites(mojoDescriptor.getPluginDescriptor());`
`188`	`188`	`} catch (PluginIncompatibleException e) {`
`189`	`189`	`throw new LifecycleExecutionException(mojoExecution, session.getCurrentProject(), e);`
`190`	`190`	`}`
Original file line number	Diff line number	Diff line change
`@@ -26,6 +26,10 @@`
`26`	`26`	`public class PluginIncompatibleException extends PluginManagerException {`
`27`	`27`
`28`	`28`	`public PluginIncompatibleException(Plugin plugin, String message) {`
`29`		`- super(plugin, message, (Throwable) null);`
	`29`	`+ this(plugin, message, null);`
	`30`	`+ }`
	`31`	`+`
	`32`	`+ public PluginIncompatibleException(Plugin plugin, String message, Throwable cause) {`
	`33`	`+ super(plugin, message, cause);`
`30`	`34`	`}`
`31`	`35`	`}`
Original file line number	Diff line number	Diff line change
`@@ -273,7 +273,7 @@ private boolean isCompatible(PluginVersionRequest request, String version) {`
`273`	`273`	`}`
`274`	`274`
`275`	`275`	`try {`
`276`		`- pluginManager.checkRequiredMavenVersion(pluginDescriptor);`
	`276`	`+ pluginManager.checkPrerequisites(pluginDescriptor);`
`277`	`277`	`} catch (PluginIncompatibleException e) {`
`278`	`278`	`if (logger.isDebugEnabled()) {`
`279`	`279`	`logger.warn("Ignoring incompatible plugin version " + version, e);`