The local repository

The local repository is the folder Maven keeps every artifact it has resolved: the plugins of the build, the dependencies of the project, the poms behind both, and the artifacts mvn install puts there. In this image it is the only repository there is, because the settings file is offline, so its layout is worth knowing: a missing jar in it is the reason a build stops, and a jar that is in it but not on the graph is the reason a page can say "this version is in the repository and unused".

Where it is

Two expressions of the settings give the folder and the offline flag, and help:evaluate prints them without the log around them:

mvn -B -q help:evaluate -Dexpression=settings.localRepository -DforceStdout
mvn -B -q help:evaluate -Dexpression=settings.offline -DforceStdout

<HOME>/.m2/repository
true

The first line is printed as <HOME>/.m2/repository: the folder is the home folder of the user that runs Maven, which is /home/agent in this image and something else on your machine, so the pages of this course write it as <HOME> where Maven prints the absolute path. ~/.m2/repository is also the default, so nothing sets it here: the path is where Maven puts it when no settings file and no command line says otherwise. The true is the switch of the offline article.

The path is the coordinates

An artifact is stored under group id, artifact id and version, one folder each, so the coordinates of a dependency are also its address. The JUnit aggregate the course uses:

find ~/.m2/repository/org/junit/jupiter/junit-jupiter/5.14.3 -type f | sort | sed "s#$HOME#~#g"

~/.m2/repository/org/junit/jupiter/junit-jupiter/5.14.3/_remote.repositories
~/.m2/repository/org/junit/jupiter/junit-jupiter/5.14.3/junit-jupiter-5.14.3.jar
~/.m2/repository/org/junit/jupiter/junit-jupiter/5.14.3/junit-jupiter-5.14.3.jar.sha1
~/.m2/repository/org/junit/jupiter/junit-jupiter/5.14.3/junit-jupiter-5.14.3.pom
~/.m2/repository/org/junit/jupiter/junit-jupiter/5.14.3/junit-jupiter-5.14.3.pom.sha1

A SNAPSHOT version adds a level of its own for the timestamped files a remote repository serves; the snapshot article shows it. An artifact that a remote repository served by a version range or LATEST also leaves a maven-metadata-<repoid>.xml next to the version folders, which lists the versions it has seen.

What install writes

A small project of this page, installed: the jar and the pom go into the repository, and the build says where.

pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>localrepo</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> </project>

src/main/java/com/example/localrepo/Hello.java

package com.example.localrepo; public class Hello { public static void main(String[] args) { System.out.println("installed"); } }

mvn -B install > install.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" install.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] -----------------------< com.example:localrepo >------------------------
[INFO] Building localrepo 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- install:3.1.4:install (default-install) @ localrepo ---
[INFO] Installing <project>/pom.xml to <HOME>/.m2/repository/com/example/localrepo/1.0.0/localrepo-1.0.0.pom
[INFO] Installing <project>/target/localrepo-1.0.0.jar to <HOME>/.m2/repository/com/example/localrepo/1.0.0/localrepo-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

find ~/.m2/repository/com/example/localrepo -type f | sort | sed "s#$HOME#~#g"

~/.m2/repository/com/example/localrepo/1.0.0/_remote.repositories
~/.m2/repository/com/example/localrepo/1.0.0/localrepo-1.0.0.jar
~/.m2/repository/com/example/localrepo/1.0.0/localrepo-1.0.0.pom
~/.m2/repository/com/example/localrepo/maven-metadata-local.xml

maven-metadata-local.xml one folder above the version lists the versions of com.example:localrepo that are installed locally. The resolver reads it when a pom asks for LATEST or for a range, and it is how a tool can list what a machine has without asking a repository. The two Installing lines of the log and the four files of the tree are the same fact: the pom goes first, then the jar, and neither is ever overwritten silently by a different artifact of the same coordinates, because the coordinates are the address.

Moving the repository

-Dmaven.repo.local points a build at another repository for one run. A new, empty folder is a repository with nothing in it, and offline mode turns that into an immediate failure:

mvn -B -Dmaven.repo.local=/tmp/empty-repo package > empty.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" empty.log

status: 1
[INFO] Scanning for projects...
[INFO]
[INFO] -----------------------< com.example:localrepo >------------------------
[INFO] Building localrepo 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[WARNING] The POM for org.apache.maven.plugins:maven-resources-plugin:jar:3.4.0 is missing, no dependency information available
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
[ERROR] Plugin org.apache.maven.plugins:maven-resources-plugin:3.4.0 or one of its dependencies could not be resolved:
[ERROR] Cannot access central (https://repo.maven.apache.org/maven2) in offline mode and the artifact org.apache.maven.plugins:maven-resources-plugin:jar:3.4.0 has not been downloaded from it before.
[ERROR] -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/PluginResolutionException

The first plugin of the lifecycle is the one that fails, because Maven resolves the plugins of a build before it runs the first phase. Pointing the same switch at the real repository changes nothing, and the same build succeeds:

mvn -B -Dmaven.repo.local=$HOME/.m2/repository package > own.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" own.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] -----------------------< com.example:localrepo >------------------------
[INFO] Building localrepo 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] --- surefire:3.5.4:test (default-test) @ localrepo ---
[INFO] No tests to run.
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ localrepo ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

Two settings can do the same thing for every build of a machine, and one of them is the reason this image works offline: <localRepository> in settings.xml, and settings article shows both in a file. A CI job uses the switch to keep the repository on a cache volume, and a Dockerfile uses it to fill a layer once.

Where to go next

Plugins and goals starts the part of the course about the other half of this repository: the plugins, which are artifacts with coordinates of their own and live in the same folders.

Article author: Arthur Isaev