A first project from the archetype

An archetype is a project template: a set of files with placeholders and a short question list that fills them. The quickstart archetype writes a Java project with one class, one test and a pom that is already buildable. This article generates it with real output, reads what came out, builds it, and then meets the first offline problem of the image: two plugin versions the generated pom pins and the local repository does not have.

Generating the project

The command names the archetype by its own coordinates, gives the four parameters of the project, and asks for batch mode, which is what -DinteractiveMode=false does: without it Maven asks the same questions on the terminal. The last parameter, javaCompilerVersion, is read by this archetype and becomes the release of the generated pom; 21 is the JDK of this image.

mvn -B archetype:generate -DgroupId=com.example -DartifactId=hello -Dversion=1.0.0 -Dpackage=com.example.hello -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DjavaCompilerVersion=21 -DinteractiveMode=false > build.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" build.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------< org.apache.maven:standalone-pom >-------------------
[INFO] Building Maven Stub Project (No POM) 1
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] >>> archetype:3.4.1:generate (default-cli) > generate-sources @ standalone-pom >>>
[INFO]
[INFO] <<< archetype:3.4.1:generate (default-cli) < generate-sources @ standalone-pom <<<
[INFO]
[INFO]
[INFO] --- archetype:3.4.1:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] Archetype repository not defined. Using the one from [org.apache.maven.archetypes:maven-archetype-quickstart:1.5] found in catalog remote
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.5
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: artifactId, Value: hello
[INFO] Parameter: version, Value: 1.0.0
[INFO] Parameter: package, Value: com.example.hello
[INFO] Parameter: packageInPathFormat, Value: com/example/hello
[INFO] Parameter: junitVersion, Value: 5.11.0
[INFO] Parameter: package, Value: com.example.hello
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: artifactId, Value: hello
[INFO] Parameter: javaCompilerVersion, Value: 21
[INFO] Parameter: version, Value: 1.0.0
[WARNING] Don't override file <project>/hello/src/main/java/com/example/hello
[WARNING] Don't override file <project>/hello/src/test/java/com/example/hello
[WARNING] CP Don't override file <project>/hello/.mvn
[INFO] Project created from Archetype in dir: <project>/hello
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.142 s
[INFO] Finished at: 2026-11-22T08:23:56Z
[INFO] ------------------------------------------------------------------------

The parameters come twice in the log, and that is not a mistake: once before the archetype runs, once when its files are written, because the second run resolves every placeholder of every file. junitVersion is 5.11.0, the version the archetype was written with, and it is in the local repository of this image, which is why the test later runs.

The three Don't override file warnings name directories that the archetype also declares as files; in batch mode it cannot ask, so it keeps what it made and warns. The build succeeded, and the folder is there.

What the archetype wrote

Five files, two of them empty:

cd hello
find . -type f | sort

./.mvn/jvm.config
./.mvn/maven.config
./pom.xml
./src/main/java/com/example/hello/App.java
./src/test/java/com/example/hello/AppTest.java

.mvn/jvm.config and .mvn/maven.config are read by Maven before the command line: the first adds options to the JVM that runs Maven, the second adds options to Maven itself, one per line. The archetype writes both empty: they are there so that a project can use them without a new folder appearing in the diff.

App.java is the class with the main method; AppTest.java is the test that the archetype says is rigorous:

hello/src/main/java/com/example/hello/App.java

package com.example.hello; /** * Hello world! */ public class App { public static void main(String[] args) { System.out.println("Hello World!"); } }

hello/src/test/java/com/example/hello/AppTest.java

package com.example.hello; import static org.junit.jupiter.api.Assertions.assertTrue; import org.junit.jupiter.api.Test; /** * Unit test for simple App. */ public class AppTest { /** * Rigorous Test :-) */ @Test public void shouldAnswerWithTrue() { assertTrue(true); } }

The generated pom

The pom is the interesting file. It is longer than the one of the first article because it pins the version of every plugin of the three lifecycles, which is what a template should do: a project keeps the plugin versions it was generated with, instead of taking whatever Maven has this month.

