Maven Enforcer

The plugin has one goal, enforcer:enforce, which runs a list of rules against the current project and the current Maven runtime. A rule passes silently or throws an exception with a message, and the goal turns the exceptions into a build failure. The goal’s default phase is validate, the first phase of the build lifecycle, so the checks run before anything is compiled. How a plugin is declared, pinned and bound is the subject of Plugins & Their Configuration; here is the tidepool parent POM with the plugin pinned in pluginManagement and a first execution in build/plugins:

Each child of <rules> is the name of a rule, and its own children are the rule’s parameters. The sample output of mvn validate on Maven 3.10.0 (filtered to the lines of the first module):

Source: The enforcer:enforce mojo

Two details are visible here. The rules are numbered in the order of the POM and named by their implementing class, which is what to look for in an error. And the rules of the three child modules are not listed: a rule can declare that its result is the same in every module (the version rules do, because the Maven and Java runtime does not change inside one build), and the plugin then runs it once per build. The rules that look at the project, such as the dependency rules below, run again in each module. The parameter ignoreCache (user property enforcer.ignoreCache) switches that off; with -Denforcer.ignoreCache=true the RequireMavenVersion line appears under every module (run here: it did, for tidepool-parent, tidepool-model and tidepool-engine).

A failing rule stops the build in the module where it fails. To see one, the Java requirement of the parent POM was temporarily changed to [27,), a JDK newer than the one running:

(... marks the usual Maven help lines that were cut.) Without message, a rule prints its own explanation, as above; with message, the text you give is shown instead (see the Tidepool needs Maven ... text in the extension section below). Three switches change what a failure does:

By default all failing rules of an execution are reported together, which is useful when you are fixing a list of problems. With failFast the execution stops at the first failing rule (see the dependency example below).

Source: The enforcer:enforce mojo

requireMavenVersion and requireJavaVersion take a version in the Enforcer’s range syntax, the standard Maven range syntax with one change: a bare 3.9.0 means at least 3.9.0 (in a dependency it would only recommend a version). So [3.9.0,) and 3.9.0 mean the same, [17,21] is an inclusive range and (,1.0],[1.2,) is a union of ranges. The Java version is normalised before the comparison (1.5.0_07-b03 becomes 1.5.0-7), and 8 can be written for 1.8. requireJavaVersion accepts display to print the normalised value. The message in the failure above, version 26 which is not in the allowed range [27,), shows the JDK home and the version it found, which is the quickest way to find out which JDK Maven is really using (see Compiling & Toolchains for how that relates to release and toolchains).

The requirement [3.9.0,) is a minimum, not an exact version; to pin the exact Maven that a team uses, see Maven Wrapper. The other environment rules are requireJavaVendor, requireOS (family, name, architecture, version), requireEnvironmentVariable and requireActiveProfile. They follow the same pattern and were not run here.

Source: Enforcer version range specification

Source: requireJavaVersion

These are the rules that pay for the plugin. They look at the resolved dependency tree of each module (the mediation rules are in Dependencies, Scopes & Mediation). The second execution of the tidepool parent:

Source: Enforcer built-in rules

For the unmodified tidepool modules every rule passes. To see them work, tidepool-engine gets a dependency on httpclient 4.5.14 (declared before commons-csv), which brings its own, older commons-codec and a commons-logging:

This added dependency is this page’s own lab setup, not an example from the Maven documentation.

Three rules failed in one run, and each shows the paths to the problem, which dependency:tree would only show after you knew where to look.

Source: dependencyConvergence

Source: requireUpperBoundDeps

Source: bannedDependencies

The fix is in the POMs, not in the rule: manage the version of the conflicting artifact so that every path gets the same one (see Dependency Management & BOMs), exclude the unwanted dependency, and add the replacement. In tidepool-engine:

and all five rules pass again (run here, BUILD SUCCESS). failFast changes the report: with -Denforcer.failFast=true on the broken POM, and the convergence rule set to WARN as in the previous section, the log showed Rule 0 ... warned and Rule 1 ... RequireUpperBoundDeps failed, and no Rule 2.

Source: Introduction to the Dependency Mechanism: Dependency Management

Source: Maven: Optional Dependencies and Dependency Exclusions, Dependency Exclusions

The last execution of the tidepool parent checks the build definition:

Source: requirePluginVersions

Source: requireProperty

Source: Enforcer built-in rules

Beyond the built-in rules, the plugin site lists two third-party rule sets: the Sonatype OSS Index rule to ban vulnerable dependencies, and MojoHaus Extra Enforcer Rules. Neither was run here (the first needs access to an external vulnerability service).

enforcer:enforce also works without any POM configuration, which is a way to test a rule on a project that does not use the plugin yet. In an empty project with only coordinates:

