How to Disable a Maven Plugin Defined in a Parent POM

1. Overview

Maven allows us to build a project using the concept of inheritance. When a parent POM defines a plugin, all of the child modules inherit it.

But what happens if we don’t want to inherit a plugin from a parent POM, and we can’t amend the parent POM?

In this tutorial, we’ll look at a couple of different approaches to disabling a Maven plugin, specifically the Maven Enforcer Plugin, defined in a parent POM.

2. When Would We Disable a Plugin Defined in the Parent POM?

Before we go any further, let’s think about why we might need to do this.

Maven prefers convention over configuration. We need to remember that while disabling a plugin might be the quickest solution for us, it might not be the best solution for the project.

The need to disable a plugin in the parent POM may arise when the original author of the Maven project did not foresee our situation, and we have no way to amend the parent module ourselves.

Let’s say the original author assumed that a particular file should always exist. However, it doesn’t make sense for our module to have this file. For example, the parent POM might enforce the presence of a license file in each module, which we don’t have. Rather than add an empty file, which may be confusing, we want to disable the rule enforcement.

Let’s set up this scenario by adding a parent module in our Maven project that implements maven-enforcer-plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <version>3.0.0</version>
</plugin>

Next, let’s add an execution to the plugin to enforce a rule that a file named file-that-must-exist.txt must exist within each module’s src directory:

<executions>
    <execution>
        <id>enforce-file-exists</id>
	<goals>
	    <goal>enforce</goal>
	</goals>
	<configuration>
	    <rules>
	        <requireFilesExist>
		    <files>
		        <file>${project.basedir}/src/file-that-must-exist.txt</file>
		    </files>
		</requireFilesExist>
            </rules>
	</configuration>
    </execution>
</executions>

If file-that-must-exist.txt doesn’t exist, then the build will fail.

As child modules inherit plugins from their parents, all of the child modules must abide by this rule.

Let’s take a look at a couple of ways we could disable this rule in our child POM.

3. How Do We Disable a Plugin Defined in the Parent POM?

First, let’s assume that restructuring the Maven project or changing the parent POM aren’t acceptable solutions. If we could amend the parent module, then we could resolve this issue by implementing a pluginManagement section in the parent POM.

We might be unable to amend the parent module because we don’t own the project, so we’re not authorized to make changes outside of our module. It could be due to time constraints – restructuring a project takes time, so it’s just more convenient to disable a plugin in a child module.

Further, we’re going to assume that the plugin actually needs to be disabled. Lots of plugins will run with no issues, even on modules they’re not intended for.

For example, let’s say that we have a plugin that copies Java files. If we have a child project with no Java files, then the plugin is likely to simply not copy any files. It’ll do this without causing a problem. In this case, it’s simpler and more conventional to leave the plugin running.

Let’s assume that after considering the above, we definitely need to disable the plugin with our module.

One way we can do this is to configure the skip parameter.

3.1. Configure the Skip Parameter

Many plugins feature a skip parameter. We can use the skip parameter to disable the plugin.

If we take a look at the documentation for the maven-enforcer-plugin, we can see that it has a skip parameter that we can implement.

Support for the skip parameter should be the first thing we check because it is the simplest solution and the most conventional.

Let’s add an empty child module, only containing the POM. If we build the module using a mvn clean install command, we see that the build fails. This is because file-that-must-exist.txt doesn’t exist within our module, which was required due to inheriting the rule from our parent module.

Let’s add the following lines to the child POM to enable the skip parameter:

<plugin>
    <artifactId>maven-enforcer-plugin</artifactId>
    <configuration>
        <skip>true</skip>
    </configuration>
</plugin>

Now, if we run the project, we see that the build is successful.

However, not all plugins will have a skip parameter. So if we’re using a plugin that doesn’t have one, what can we do instead?

3.2. Remove the Phase Parameter

A Maven goal only runs when bound to a build phase.

In our parent POM, we’ve configured the enforce goal to run with the id enforce-file-exists.

As we haven’t specified a phase parameter for enforce-file-exists, it’ll use the default value for the enforce goal. We can see from the documentation that the default is the validate build phase.

We can execute the goal in an alternative build phase by specifying an alternative value for the phase parameter.

Using this to our advantage, we can set the phase parameter to a value that doesn’t exist. This means that the build phase would never be executed. Thus the goal wouldn’t be executed, effectively disabling the plugin:

<plugin>
    <artifactId>maven-enforcer-plugin</artifactId>
    <executions>
        <execution>
            <id>enforce-file-exists</id>
	    <phase>any-value-that-is-not-a-phase</phase>
	</execution>
    </executions>
</plugin>

To make it clear to somebody looking at our code later, we’d want to set phase to a clear name such as “none” or “null”.

However, perhaps the clearest way to do this would be to clear the phase parameter altogether:

<execution>
    <id>enforce-file-exists</id>
    <phase/>
</execution>

As the phase of the execution empty is now empty, the goal won’t be bound to a build phase that runs. This effectively disables the plugin.

We can see that when we run the build, enforce-file-exists doesn’t run at all for our child module.

4. Conclusion

In this article, we discussed why we might choose to disable a plugin defined in a parent POM. We saw that disabling the plugin might not always be the best thing to do, as Maven prefers convention over configuration.

Then, we looked at a simple example where we disabled the maven-enforcer-plugin declared by a parent POM.

Firstly, we demonstrated that we could configure a plugin’s skip parameter if the plugin has one. We found that this was the most conventional approach.

Finally, we learned that clearing the phase parameter for the plugin would effectively disable it.