Maven 4: POM Model & Consumer POM

In a 4.1.0 POM the <modelVersion> element can be left out, because the namespace already says it. The upgrade tool removes it. The consequence is easy to miss on a team that still has a Maven 3 user: Maven 3 does not know the new namespace, finds no modelVersion, and reports that, not the real cause. This is the same tidepool parent POM with the root attribute taken out, built with Maven 3.10.0:

With the root="true" attribute present the first message is the one the overview shows, Unknown attribute 'root' for tag 'project', and Maven 3.9.16 prints the same lines. Either way the rule is the one the overview gives: a repository with a 4.1.0 build POM can only be built with Maven 4.

Comparing maven-4.0.0.xsd with the 4.1.0 schema that the redirect above points to, type by type, for every element and attribute name that appears or disappears, gives the complete list below. No other element or attribute name differs, so dependencyManagement, profiles, repositories or distributionManagement, for example, are unchanged.

Two further 4.1.0 features are behaviour, not new names: the bom packaging (build POM only; the consumer POM says pom) and the use of <classifier> and <exclusions> on an import-scope BOM dependency, both described in the overview and in Dependency Management & BOMs.

Two elements disappear from the schema: <reports> (in <project> and in <profile>, long deprecated in favour of <reporting>) and <goals> inside <plugin>. A POM that still uses them is no longer valid 4.1.0, which is one more reason to move to 4.1.0 deliberately and not by search and replace. The <source> element is a whole new type; its fields are in Declaring sources.

Source: Maven 4 model reference (API model) and What’s new in Maven 4: Model version 4.1.0

The conversion of the tidepool project is mostly mechanical, so it is a good fit for mvnup. The starting point is a Maven 3 style 4.0.0 build with a ${revision} version, three <module> entries and repeated parent and dependency coordinates. It builds on Maven 3.10.0 and on Maven 4.0.0-rc-7 without change; on rc-7 it only adds the warning that no root directory was found (The root directory, in practice). mvnup apply with --model-version 4.1.0 --infer, in a scratch git repository, reported:

(Only the headline lines of each strategy are shown.) Three details are worth knowing. The tool deletes the list of subprojects when it equals the direct children, trusting discovery (Subprojects in detail). It does not touch a dependency such as <version>${project.version}</version>, so the version is still repeated in the POMs of tidepool-engine and tidepool-cli. And it moves maven.compiler.release into <sources>, which broke the build with the 3.x compiler plugin, a trap that the overview already measured (the compiler failed with records are not supported in -source 8, because 3.x ignores targetVersion); with the 4.x compiler plugin (4.0.0-beta-5) the same converted project compiled for release 17, and the class file major version was 61. On a copy without a .mvn directory the tool also printed Created .mvn directory (an empty one), so it silences the missing-root warning for you. I finished the conversion by hand: I restored the property, removed the dependency versions and used the root attribute instead of the empty directory. The result, which the rest of the page uses, is:

and each subproject, for example tidepool-engine, is eleven lines with no coordinates but its own artifact id:

Source: Maven Upgrade Tool and What’s new in Maven 4: Automatic versioning

mvn install installed flat-app-1.0.0.jar, flat-app-1.0.0.pom and flat-app-1.0.0-build.pom. The default consumer POM is not stripped of build information in rc-7. This is the file, with the unchanged <dependencies> and <build> left out:

What changed compared with the build POM is only the form: the model version is 4.0.0, the <parent/> shorthand is a real parent, <relativePath> is gone, and everything else, the property, the four dependencies with their scopes (the managed versions are still omitted: the parent supplies them), and the jar plugin configuration, was copied. The file is also reformatted (the source layout is not kept). The parent is installed too, because the consumer POM refers to it. The official comparison table says that plugin configuration and properties exist only in the build POM and that the consumer POM "might" lose more build data in future; on rc-7 they were kept, so treat the published POM as containing build information and avoid putting anything sensitive in the build section.

A pom-packaging parent is treated the same way: installing tidepool-parent kept <properties> and <pluginManagement>, which children need, dropped the <modules> list (and the root attribute of the 4.1.0 form) and replaced ${revision} by its value.