Without -Denforcer.rules and without configuration the goal refuses to run: No rules are configured. Use the skip flag if you want to disable execution. (failIfNoRules). When the rule is configured in the POM, the same option selects it, but read this carefully: if the configuration is inside an <execution>, you must name the execution (mvn enforcer:enforce@enforce-hygiene), as with any goal bound with an id, because the goal run from the command line is the default-cli execution, which only sees plugin-level configuration. Run here, mvn enforcer:enforce@enforce-hygiene -pl tidepool-model ran the four rules of that execution.

A gotcha: -Denforcer.rules=requireJavaVersion on a normal mvn validate applies to every execution bound to the build, including the ones that do not configure that rule, and on Maven 3.10.0 the enforce-dependencies execution failed with an internal error (Cannot invoke "org.apache.maven.artifact.versioning.VersionRange.getRecommendedVersion()" because "versionRange" is null) (apparently because the rule was created without its version). Select rules with enforcer:enforce@id or rulesToSkip (which worked: with -Denforcer.skipRules=requireJavaVersion,requirePluginVersions the other rules ran and the build succeeded).

Source: Check specific rule via CLI

The plugin is configured in the POM, so a rule that must hold for a whole organisation has to be inherited through a parent POM. The Enforcer Extension keeps the same rules outside the POM, in the project’s .mvn directory (see Extensions and Configuring Maven). Register the extension in .mvn/extensions.xml:

and put the rules into .mvn/enforcer-extension.xml, whose content is like an <execution> of the plugin (the default id is default-extension and the default phase validate):

The version requirement was deliberately set higher than the Maven used, with the enforcer section removed from the parent POM, to see the extension work:

That is Maven 3.10.0 and also Maven 3.9.16 (the run printed the same failure, preceded by messages about the extension jar being verified in the local repository). On Maven 4.0.0-rc-7 the build passed, as it should: 4.0.0 satisfies [3.11.0,), and the extension added the enforcer:3.6.3:enforce (enforce-maven) execution to all four projects. The extension adds the execution to every project, so no module needs an enforcer section at all, and -Denforcer.skip skips it (run here: the header was printed and no Rule line). The extension’s documentation also names a third way to register it, in the POM, and says that the plugin makes more sense in that case.

Source: Enforcer extension: usage

Source: Enforcer extension: .mvn/enforcer-extension.xml

When no built-in rule fits, write one. A rule is a class in a normal JAR project that extends AbstractEnforcerRule (available since API 3.2.1), carries a @Named("ruleName") annotation whose name starts with a lowercase letter, and implements execute(): return when the check passes, throw EnforcerRuleException with a helpful message when it fails. Fields (or setters) become configuration parameters, and Maven components such as MavenProject or MavenSession are injected with @Inject. The enforcer plugin shares its class loader with the rule, so enforcer-api and Maven core are provided scope, and a sisu-maven-plugin main-index execution generates the index that lets Maven find the @Named class. The tidepool project’s rule checks the stations file that the StationReader reads:

(The imports are java.io.IOException, java.nio.file.Files, java.nio.file.Path, java.util.List, javax.inject.Inject, javax.inject.Named, the two enforcer API classes org.apache.maven.enforcer.rule.api.AbstractEnforcerRule and EnforcerRuleException, and org.apache.maven.project.MavenProject.) Its POM, a JAR project with release 17, declares enforcer-api 3.6.3, maven-core 3.9.15 and javax.inject 1 as provided dependencies and the plugin org.eclipse.sisu:sisu-maven-plugin:1.0.0 with the goal main-index. After mvn install the JAR contained META-INF/sisu/javax.inject.Named with the single line io.tidepool.rules.RequireStationsCsv.

Source: Writing a custom rule: Implementation of custom Enforcer Rule

The rule is used by adding the JAR as a dependency of the enforcer plugin and writing the rule’s name in <rules>, in tidepool-engine/pom.xml:

The same failure was printed on Maven 3.10.0, 3.9.16 and 4.0.0-rc-7; with minStations 3 the rule passed (Rule 0: io.tidepool.rules.RequireStationsCsv passed). getCacheId() is there on purpose. According to the documentation a rule that is not cacheable need not override it, and a cacheable rule returns an id that is unique for the parameters and conditions that change its result; results are stored per id. A rule that reads the project must therefore include the module in its id, as above. The rule artifact has to be resolvable when the build runs: here it was installed into the local repository of the scratch build; in a real organisation it is deployed to the company’s repository (see Install, Deploy & Distribution Management). The classes of enforcer-rules are not API and a custom rule must not use them. To break the build immediately instead of collecting failures, execute() can throw EnforcerRuleError.

Source: Writing a custom rule

Material written for Maven 2 predates most of what is on this page. What still circulates with it, and is outdated:

Source: Ant conditions: antversion

Source: ResolutionStrategy.failOnVersionConflict()

The cross-tool picture is in Comparing Ant, Maven and Gradle.