Maven In Depth: Creating A Custom Archetype For Spring Boot Project

Hi guys! We gonna take in-depth look at one of the advanced features of Apache Maven and the most I’ve ever liked… we’re going to see together how to create a custom archetype for a Spring Boot project, but first, have you ever encountered problems in managing your java projects? Have you ever had problems within your team with the structure or naming convention of your projects? Are you tired of writing redundant code on a daily basis? Are you a java developer, but a lazy one? If the answer is yes, then a Maven custom archetype is the solution to a large part of your problem.

Before starting! I assume you are familiar with Apache Maven, otherwise you can enjoy this Baeldung tutorial.

Introduction

What is Maven Archetype? How to use it? And how to create a custom one?
Don’t worry, we’ll answer all these questions in this article step by step.

What is Maven Archetype?

Maven archetypes are simply a project templates that can help us quickly create a maven starter project based on its type. It's a great tool to start a maven project with the least amount of effort.

There are wide options of archetypes available to us. Some of the popular archetypes include maven-archetype-quickstart, maven-archetype-webapp, maven-archetype-archetype…

Create a Maven Archetype

To create a maven project with a specific archetype, we can use:

mvn archetype:generate

This command will ask us to choose an archetype and will then create our maven project from it.

We can also define our custom archetype. It is specifically helpful when we have multi-module project which share the same structure. We can simply standardize a template to use for creating our modules.

In this article, we will use a Spring Boot multi-module project:

This is a general structure of the project
This is a general structure of the project
General structure screenshot

This demo project consists of two modules (starter and sample), the starter module contains our main application and use the sample module as a library.

PS: the code will be available at the end of this article.

Let’s focus a little bit on the demo-sample module:

This is the sample module
This is the sample module
Sample module screenshot

This module contains a controller package that contains a controller class with a helloWorld() method that returns a hello world message.

For future purpose, we want to make a generic template (Maven Archetype) for our modules, to be used whenever we want to generate new module and avoid recreating each module and their classes from scratch.

To create our own Maven Archetype there are two ways:

Create a Maven Archetype from existing project:

It’s fairly easy to create a Maven archetype from one of our existing modules. All we have to do is run this command from the root directory of our project:

mvn archetype:create-from-project

Maven command

Create a Maven Archetype using a predefined Archetype (maven-archetype-archetype):

We can directly generate an archetype project by using this predefined Maven Archetype called maven-archetype-archetype

mvn archetype:generate -B -DarchetypeArtifactId=maven-archetype-archetype

Either way, after the successful creation of the archetype, we get this archetype generated under /target/generated-sources

Generated archetype

Now that we have generated the archetype structure, we can start modifying our generated sources:

  • Modify the target/generated-sources/archetype/src/main/resources/archetype-resources/pom.xml to add or remove additional dependencies as needed.
Project’s pom.xml file
  • Modify the target/generated-sources/archetype/pom.xml as we want, we can change the groupId, the artifactId or the version of our generated Archetype.
Archetype’s pom.xml file
  • Modify our Archetype Metadata file (called also ArchetypeDescriptor). The archetype-metadata.xml stores the metadata of our archetype and is present in the folder target/generated-sources/archetype/src/main/resources/META-INF/maven.
Archetype’s archetype-metadata.xml file

Let’s explain in details the elements of the archetype-metadata file and other global details:

<requiredProperties> tag defines the properties required to generate a project from this archetype. We can specify the default value of the property, as we can also define a regular expression used to validate the entered property.

<fileSet> tag defines where to find the module files to be used in the generation of the archetype project.

filtered = “true” means that placeholders are replaced by the values provided when generating the project and the selected files will be used as Velocity templates.

packaged = “true” means that the selected files will be generated in a directory structure that is prepended by the package property.

If the name of the file or directory contains __property__ pattern or if the file contains ${property}, it is replaced by the corresponding property value.

Building a Maven Archetype

We can build our archetype project now by going to /generated-sources/archetype and run:

mvn clean install

We can find our built jar under /generated-sources/archetype/target and it will be installed in our local Maven repository under /.m2/repository/<group_id>

Using Created Archetype

By now, we have successfully installed our customized archetype. To generate a new “dummy” module from this newly created archetype, we will first switch to our project/demo root directory and then run:

mvn archetype:generate -DarchetypeGroupId=com.example
-DarchetypeArtifactId=demo-custom-archetype
-DarchetypeVersion=1.0-SNAPSHOT
-DgroupId=com.example
-DartifactId=demo-dummy
-Dversion=1.0-SNAPSHOT

Maven generate command

Then it will ask us if we want to continue with the default values, otherwise we can enter our desired values as shown below:

As we can see here we set the package, the configName and the controllerName to Dummy with the present of the Regex validation.

After further confirmation, we have our new dummy module in our project:

The last step now is to run this project and test it !

Sample test
Dummy test

Well done! Our new generated dummy module works perfectly well as the sample module.

Conclusion

Maven Archetype one of the greatest tools given by Maven, it absolutely makes things easier and save us a lot of time. Here we are at the end of this chapter. I hope it was a good and useful experience.

GitHub: https://github.com/Hassib-Maslah/custom-maven-archetype-demo

Do not hesitate to contact me :

Gmail: maslah.has@gmail.com

Linkedin: https://www.linkedin.com/in/hassib-maslah

Software Engineer

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store