Source: What’s new in Maven 4: Comparing build POM and consumer POM

Set maven.consumer.pom.flatten to true and the consumer POM becomes self-contained. This is the same build with -Dmaven.consumer.pom.flatten=true:

The dropped scopes (provided and test) are not transitive anyway, so what flattening mainly removes is the need to resolve the parent and the imported BOM to read the dependencies. The article gives the reason it is off by default: to avoid unexpected behaviour and to keep control of how (transitive) dependencies are listed. The parent POM of a flattened child is still installed, since it is a normal project of the build.

Source: What’s new in Maven 4: Consumer POM

The property is a user property, so -D works. The official article names a second place, which is the one to prefer in a repository because it applies to every contributor and to CI, with no change to the command line. Putting a single line in .mvn/maven-user.properties:

and running a plain mvn clean install gave a consumer POM with no <parent> and only the compile and runtime scopes, exactly like the -D run. It also took effect when the build was started from another directory with -f flat2/app/pom.xml: that consumer POM again had no <parent> and no <properties>. I found no pom.xml element that does the same; the switch is a property, because it is about how you publish, not about what the project is.

The consumer POM is 4.0.0 only as long as everything in the build POM can be written in 4.0.0. A condition-based profile cannot. A scratch project with this profile (the build POM has no other 4.1.0 feature):

produced a consumer POM with <modelVersion>4.1.0</modelVersion> and the profile untouched. The overview says that Maven warns when this happens; on rc-7 I saw no warning in the build output, only the Installing .../consumer-NNN.pom line, so check the installed file. A downstream project whose only dependency is this artifact (version 1.0.0) shows why it matters, because commons-lang3 lives only in the profile. The dependency tree, on Maven 3.10.0 and on Maven 4.0.0-rc-7:

Maven 3.10.0 and 3.9.16 both read the 4.1.0 consumer POM without a message and silently drop the profile and with it the dependency. A library that publishes for Maven 3 users must therefore avoid <condition>, or use the classic <jdk> activation, which 4.0.0 can express.

The preserve.model.version attribute decides whether the model version of the build POM is passed on. On the project without the profile, preserve.model.version="false" (the default) produced a 4.0.0 consumer POM, and preserve.model.version="true" produced one with <modelVersion>4.1.0</modelVersion> and the 4.1.0 namespace. In both cases name-1.0.0-build.pom was the 4.1.0 source file, with the attribute itself kept. Use true only when you want the published POM to be 4.1.0; as the dependency trees above show, Maven 3 still reads such a file, but it ignores what it does not know.

Source: What’s new in Maven 4: Condition-based profile activation and Maven 4 model reference (API model): project

The point of the whole mechanism is that a project built with Maven 4 stays usable from Maven 3. A downstream Maven 3.10.0 project whose only dependency is tidepool-cli, installed by rc-7 from the 4.1.0 tidepool build:

The consumer POM of tidepool-cli, 16 lines against the 13 of the build POM and the 248 of help:effective-pom for the same project, is:

(The effective POM is much longer because it carries the inherited properties, the 15 plugins from the lifecycle bindings and from pluginManagement, and the Super POM defaults; it exists only in memory.)

Source: What’s new in Maven 4: Consumer POM

The official article says Maven 4 "does not deploy the pom.xml used to build the project". On rc-7 it deploys both. Deploying the 4.1.0 tidepool build to a file: repository with -DaltDeploymentRepository=local::file:/work/repo (the deploy plugin 3.2.0, as pinned in the parent; the real remote was not used) produced, for tidepool-cli:

(The .md5 and .sha1 files of each entry were left out.) So the build POM, with the build classifier, is published next to the consumer POM and a repository manager sees an artifact it has not seen before. Plan for it in the policies of your repository manager (see Install, Deploy & Distribution Management and Repositories, Mirrors & Repository Managers). Publishing to Maven Central was not run here; its validation of the POM is on Publishing to Maven Central.

Source: What’s new in Maven 4: Consumer POM and Comparing build POM and consumer POM