The wrapper and a fat jar

Two things a Java project often adds to its Maven setup are a wrapper, which pins the version of Maven the project builds with, and a fat jar, which puts the dependencies inside the jar so that one file is enough to run it. Both need an artifact that the local repository of this image does not have, so this article is the honest version of two pages that usually show a command and a happy output: the commands, and the failures they produce here, in full.

The project

A jar with one class, which is all either subject needs:

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>extra</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/extra/Main.java

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

The wrapper

mvnw is a shell script in the project that downloads a pinned version of Maven and runs it, so that a machine with no Maven, or with another version, builds the project the way its authors did. It is generated once, by a plugin, and committed. Generating it is where this image stops:

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

status: 1
[INFO] Scanning for projects...
[WARNING] Plugin not found in any plugin repository: org.apache.maven.plugins:maven-wrapper-plugin
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
[ERROR] Error resolving version for plugin 'org.apache.maven.plugins:maven-wrapper-plugin' from the repositories [local (<HOME>/.m2/repository), central (https://repo.maven.apache.org/maven2)]: Plugin not found in any plugin repository -> [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/PluginVersionResolutionException

The prefix wrapper is not in the metadata of either plugin group in the local repository, so Maven cannot even name the artifact: the message says Plugin not found in any plugin repository and nothing about maven-wrapper-plugin is resolved. On a machine with a network the same command writes the files below.

What the wrapper writes

Four files. Two scripts at the root of the project, one for a POSIX shell and one for Windows, and two files in .mvn/wrapper/: the jar the scripts run, and the properties that pin the version and the URL it comes from.

.mvn/wrapper/maven-wrapper.properties

wrapperVersion=3.3.2 distributionType=only-script distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.16/apache-maven-3.9.16-bin.zip

The version in distributionUrl is the one the project builds with, which is the point of the wrapper: a machine does not need Maven 3.9.16, it needs ./mvnw. The scripts are about three hundred lines of shell and batch each, and they are committed as they are generated: they are the one place in a Maven project where a generated file is deliberately kept.

This image cannot download the distribution either, so even the generated wrapper would not run here: ./mvnw would fail at its first step, the download of apache-maven-3.9.16-bin.zip. That is why every command of this course is mvn and not ./mvnw.

A fat jar

The jar of the package article holds the classes of the project and not its dependencies, so running a program that uses a library needs a class path. A fat jar (an uber jar) puts the classes of the dependencies inside the same jar, and then java -jar is enough. The plugin that does it is the shade plugin, and it is configured as an execution of the package phase:

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>extra</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <version>3.6.0</version> <executions> <execution> <phase>package</phase> <goals> <goal>shade</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </project>

The shade failure

Unlike the wrapper, the shade plugin is named with its version, so Maven looks for the artifact and does not find it:

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

status: 1
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:extra >--------------------------
[INFO] Building extra 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[WARNING] The POM for org.apache.maven.plugins:maven-shade-plugin:jar:3.6.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-shade-plugin:3.6.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-shade-plugin:jar:3.6.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 POM for org.apache.maven.plugins:maven-shade-plugin:jar:3.6.0 is missing and has not been downloaded from it before: the plugin is not in the seed, the settings are offline, and the build stops before the first phase, because the plugins of a lifecycle are resolved before anything runs. The failure is the one of the errors article and of the archetype page, with another coordinate.

What a page can do instead

The same result without a plugin that this image lacks has two forms, and this course uses both. The first is the class path: java -cp with the classes folder and the jars, assembled by dependency:build-classpath, which the article on projects that use each other shows. The second is a jar built by the JDK tool, with the dependency’s classes unpacked into it, which is what a fat jar is:

The jar of the first pom is that file: the package article lists its entries, and none of them is a dependency. A project that must ship one file adds the shade or the assembly plugin on a machine that has a repository, and then extra-1.0.0.jar holds every dependency and the manifest names the main class.

That jar is the ordinary one: the project’s own classes and nothing else. A project that must ship one file can still do it on a machine with a repository: the shade plugin writes extra-1.0.0.jar with every dependency inside and the manifest of the main class, and the assembly plugin can do the same with a different configuration. Neither is in the seed, so neither is shown as run.

The rest of this part of the course is about setups around the build rather than inside it: a CI job and a Dockerfile that run these commands on a machine with a network.

Where to go next

Maven in CI and in a Dockerfile shows the two files that put a Maven build on a server, with the lines this image cannot run marked as such.

Article author: Arthur Isaev