Quick guide to building Maven archetypes

Overview

Maven archetypes are project templates that offer a quick and easy way to start a new software project that is consistent with an organizations best practices. This blog entry demonstrates the technical steps one can take to convert a skeleton project to a Maven archetype, to store the archetype into a Nexus Repository and finally to test the archetype by generating a new Maven project from the archetype. In a previous blog entry I covered setting up a Nexus Repository click here if you have an interest in that material, it is somewhat relevant to the content in this blog entry.

Pre-requisites

A JVM and Maven should be installed on the developer machine, Java and Maven should both be available on the systems/users path variable.

1. Create a project skeleton

The best way to start any new project in Maven is to utilize an existing archetype. To see a list of available archetypes from a specific repository type the following command.

mvn archetype:generate -DarchetypeCatalog=http://localhost:8081/nexus/content/repositories/bcn-archetypes

This command triggers Mavens archetype wizard.

The example archetype created in this document used  a pre-created “basic-java-app” as a starting point, this archetype existed in a local Nexus Repository but it is very similar to the publicly available archetype “maven-archetype-simple”

Running through the archetype wizard will create a basic skeleton Maven project.

After Maven has created the project,  edit it to the desired standards of the archetype.

*

The example project is created for the purposes of generating a batch archetype for my employer. The original skeleton project was edited to add dependencies related to the  organizations database framework library and to test database connectivity.  The table below demonstrates the file changes done to the skeleton project.

Initial skeleton Maven Project Edited skeleton project

From a file layout there was NOT much change, the bulk of the changes where implemented within dependencies of the projects pom.xml. Once again edit the skeleton to fit the needs of the archetype you need to create.

From $SKELETON_PROJECT_ROOT execute the following command to confirm the skeleton project compiles and executes tests successfully

mvn package

2. Create Maven archetype project from skeleton

When satisfied with the skeleton project, generate an archetype project from the skeleton by running the following command at the skeleton projects root.

mvn archetype:create-from-project

3. Copy generated files into a new Maven project location

After step 2 has executed it will create the archetype project at the location $SKELETON_PROJECT_ROOT/target/generated-sources/archetype, copy all of the files at this location into a separate directory outside of the Skeleton project.

This new location is the root of your Archetype project. It should look similar to the screenshot to the right.

Note: “$ARCHETYPE_PROJECT_ROOT/src/main/resources/archetype-resources” contains the initial files that will be generated when the archetype is called. Nothing should have to be edited in this section.

*

4. Edit the new archetype project with the desired settings

Open “$ARCHETYPE_PROJECT_ROOT/src/main/resources/META-INF/maven/archetype-metadata.xml”,  this file declares the files and/or file-types Maven will perform search and replace activities on during the build process.  Make changes based on the archetypes requirements.

An example edit maybe to add support for more file-types in the “resources” directory.

<fileSet filtered="true" encoding="UTF-8">
 <directory>src/main/resources</directory>
 <includes>
 <include>**/*.txt</include>
 <include>**/*.properties</include>
 <include>**/*.resource</include>
 <include>**/*.conf</include>
 <include>**/*.xml</include>
 <include>**/*.xsd</include>
 </includes>
</fileSet>

Edit $ARCHETYPE_PROJECT_ROOT/pom.xml file with the desired name and description details for the archetypes and add support for the Maven “deploy” goal, the deploy goal change allows the archetype to be stored into the desired repository.

<distributionManagement>
 <repository>
 <id>my-repo</id>
 <url>http://localhost:8081/nexus/content/repositories/my-archetypes</url>
 </repository>
</distributionManagement>

 

5. Build the archetype project and deploy to the repository

From $ARCHETYPE_PROJECT_ROOT run the Maven commands to build and store the archetype into the repository.

mvn clean install
mvn deploy

6. Test the new archetype

a.  From a location outside of a an existing Maven project execute the maven command to list available archetypes (remember to point to the repository where the new archetype has been installed).

mvn archetype:generate -DarchetypeCatalog=http://localhost:8081/nexus/content/repositories/my-archetypes
b.  Run through the archetype wizard to populate the project.  This should result in the creation of a Maven project in the current directory with the desired directory layout
c.  change directory into the “artifactId” value entered at the archetype wizard prompt
d.  Execute “mvn package” to ensure the new application compile and executes tests successfully