Creating a New Maven Archetype

A Maven archetype is like a template project. You can create a new project quickly from this template. If you find yourself creating same type of projects over and over again, it may be useful to create an archeype for it.

In this tutorial I will show you how to create a new Maven archetype.

Our New Archetype

We will create a new archetype to create Java EE web projects from it. Maven already comes with the very popular “maven-archetype-webapp”. But, it has several areas that need improvement:

  • The generated project has no dependency defined, not event for the Java EE API.
  • The folder for Java source is not created.
  • The web.xml file uses ancient Servlet API level 2.3. This needs to be updated to level 3.0.

We will create a new archetype that will fix these issues.

The easiest way to create a new archetype is from an already created project. So, we will take these general steps:

  1. Create a new starter web project based on maven-archetype-webapp.
  2. Fix the issues I have identified.
  3. Generate a new archetype from our project.

Create the Starter Project

Create a new web project by entering:

mvn archetype:generate \
 -DarchetypeArtifactId=maven-archetype-webapp \ \
 -DartifactId=MyWeb \

Now, we will customize the generated project and add the enhancements we proposed.

Go inside MyWeb folder and open pom.xml. Add dependency for the Java EE API by adding these lines:


Save and close the file.

Next, we will create the folder for Java source files. We will add a sample Servlet file there.

Go inside the src/main folder and create a folder called java.

In the newly created java folder, create a new Java file called Add the following code to that file.

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class SimpleServlet extends HttpServlet {
 protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {

Save and close the file.

Finally, we will fix the web.xml to use Servlet API level 3.0.

Open src/webapp/WEB-INF/web.xml in an editor. Delete the DOCTYPE and the beginning <web-app> lines:

 "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "" >


In its place, enter these lines:

<?xml version="1.0" encoding="UTF-8"?>


Save and close the file.

Our project is now ready. We can now generate an archetype from it.

Generate a New Archetype

Go to the root of the starter project where pom.xml is located. Then, enter this command to create the new archetype:

mvn archetype:create-from-project

This will create a new archetype inside the target/generated-sources/archetype folder of the starter project. Go inside that folder. An archetype is itself a Maven project and you will see the pom.xml file in that folder. Open the pom.xml in an editor. Change the group ID, archetype name (artifact ID) and version as you see fit. For example:


<name>An enhanced Web App archetype for Java EE 6</name>

Scroll down and locate the lines:


The final WAR file is hard coded to MyWeb. This will not work very well. We should use the placeholder variable ${artifactId} instead. Change the line as follows:


Now, if we create a new project from this archetype called SimpleWeb, the WAR file will be called SimpleWeb.war.

Save changes and close the file.

All the starter files for a project shipped with an archetype is located in the src/main/resources/archetype-resources folder of the archetype project. Go inside that folder. Open the pom.xml file. This will be the POM for a new project created from this archetype. You should see dependency for Java EE 6 there.

Similarly, you will see the sample Servlet Java file in there. You can now freely add new files to the archetype if you need to. These files will go inside the src/main/resources/archetype-resources/src/main of the archetype project. However, keep in mind, if you start changing the source files, you will no longer be able to regenerate the archetype from the starter project.

Test the New Archetype

Go to the root of the archetype project. That will be the target/generated-sources/archetype folder of the starter project. You should create a new Git repo based on this folder and commit it. If the starter project is non-trivial, you probably also need to save that in Git.

From the root of the archetype project, run:

mvn clean install

Now, that the arcehtype is installed in the local repository, we can create a new project based on it. Go to a suitable folder where the new project will be created. Then run:

mvn archetype:generate \
 -DarchetypeArtifactId=my-archetype-web \ \
 -DarchetypeVersion=1.0 \
 -DgroupId=com.example.web \
 -DartifactId=NewWebProject \

Carefully note the coordinates of the archetype. They need to exactly match the archetype we have created.

Our new project NewWebProject will inherit all the enhancements we have made. Go inside the project folder. Run:

mvn package

This will create target/NewWebProject.war. Deploy it in a server like TomEE. Then, try accesing the sample Servlet:

curl -v http://localhost:8080/NewWebProject/simple

This should work without a problem (HTTP status code 200).

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s