Maven: Philosophy, Coordinates & Directory Layout

The Maven site states the goal in one sentence: to allow a developer to organise and build a Java project in the shortest period of time. It says Maven pursues that in four ways, and each one is visible in how the tool behaves:

The same page is candid about the cost. Maven takes an opinionated approach to layout, some projects cannot fit it for historical reasons, and the site says that a project with an unusual structure that cannot be reorganised may have to give up some features, or Maven altogether. That statement is the honest summary of the trade-off: Maven’s value is in the conventions, and the more a project departs from them the less value the tool returns. The last section of this page shows how far a departure can go in practice.

The name is a Yiddish word meaning accumulator of knowledge, and the project began as an attempt to simplify the build processes of the Jakarta Turbine project: several projects, each with its own slightly different Ant build files, with JARs checked into CVS. The wish was for a standard way to build them, a clear definition of what a project consists of, an easy way to publish project information and a way to share JARs across projects. The tool grew from there into what the release history traces from Maven 1.0 (2004) to Maven 3.10.0 and the Maven 4 release candidates.

"Convention over configuration" means the tool supplies a default for everything it can, so that a project states only what differs from the default. In Maven the defaults live in a built-in parent that every POM inherits from, the super POM. The super POM fixes the directory structure, the output directories and the final name of the artifact; the default lifecycle bindings (which plugin goal runs in which phase for a jar project) are supplied separately by the packaging, and the effective POM page shows how the two merge.

You can see the defaults without reading any documentation, by asking Maven to evaluate the expressions it will use. The tidepool-model POM does not mention a single directory, yet:

(<module> stands for the scratch path of the tidepool-model directory.) Every value above comes from the super POM, and an mvn help:effective-pom run on Maven 4.0.0-rc-7 prints the same directories, so the layout is stable across the lines. The finalName is the artifact id and version joined by a hyphen, which is the file name convention that the packaging page and the repository layout below both rely on. The same effective POM also shows what Maven 3.10.0 changed in the defaults: the properties project.build.sourceEncoding and project.reporting.outputEncoding are UTF-8, and project.build.outputTimestamp is 1980-02-01T00:00:00Z. That last property is why every entry of a JAR built by Maven 3.10.0 is dated 1980-02-01 (the unzip -l runs on the Getting Started page show it): reproducible builds are on by default in 3.10, and Security & Reproducible Builds explains the mechanism.

The convention has a price, and it is worth stating plainly because it is the source of most "why does Maven do that" questions: the defaults are right for the common case and invisible. When a project needs something else, you override one element, and that override is the whole configuration. The last section of this page does exactly that for the directory layout.

Source: Maven: POM Reference, The Super POM

Source: Maven 3.10.0 reference: Super POM

Source: Maven: POM Reference, Directories

The standard directory layout is the most visible convention. The Maven guide gives the reason in one sentence: a common layout lets a user who knows one Maven project feel at home in another, with the same advantages as a site-wide look and feel. It asks you to conform as far as you can, and says that where you cannot, the settings can be overridden in the project descriptor (the last section of this page).

The guide lists these directories:

The top level of a Maven project holds the pom.xml, the descriptive text files, and two directories at most: src and target. The only others expected are version-control metadata (.git, .svn, CVS) and the subprojects of a multi-project build, each laid out the same way. Under src there is a subdirectory per kind: main for the main artifact, test for unit test code and resources, site and so on. Inside an artifact-producing directory (main and test) there is one directory for the language, java, under which the normal package hierarchy exists, and one for resources, whose structure is copied as it is to the class path. Other contributing sources get their own directory under the same parent: src/main/antlr would hold ANTLR grammar files, for instance. The target directory holds all the output of the build.

Two details are not in the guide’s list but are visible in the runs. src/main/scripts is the default scriptSourceDirectory, shown by the help:evaluate output above. And the Maven 4.0.0-rc-7 build of a project with a 4.1.0 POM model (the last section) logged "skip non existing resourceDirectory" for a second default test resource directory, src/test/resources-filtered; the Maven 3.10.0 builds did not look for it. The Maven 4 POM model page covers the model.

Maven identifies everything it handles by coordinates. The Maven site’s definition of an artifact is the clearest starting point: an artifact is a file (a sequence of bytes) that can be addressed by its coordinates and which Maven downloads, installs or deploys. Most artifacts are POMs and JARs, but an artifact can be any file; what makes it an artifact rather than "just a file" is that it has coordinates and is therefore addressable. The tool uses the short form groupId:artifactId:version, or GAV, although the real coordinates have more fields.

The Maven site has two documents on naming: a short conventions page and a guide to the naming conventions of coordinates. They agree, and together they say:

These are conventions, and Maven enforces only a part of them. The difference between what is recommended and what is rejected is worth knowing exactly, so here is a POM that breaks the artifact id convention in two ways (an uppercase letter and an underscore) and then in a third (a space):

With the artifact id Tide_Pool and the version 1.0 beta (a space), mvn validate printed BUILD SUCCESS on Maven 3.10.0, 3.9.16 and 4.0.0-rc-7: uppercase letters and underscores are accepted, and so, in these three versions, is a space in a version. With the artifact id Tide_Pool Core (a space) the build stops:

(The same message appears for Maven 3.9.16; Maven 4.0.0-rc-7 prints it twice, as does not match a valid coordinate id pattern, once for each validation pass.) So the artifact id pattern allows letters, digits, underscores, hyphens and dots, which is wider than the convention. The version is different: the characters \ / : " < > | ? * are rejected, but in different ways by different lines. With the version 1.0/beta:

