Introduction:

Maven archetypes are the project templates which can help us quickly create a maven starter project based on its type. It’s a great tool to bootstrap a maven project with least 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. 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 many modular apps in our project which share the same structure. We can simply standardize a template to use for creating our project modules.

In this tutorial, we’ll learn to create and use our own Maven Archetype.

Creating Maven Archetype:

It is pretty easy to create a Maven Archetype from one of our existing projects. All we need to do is to execute:

mvn archetype:create-from-project

from the root directory of our project.

Optionally, we can directly generate an archetype project using archetype-maven-plugin:

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

Either way, after successful archetype creation, we would see archetype files generated at target/generated-sources/archetype.

Now that we have generated the archetype structure, we can choose to:

• Modify the target/generated-sources/archetype/pom.xml to add or remove extra dependencies based on our requirements
• Modify our Archetype Metadata file – target/generated-sources/archetype/src/main/resources/META-INF/maven/archetype-metadata.xml

Archetype Metadata Descriptor:

Let’s quickly look at what does the archetype-metadata.xml contains.

The archetype-metadata.xml stores the metadata of our archetype. It is present at the location – /META-INF/maven folder within the jar.

The metadata file structure looks similar to:

<archetype-descriptor
  ...
  name="my-custom-archetype">
 
    <requiredProperties>
        <requiredProperty key="name">
            <defaultValue>ProgrammerGirl</defaultValue>
        </requiredProperty>
    </requiredProperties>
 
    <fileSets>
        <fileSet filtered="true" packaged="true">
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.java</include>
            </includes>
        </fileSet>
    </fileSets>
 
    <modules>
        <module name="sub-module-1"></module>
        <module name="sub-module-2"></module>
    </modules>
 
</archetype-descriptor>

Here are a few important tags and their purpose:

• <requiredProperties> tag defines the required properties to generate a project from this archetype. A user can also choose to go ahead with the property’s defaultValue
• <fileSet> defines how to use the project files located in the jar file to generate a project. If a file or a directory name contains __property__ pattern, it is replaced with corresponding property value
• In a filtered fileSet property placeholders gets substituted with provided values during project generation
• packaged = “true” means that the selected files will be generated in a directory structure that is prepended by the package property
• For a multi-module project, we can use <modules> tag to define the sub-modules

Building the Archetype:

Once we are done with modifications in our pom.xml and archetype-metadata.xml files, we can build our archetype project.

Let’s go to the path /generated-sources/archetype and execute:

mvn clean install

It will install the plugin in our local repository. We can cross-check whether our newly created archetype is present in our local repository:

mvn archetype:generate -DarchetypeCalalog=local

Using Created Archetype:

By now, we have successfully installed our custom archetype in our local repository. To generate a project from this newly created archetype, we’ll use:

mvn archetype:generate -DarchetypeGroupId=com.programmergirl.archetypes
                       -DarchetypeArtifactId=my-custom-archetype
                       -DarchetypeVersion=1.0-SNAPSHOT
                       -DgroupId=com.programmergirl
                       -DartifactId=sample-project
                       -Dversion=1.0-SNAPSHOT

where com.programmergirl.archetypes & my-custom-archetype are the groupId and artifactId of the main archetype project we created earlier. The parameters -DgroupId and -DartifactId specify the groupId and artifactId of newly generated project.

Conclusion:

In this tutorial, we discussed how to create a custom maven archetype and use it to generate multiple projects.