Apache Maven: Custom Archetype for Spring Boot Projects

A Maven archetype is a parameterized project template that is used to initialize, or create, a new Apache Maven project. Maven archetypes are ideal for creating initial, boilerplate code and scaffolding that is required to get a new Maven project in a working, standardized state.

In this post, I walk through the steps required to create a Maven archetype for a minimal Spring Boot project. I will also show how to customize the archetype so that the user of the archetype can choose which version of Spring Boot he or she wishes to use in their new Spring Boot project.

Prerequisites

Before getting started, you need to make sure you have installed the following software on your computer:

• Java Development Kit, version 8 or higher
• Apache Maven, 3.8 or higher

To verify that you have installed the JDK correctly, open a terminal, or shell, and execute the following command:

javac --version
                

The output in your shell should be similar to the following:

javac 17.0.2
                

To verify that you have installed Apache Maven correctly, execute the following command:

mvn --version
                

The output in your shell should be similar to the following:

Apache Maven 3.8.5 (3599d3414f046de2324203b78ddcf9b5e4388aa0)
                

Empty Working Directory

For creating an Apache Maven archetype, we are going to want to be in an empty directory to start. You can name the directory whatever you wish. The name of this directory is not important. We just need an empty directory tree to begin creating the archetype.

Define The Archetype Properties

Within the empty archetype directory, create a file named archetype.properties. Within this properties file, you will define the following four properties:

archetype.groupId

Your group or organization identifier

archetype.artifactId

The identifier of this archetype within your group or organization

archetype.version

The current version of this archetype

springBootVersion

The default version of Spring Boot to use in the project generated using this archetype

When complete, archetype.properties should look like the following:

archetype.groupId=com.nightsky
archetype.artifactId=spring-boot-minimal
archetype.version=1.0.0
springBootVersion=2.7.8
                

Create The Archetype Directory

Next, we need to create a directory to hold all of the files that will compose the archetype. Again, the name of this directory does not matter, but it is good practice to name it the same as the value you provided for the archetype.artifactId property within the archetype.properties file.

mkdir spring-boot-minimal
                

Create The Target Project Directory Structure

Within the archetype directory we just created, we need to create the standard directories that exist in Spring Boot projects. Execute the following commands to create the directories:

cd spring-boot-minimal
mkdir -p src/main/java src/main/resources src/test/java src/test/resources
                

Create An Apache Maven POM File

With all of the directories created, we can start creating the required files. Let's start by creating the pom.xml file expected by Apache Maven.

touch pom.xml
                

Copy the XML content below and paste it into your pom.xml file. You will need to change the following lines:

• Line 6 (groupId): The value should match the value of archetype.groupId in the archetype.properties file
• Line 7 (artifactId): The value should match the value of archetype.artifactId in the archetype.properties file
• Line 8 (version): The value should match the value of archetype.version in the archetype.properties file
• Line 18 (version): The value should match the value of springBootVersion in the archetype.properties file

<?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.nightsky</groupId>
    <artifactId>spring-boot-minimal</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>8</maven.compiler.source>
        <maven.compiler.target>8</maven.compiler.target>
    </properties>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.8</version>
    </parent>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>
                

Create The Spring Boot Application Configuration File

Next, we need to create the Spring Boot application configuration file (application.yml).

touch src/main/resources/application.yml
                

Add the following to the file to make it a valid YAML file and configure Spring Boot to output its banner to the console during startup.

---
spring:
    main:
        banner-mode: console
                

Create The Application Entry Point

The final requirement for the Spring Boot project is a class annotated with the @SpringBootApplication annotation that contains a standard Java main method, which bootstraps and launches the Spring-based application.

Create a file named App.java in src/main/java/com/nightsky/spring/boot/minimal/ by executing the following commands:

mkdir -p src/main/java/com/nightsky/spring/boot/minimal/
touch src/main/java/com/nightsky/spring/boot/minimal/App.java
                

Then, copy the code below and paste it into App.java

package com.nightsky.spring.boot.minimal;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class App {

    /**
     * Point of entry for the Spring Boot application.
     *
     * @param args Command line arguments.
     */
    public static void main(String[] args) {
        SpringApplication.run(App.class, args);
    }

}
                