(Messages trimmed to the lines that matter.) This is one of the "stricter POM validation" changes of Maven 3.10: what 3.9 accepts with a warning, 3.10 refuses. The release table in Versions & Release History lists the others, and Versions, Snapshots & Ranges explains how Maven orders the version strings that pass validation.

Source: Maven: Conventions, Artifact Naming

Source: Maven: Naming convention of Maven coordinates, Project group identifier

Source: Maven: Naming convention of Maven coordinates, Artifact identifier

Source: Maven: Naming convention of Maven coordinates, Version identifier

Source: Maven: Naming convention of Maven coordinates, Maximum version length

Source: Maven: Naming convention of Maven coordinates, Unstable versions (SNAPSHOT)

The glossary of the Maven site explains the terms that have an explicit meaning in Maven and confuse newcomers. The table keeps the site’s definitions and adds the evidence from the runs on this page where a term shows up in the output. Two entries a reader would expect, goal and reactor, are not in the site’s glossary page; they are defined from the plugin and multi-module guides.

The glossary also defines two documentation formats of the Maven site, APT and XDoc (the formats currently used for site content are in Site & Reporting). Its examples of plugins, jar, eclipse and war, include one that is retired: the Maven site’s plugin list shows the eclipse plugin (last version 2.10) retired on 2015-10-07, the idea plugin (2.2.1) on 2013-07-26 and the reactor plugin (1.1) on 2014-03-24. IDEs read the POM directly.

Two of those terms can be verified by running Maven. help:describe reports the mojo behind a goal, and its class:

(Trimmed to the first lines; the real output goes on with every parameter of the goal. -N runs the goal on the root project only. Without it, the same command on Maven 3.10.0 ran the goal once, on tidepool-parent, and the reactor summary reported the three modules as SKIPPED.) And the reactor announces itself at the start of every multi-module build:

The order is not the order of <modules> in the parent POM by accident: the reactor sorts projects so that any project is built before the ones that need it (a project dependency on another module, a plugin declared from another module, a build extension), and falls back to the declared <modules> order when no other rule applies. Only references that are used count; dependencyManagement and pluginManagement do not change the order. The module list of tidepool-parent happens to be in dependency order already (model, engine, cli), so the run does not demonstrate the sorting; the page on multi-module builds and the reactor does.

Source: Maven: Glossary

Source: Maven: Introduction to Plugins, What is a Mojo

Source: Maven: Introduction to the Build Lifecycle, A Build Phase is Made Up of Plugin Goals

Source: Maven: Guide to Working with Multiple Modules, The Reactor

Source: Maven: Guide to Working with Multiple Modules, Reactor Sorting

The Maven guide for this situation starts with a warning that is worth repeating before the technique: use it as a last resort. It is a misconception that Maven cannot build a project that does not follow the layout, but some features or plugins, especially third-party ones, may not work or may not work completely, and the defaults exist because they save every future reader from learning another layout. The guide covers three cases: several source directories feeding one artifact, several artifacts built from one source directory, and several artifacts from one POM (which it discourages in favour of one artifact per POM).

For the simple case, a legacy project whose sources are in src/, tests in test/ and resources in etc/, the technique is to override the directories in the POM’s build element. The experiment copies the tidepool-model sources into that Ant-style layout, with a POM that declares nothing about directories. The default layout finds nothing, and the build still succeeds, which is the dangerous part:

Maven did not fail: there was nothing to compile, nothing to test and the JAR is empty but for its META-INF entries, which is why that one WARNING must not be ignored. Adding the directories to the POM:

and running mvn package again, now with the output under build because of <directory>build</directory>:

(Lines of the output that did not carry the information were left out. The line "skip non existing resourceDirectory …​ src/test/resources`" is there because the default test resources directory still applies: only `resources was overridden.) The JAR holds the four classes and model.properties. The directories you can override this way are exactly the ones evaluated earlier: sourceDirectory, testSourceDirectory, scriptSourceDirectory, outputDirectory, testOutputDirectory, resources, testResources, directory (the build directory) and finalName. They live in the parent build element, so, as the POM reference says, they cannot be changed by a profile.

Source: Maven: Using Maven When You Can’t Use the Conventions

Source: Maven: POM Reference, Directories

Apache Maven 2 Effective Implementation (Ching and Porter, 2009, written for Maven 2.2) is right about the ideas on this page: the standard layout, the coordinates, the repository layout and the best practice of one artifact per POM have not changed since Maven 2.0 (2005). It is out of date in the details around them. It installs Maven 2.2.1 (the 2.x line has been end of life since 2014-02-18; the maintained lines are 3.10.0 and 3.9.16, with 4.0.0-rc-7 as a release candidate); it sets M2_HOME and unpacks Maven per machine (M2_HOME is unnecessary, and the Maven Wrapper is the per-project approach); it assumes Java 5 (Maven 3.9 and 3.10 need Java 8 or later, Maven 4 needs Java 17); it uses plugins without versions and relies on the RELEASE and LATEST plugin metaversions (always pin plugin versions); and it uses archetype:create, which no longer exists: on Maven 3.10.0 mvn archetype:create fails with Could not find goal 'create' in plugin org.apache.maven.plugins:maven-archetype-plugin:3.4.1 among available goals crawl, create-from-project, generate, help, integration-test, jar, update-local-catalog. The glossary page of the Maven site itself still describes the POM file as project.xml, which is Maven 1.

Source: Maven: Maven Releases History

Source: Maven: Plugins, Retired