Maven: POM Fundamentals

The effective POM is the POM as Maven actually uses it, after inheritance from the super POM, interpolation and the default lifecycle bindings have been applied. help:effective-pom prints it. For the six-line POM above:

printed 219 lines on Maven 3.10.0, 234 on Maven 3.9.16 and 172 on Maven 4.0.0-rc-7 (release candidate). The start of the 3.10.0 file shows the three kinds of thing that are added (a ... marks the lines that were left out, here the plugin executions):

The rest of the difference between the three Maven versions (the 3.9.16 super POM’s <pluginManagement>, for instance) is explained on Inheritance, Aggregation & the Effective POM.

Source: Maven 3.10.0 release notes, Changes in the Super POM

Source: Maven Help Plugin: help:effective-pom

A POM that leaves out a required element does not build. Each row below is the minimal POM with the one element removed; the message is from mvn -B -ntp validate on Maven 3.10.0, and the last column says what 4.0.0-rc-7 (release candidate) did with the same file.

The 3.10.0 output for the missing artifactId, in full, shows the shape of every such failure (the first block of lines names the problem, the [Help 1] lines at the end are the generic pointer to the Maven wiki):

groupId and version may be omitted when a <parent> supplies them (they are inherited; artifactId and packaging never are), which is why a module POM is usually shorter than the minimal one. A misspelt element name is a different failure: a POM with <dependecies> instead of <dependencies> stops with Malformed POM <dir>/pom.xml: Unrecognised tag: 'dependecies' on 3.9.16 and 3.10.0, and with Unable to read model: Unrecognised tag: '{http://maven.apache.org/POM/4.0.0}dependecies' on 4.0.0-rc-7. Maven does not validate against the XSD, though: the same POM with no xmlns at all built on all three versions. The namespace and the xsi:schemaLocation matter for editors and tools that validate and complete, not for Maven itself.

Source: Maven: Introduction to the POM, Minimal POM

packaging is the fourth coordinate of the project’s identity. When it is absent it is jar. Its value is not free text: it is the role-hint of a lifecycle mapping, which fixes the list of plugin goals that run in each phase of the default lifecycle. The POM reference lists these core packaging values: pom, jar, maven-plugin, ejb, war, ear, rar. Plugins and extensions can contribute more; the Maven Central requirements list par, aar and apklib as further examples seen in the wild. The default bindings per packaging are on Build Lifecycle, and the archives themselves on Packaging JARs, WARs & Manifests.

Two runs show what the value changes. A pom project has no code to build and the lifecycle mapping contains no plugin for the early phases, so mvn -B -ntp package on the tidepool-parent POM runs nothing:

and install ran a single plugin goal, which copies the POM itself into the repository (this run used a throw-away -Dmaven.repo.local, so nothing was added to the real local repository):

A project that declares war gets the war plugin bound to package, and with no web descriptor that goal fails, which is the classic first error of a new web project (the war plugin 3.5.1 on Maven 3.10.0):

The two fixes are to add a src/main/webapp/WEB-INF/web.xml or to set failOnMissingWebXml to false in the plugin configuration (this page does not run the second one; see Plugins & Their Configuration). And a value that is not a known packaging stops before anything runs, as in the table above (Unknown packaging: jarr).

Source: Maven: POM Reference, Packaging

<build><finalName> is the name of the file Maven creates in target, without its extension. Its default is ${project.artifactId}-${project.version} (the effective POM above shows tidepool-minimal-1.0.0). It is the one coordinate-related setting that people change on a project that has to produce a fixed file name, for example a web application called ROOT.war or a CLI called tidepool.jar, and it is also the source of a classic misunderstanding: it renames the file in target, not the artifact in a repository. A tidepool-model project with <finalName>tidepool</finalName>:

built with mvn -B -ntp -q -Dmaven.repo.local=<scratch>/repo install (the -q hides the build log), produced