Ensure Empty Folders are Included

When building the archetype distributable, empty folders are omitted. To ensure the directory tree under src/test/ is included in the archetype, we need to add a couple empty files to the directories contained under src/test/. Let's name them .gitkeep, and create them using the following commands:

touch src/test/java/.gitkeep
touch src/test/resources/.gitkeep
                

I am naming them .gitkeep for two reasons:

1. Most file system viewers will, by default, hide files with names starting with a period ("."); and,
2. I want these folders to be included in the Git repository that will be created upstream, after creating a new Maven project using this archetype. Git, like the Maven archetype build process, will not include empty folders in a newly created Git repository. Adding a .gitkeep file to an empty folder ensures the folder is included in a new Git repository.

Create The Maven Archetype

We are now ready to create the Maven archetype. This can be done by executing the following command:

mvn archetype:create-from-project -Darchetype.properties=../archetype.properties
                

If the process completes successfully, you will find a new directory in your archetype project folder. It will be named target/. This directory contains the files required to install the archetype to your local Maven repository located in $HOME/.m2/.

Add Spring Boot Version Variable to POM Template

Before we install the archetype to our local Maven repository, we need to add a variable for the version of Spring Boot the user would like to use in their Spring Boot project. We will add this variable to the template pom.xml file created by the mvn archetype:create-from-project process.

To add the variable, open target/generated-sources/archetype/src/main/resources/archetype-resources/pom.xml.

Change the version of the Spring Boot parent artifact from 2.7.8 to ${springBootVersion}.

The parent entry should now look like the following:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>${springBootVersion}</version>
</parent>
                

We also need to remove the default value of this variable from the archetype metadata. This will force the user of our archetype to specify which version of Spring Boot they wish to use in their project.

To remove the default value, open target/generated-sources/archetype/src/main/resources/META-INF/maven/archetype-metadata.xml.

Look for the requiredProperties element and remove the defaultValue child element.

The requiredProperties element should now look like the following:

<requiredProperties>
    <requiredProperty key="springBootVersion">
    </requiredProperty>
</requiredProperties>
                

Install The Maven Archetype

The archetype is now complete, and we are ready to install it to our local Maven repository. Let's install the archetype by executing the following commands:

cd target/generated-sources/archetype/
mvn install
                

That's it! The custom Maven archetype is now ready to be used to create minimal Spring Boot projects.

Use The Custom Spring Boot Maven Archetype

After installing the custom Maven archetype to our local Maven repository, it can be used to create a minimal, standardized Spring Boot project by executing the following command:

mvn archetype:generate -DarchetypeCatalog=local \
    -DarchetypeGroupId=com.nightsky -DarchetypeArtifactId=spring-boot-minimal -DarchetypeVersion=1.0.0
                

Note that the values of the command line arguments (archetypeGroupId, archetypeArtifactId, and archetypeVersion) must match the values of the corresponding properties in the archetype.properties file used to create the Maven archetype.

Maven will prompt you for the following values:

springBootVersion

The version of Spring Boot to use in your new project

groupId

The group or organization identifier for your new project

artifactId

The identifier of the new project within your group or organization

version

The initial version of the new project

package

The root Java package for your source files

After providing the required values, Maven will ask you confirm the values you provided. Type Y and press Enter to confirm your entries.

Alternatively, if you want to skip the prompts, you can provide all required variable values on the command line like so:

mvn archetype:generate -DarchetypeCatalog=local \
    -DarchetypeGroupId=com.nightsky -DarchetypeArtifactId=spring-boot-minimal -DarchetypeVersion=1.0.0 \
    -DgroupId=com.myorganization -DartifactId=myproject -Dversion=1.0.0 -Dpackage=com.myorganization.app \
    -DspringBootVersion=2.7.7 -DinteractiveMode=false
                

Verify Your Spring Boot Project

After executing the mvn archetype:generate command, your working directory should have a child directory with a name matching the value you chose for the artifactId variable.

To verify that your Spring Boot project was created properly, enter the new project directory and run the Spring Boot application. For example:

cd myproject
mvn spring-boot:run
                

If your project was created properly, you should see the Spring Boot banner displayed with the version that you chose, and Apache Tomcat should be listening on port 8080.