hello/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>hello</artifactId> <version>1.0.0</version> <name>hello</name> <!-- FIXME change it to the project's website --> <url>http://www.example.com</url> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> <dependencyManagement> <dependencies> <dependency> <groupId>org.junit</groupId> <artifactId>junit-bom</artifactId> <version>5.11.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-api</artifactId> <scope>test</scope> </dependency> <!-- Optionally: parameterized tests support --> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-params</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) --> <plugins> <!-- clean lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#clean_Lifecycle --> <plugin> <artifactId>maven-clean-plugin</artifactId> <version>3.4.0</version> </plugin> <!-- default lifecycle, jar packaging: see https://maven.apache.org/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_jar_packaging --> <plugin> <artifactId>maven-resources-plugin</artifactId> <version>3.3.1</version> </plugin> <plugin> <artifactId>maven-compiler-plugin</artifactId> <version>3.13.0</version> </plugin> <plugin> <artifactId>maven-surefire-plugin</artifactId> <version>3.3.0</version> </plugin> <plugin> <artifactId>maven-jar-plugin</artifactId> <version>3.4.2</version> </plugin> <plugin> <artifactId>maven-install-plugin</artifactId> <version>3.1.2</version> </plugin> <plugin> <artifactId>maven-deploy-plugin</artifactId> <version>3.1.2</version> </plugin> <!-- site lifecycle, see https://maven.apache.org/ref/current/maven-core/lifecycles.html#site_Lifecycle --> <plugin> <artifactId>maven-site-plugin</artifactId> <version>3.12.1</version> </plugin> <plugin> <artifactId>maven-project-info-reports-plugin</artifactId> <version>3.6.1</version> </plugin> </plugins> </pluginManagement> </build> </project>

Three blocks are worth naming. dependencyManagement imports the JUnit BOM at 5.11.0, so the two dependencies below it need no version of their own; the BOM article explains that in full. pluginManagement pins the plugin versions without adding a plugin: a phase that runs one of these plugins uses the pinned version, and a phase Maven does not run keeps its pin unused.

Building it offline

mvn test compiles the class, compiles the test, and runs it with surefire. It works with no network because every version it asks for is in the local repository: the resources 3.3.1, compiler 3.13.0, surefire 3.3.0 and jar 3.4.2 the pom pins, and JUnit 5.11.0 behind the BOM.

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

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:hello >--------------------------
[INFO] Building hello 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ hello ---
[INFO] skip non existing resourceDirectory <project>/src/main/resources
[INFO]
[INFO] --- compiler:3.13.0:compile (default-compile) @ hello ---
[INFO] Recompiling the module because of changed source code.
[INFO] Compiling 1 source file with javac [debug release 21] to target/classes
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ hello ---
[INFO] skip non existing resourceDirectory <project>/src/test/resources
[INFO]
[INFO] --- compiler:3.13.0:testCompile (default-testCompile) @ hello ---
[INFO] Recompiling the module because of changed dependency.
[INFO] Compiling 1 source file with javac [debug release 21] to target/test-classes
[INFO]
[INFO] --- surefire:3.3.0:test (default-test) @ hello ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.example.hello.AppTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.089 s -- in com.example.hello.AppTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4.200 s
[INFO] Finished at: 2026-11-22T08:24:06Z
[INFO] ------------------------------------------------------------------------

The versions in this log are the ones of the pom, not the ones Maven 3.9.16 would pick by itself: 3.3.1 and 3.13.0 instead of 3.4.0 and 3.15.0, 3.3.0 instead of 3.5.4. That is what pluginManagement does, and it is visible without opening the pom.

Two versions this image does not have

The template is a year or two ahead of the local repository in two places, and both are one line of the pom: clean 3.4.0 and install 3.1.2. The local repository has clean 3.2.0 and install 3.1.4. So the two phases that the test run did not touch stop before they start:

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

status: 1
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:hello >--------------------------
[INFO] Building hello 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[WARNING] The POM for org.apache.maven.plugins:maven-clean-plugin:jar:3.4.0 is missing, no dependency information available
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.231 s
[INFO] Finished at: 2026-11-22T08:24:13Z
[INFO] ------------------------------------------------------------------------
[ERROR] Plugin org.apache.maven.plugins:maven-clean-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-clean-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 same story for install, one version later:

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

status: 1
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:hello >--------------------------
[INFO] Building hello 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[WARNING] The POM for org.apache.maven.plugins:maven-install-plugin:jar:3.1.2 is missing, no dependency information available
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 0.723 s
[INFO] Finished at: 2026-11-22T08:24:16Z
[INFO] ------------------------------------------------------------------------
[ERROR] Plugin org.apache.maven.plugins:maven-install-plugin:3.1.2 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-install-plugin:jar:3.1.2 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

Neither failure says anything about the project: both name a plugin, its version, the repository they asked and the offline rule that stopped them. On a machine with a network the first run downloads the plugin and the command works; here the pom has to name a version the repository has. That is one number per plugin, and the errors article shows the change and the successful run after it.

The folders of the page are the next article: which of these five files belong to the project, which are generated, and which folder Maven writes during the build.

Where to go next

The layout article takes the folders this project already has and explains where a new class, a test, a resource and the built jar go. The pom article comes back to this file and reads it element by element.

Article author: Arthur Isaev