The file in target is called tidepool.jar, and the file installed in the repository is tidepool-model-1.0.0.jar. A repository has a fixed layout (artifactId-version[-classifier].extension below the coordinates' directory) and a consumer finds a file by coordinates, so the install and deploy plugins ignore finalName. Anyone who needs the plain name, such as a Dockerfile that copies target/tidepool.jar, uses finalName; anyone who publishes does not need to care about it.

Source: Maven: POM Reference, Packaging

The POM reference names five kinds of property. The table has the reference’s description and, in the last column, what the expression gave in a run: a throw-away POM (the coordinates of tidepool-model) declared the <properties> shown below, and help:effective-pom printed the interpolated values. The Java system property was java.specification.version and os.name, and the environment variable was HOME.

The reference adds a detail about Windows that this page cannot run (not run here, macOS): environment variable names are case-insensitive there, but the lookup of the property is case-sensitive, so ${env.Path} and ${env.PATH} are different expressions, and names are normalised to upper case.

The settings.* row is the odd one. The model builder reference explains why: after interpolation, ${...} content can remain in the model and be evaluated later when plugin parameters are set, and it names the settings.* values for the settings model as the main case. So settings.* is not a POM-interpolation prefix in practice; it is available to plugin parameters. help:evaluate uses the same expression evaluator as plugin parameters, and it does resolve it:

(The <home> stands for the home directory.) Reading settings.xml values is therefore possible in a plugin’s <configuration>, but not in a property of the POM or in a dependency version.

Source: Maven: POM Reference, Properties

Source: Maven 3.10.0 Model Builder, Model Interpolation

Some property names are read by Maven or by the default plugins, so declaring them changes behaviour:

The POM reference warns in a comment of its own example not to start your own properties with project.: those names are reserved for Maven and "will become elements in a future POM definition". Section "Precedence" below shows what happens when you do.

A property can be declared in several places at once, and the values are not equal. A POM with the following properties (the coordinates are those of tidepool-model) was run with and without -D options on the command line:

The table lists the value each result.* property had in the effective POM:

So, on all three versions, user properties from -D win over properties in the POM, and properties in the POM win over system properties and environment variables, which is what lets a POM supply a default that the command line overrides. The row that differs is the one the POM reference tells you to avoid: a user-declared project.artifactId is ignored by Maven 3.x (the model value is used first, matching the model builder reference, which lists project.* first) and honoured by Maven 4.0.0-rc-7. Declaring properties under the project. prefix therefore behaves differently between Maven 3 and Maven 4 and should not be done.

Source: Maven: POM Reference, Properties

Source: Maven 3.10.0 Model Builder, Model Interpolation

Because -D wins, a POM property is a build parameter. Declare <greeting>from-the-pom</greeting>, use ${greeting} in a place that accepts properties, and call mvn -Dgreeting=from-the-command-line .... Beware that the same mechanism makes -D a global switch: a system property given with -D is visible to every module and every plugin of the build. The CLI options themselves are on Running Maven (CLI), and profiles are the structured way to switch whole groups of properties.

Because variables are processed after inheritance, a parent that uses a variable gets the definition of the child, not its own. The introduction to the POM says so, and a small experiment shows it. The parent declares and uses a property:

and the child, which lives in the child directory below it, redefines station:

mvn -B -ntp -q help:evaluate -Dexpression=banner -DforceStdout printed, on all three versions, in the child directory

and in the parent directory Tides for Tarifa (built from tidepool-parent). Neither station nor project.artifactId was read in the parent: the string was inherited unexpanded and expanded in the context of the project being built. This is the mechanism behind template-style parents ("define the version once, let children set the name") and behind bugs where a child’s property silently changes what a shared parent does.

Source: Maven: Introduction to the POM, Project Interpolation and Variables

A ${...} that matches nothing is not an error by itself. The effective POM of the properties experiment kept <by.missing>${no.such.property}</by.missing> as a literal string on all three versions. The error appears where the value is needed. The most common case is a misspelt property in a dependency version:

(vesion in the property name.) The build stops before resolving anything, on Maven 3.9.16 and 3.10.0 with:

Maven 4.0.0-rc-7 (release candidate) reports the same problem twice with the coordinates spelt out ('dependencies.dependency.version' for groupId='org.apache.commons', artifactId='commons-csv', type='jar' must be a valid version but is '${commons-csv.version}'). Read the placeholder in the message literally: it is the name the POM asked for, so compare it with the declaration.

Source: Maven 3.10.0 Model Builder, Model Interpolation

There is no escape syntax for a literal ${name} in a POM that Maven would not also replace. The experiment declared three properties after station=Tarifa: <esc.dollar>$${station}</esc.dollar>, <esc.backslash>\${station}</esc.backslash> and <esc.plain>${station}</esc.plain>. The effective POM had $Tarifa, \Tarifa and Tarifa on all three versions: the placeholder was replaced anyway and a stray character was left. Where a literal is needed in a filtered resource, the resources plugin has its own escape parameter (escapeString, see Resources & Filtering),.

Interpolation of a project’s own POM can use anything: command-line properties, environment variables, system properties. A POM that Maven reads from a repository, because it is a dependency, a parent or an imported BOM, is a different matter, and Maven 3.10.0 changed the rule. The release notes list, under "Security Hardening", that such a model "contributes less to the build: restricted interpolation, profile activation limited to platform-derived criteria, recessive repository merging and rejection of system scoped dependencies", with the property maven.model.dependencyInterpolation.full as an opt-out.

The effect is easy to reproduce. A throw-away tidepool-probe POM (packaging pom) was installed in a scratch local repository with a dependency whose version is a placeholder that only a command-line property can fill:

A consumer project depends on it with <type>pom</type>, and dependency:tree (plugin 3.11.0) was run with -Dcsv.v=1.14.1. The resolved tree on Maven 3.9.16:

and on Maven 3.10.0 with the same command:

On Maven 4.0.0-rc-7 (release candidate) the commons-csv node was missing altogether. Adding -Dmaven.model.dependencyInterpolation.full=true to the 3.10.0 command restored the 3.9.16 tree. Without any -D, both 3.9.16 and 3.10.0 printed the literal ${csv.v} node. The lesson is for anyone who publishes: a POM that goes to a repository must be self-contained. A published POM that needs a -D property, an environment variable or a profile activated by the consumer’s machine is unreliable, and from Maven 3.10.0 on it is also ignored. Properties defined in the POM itself or in its parents still work. The dependency side is on Dependencies, Scopes & Mediation, and the consumer POM that Maven 4 generates so that the published file is flat is on Maven 4: POM Model & Consumer POM.

Source: Maven 3.10.0 release notes, Security Hardening

A child of that parent (artifactId tidepool-model, nothing else but the <parent>) saw, in its effective POM, on all three Maven versions:

The last is scm/url; the fifth, the distributionManagement/site/url, became file:///tmp/tidepool-site/tidepool-model/ in a variant of the parent with a <site> element. The model builder reference documents this special handling of project.url, project.scm.connection, project.scm.developerConnection, project.scm.url and project.distributionManagement.site.url: an unset value is the parent’s with the artifact id appended. That is right when each module has its own page below the parent’s, and wrong for a repository URL, where the SCM URL of a module in a git repository is the repository’s. Two settings change it:

Source: Maven 3.10.0 Model Builder, Inheritance Assembly

Source: Maven 3.10.0 POM model reference

The descriptive elements are in the POM, and the POM travels with the artifact. The JAR built by the finalName example above contains a copy of the POM and a small properties file with the coordinates, which tools use to identify a JAR found outside a repository:

The installed tidepool-model-1.0.0.pom was byte-for-byte identical to the project’s pom.xml (checked with cmp): in the Maven 3 line the file that is installed and deployed is the source POM, with its <parent> reference, its unexpanded ${...} placeholders and its profiles, which is why a consumer needs the parent in a repository too and why the previous section’s rule (a self-contained POM) matters. The consumer POM of Maven 4 is the change that makes the published file a flattened one.

Repositories that host public releases check the descriptive elements. Maven Central requires name, description and url, the license information, the developer information and the SCM information in the POM, as well as correct coordinates (a release version cannot end in -SNAPSHOT). The checklist and how to produce the Javadoc, sources and signature files are on Publishing to Maven Central.

Source: Sonatype Central: Required POM Metadata

<prerequisites><maven> states a minimum Maven version. In POM 4.0.0 maven is the only element it has. Its role has narrowed over the years: the POM reference says that for a build-time prerequisite one should use the Maven Enforcer Plugin’s requireMavenVersion rule, and that the element is still used at run time for packaging maven-plugin, to make sure the minimum Maven version of a plugin is met (only in the plugin’s own pom.xml). A jar project that sets it is told off by all three Maven versions. This POM:

printed the same warning on 3.9.16, 3.10.0 and 4.0.0-rc-7, and built successfully (the prerequisite was not enforced):

Source: Maven: POM Reference, Prerequisites

The way to state a build requirement is the Enforcer plugin (3.6.3). Bound to the validate phase through an execution, with the rules in the execution’s configuration:

mvn -B -ntp validate passed with 3.9.16, 3.10.0 and 4.0.0-rc-7 (release candidate):

and with the range changed to [3.99.0,) it failed on 3.10.0 with the message that the POM supplies:

The prerequisites run for a maven-plugin project was not run here; the other rules of the Enforcer are on Enforcer.

Source: Maven Enforcer: requireMavenVersion

<repositories> and <pluginRepositories> say where dependencies and plugins are downloaded from, beyond Central, which the super POM supplies (the effective POM above shows it). Each repository has an id, a name, a url, a layout (default, or legacy for the Maven 1 layout) and independent releases and snapshots policies with enabled, updatePolicy (always, daily as the default, interval:X in minutes or never) and checksumPolicy (ignore, fail or warn, the default). A repository must follow the Maven repository layout; everything else, including mirrors and credentials in settings.xml, is on Repositories, Mirrors & Repository Managers and settings.xml & Password Encryption. Plain http repository URLs in examples older than Maven 3.8.1 are blocked by default today; see that page.

Source: Maven: POM Reference, Repositories

<distributionManagement> is about the artifacts this project produces, not the ones it consumes: where deploy uploads them. The reference lists repository and snapshotRepository (an id, a name, a url and a layout; the id is matched to a <server> in settings.xml for credentials, and the snapshot repository is optional: with none, repository is used for snapshots), site (where site:deploy publishes the project site), downloadUrl, status and relocation.

Two notes on the elements. The upload URL is often not the download URL (an upload by HTTP PUT or scp, a download by HTTP GET), so the two are declared separately. And <status> must never be written by hand: Maven sets it when the artifact is transported to a repository, with the values none, converted, partner, deployed and verified, and "should never be configured in your pom.xml". The uploading itself, with real runs against a file:// repository, is on Install, Deploy & Distribution Management.

Source: Maven: POM Reference, Distribution Management

Source: Maven: POM Reference, Status

When a project changes its coordinates, for example after a change of groupId, the old coordinates should keep resolving. The mechanism is a <relocation> element in the old coordinates' POM, published in the repository:

Only the elements that changed need to be given (version was left out, so it stays 1.0.0); the message explains why. In the run, this POM was installed into a scratch repository next to the real io.tidepool:tidepool-model:1.0.0, and a consumer declared a dependency on org.example.tides:tides-model:1.0.0. dependency:tree printed on 3.9.16, 3.10.0 and 4.0.0-rc-7 (release candidate), twice (once while the project was read, once for the plugin):

The consumer gets the new artifact and is told to update its POM. The two things people get wrong are where the element lives and what it does not do. It goes in the old coordinates' POM, the one that is published in the repository, and not in the new one. The related case of a third-party artifact that is not in any repository, and more on relocation, are on Installing Third-Party JARs & Relocation.

Source: Maven: POM Reference, Relocation