Maven Custom Archetype from Eclipse Project

Maven custom archetypes helps in creating a specific type of project structure which is not available in any standard maven archetypes. In this maven tutorial, we will learn to create custom archetypesfrom an eclipse project.

It is very useful in some scenarios specially when we need custom contents in the generated maven project, which maven does not provide out of the box.

Why custom Archetype is required?

In general maven and some third party providers provide some archetypes which is useful in jump start our maven projects easily. But in our day work life we might face some scenarios where we need to create custom project structure for the below reasons:

Need to introduce/enforce a particular project structure (including package and skeleton class) within the organization.
Reduces lots of time in setting up the project structure, increasing developer’s productivity by quick start to actual work.
Reduces code review effort, by ensuring that the project structure and intended artifacts are in place.

Create Custom Archetype

Maven has already provided one new archetype maven-archetype-archetype to create new archetypes.

mvn archetype:generate -B -DarchetypeArtifactId=maven-archetype-archetype  -DgroupId=com.howtodoinjava.archetype -DartifactId=maven-howtodoinjava-archetype -Dversion=1.0-SNAPSHOT

Let’s understand above command.

-DarchetypeArtifactId=maven-archetype-archetype is the archetype that maven has provided to create a new custom archetype.
-DgroupId=com.howtodoinjava.archetype is the group id of the archetype we will now create.
-DartifactId=maven-howtodoinjava-archetype is the artifactId of the archetype we will now create.
-Dversion=1.0-SNAPSHOT is the version of the maven archetype.

All the parameters here are self-explanatory and intuitive. Still we can anytime follow official maven documentation for more details.

We need to now run this command from command prompt and before that make sure you have setup the maven class path.

So once you run this from command prompt, you will have one maven project generated in the same directory from where you have initiated the mvn command.

Import Project to eclipse

Now next job is to import this project in eclipse for further refinement to fit our requirement. After import the eclipse project structure will look something like this.

Once this is imported in eclipse, we need to do the below steps.

Delete the contents of /src/main/resources/archetype-resources/src/main/java & /src/main/resources/archetype-resources/src/test/java – mainly App.java and AppTest.java
We need to rename file /src/main/resources/META-INF/maven/archetype.xml to archetype-metadata.xml, later we need to change the contents of this file, we will see that in a while.

After the above steps, the folder structure will look like,

Create Template Files

Now we will create some template files for the classes and resources that the archetype should generate everytime.

Create a template java file in \src\main\resources\archetype-resources\src\main\java\__project-name__.java with the contents:

package ${package};

public class ${project-name} {

    public static void ${project-name}SampleMethod() {

      System.out.println("Sample method generated by maven Archetype..");

    }

}

This template file will generate java files as per the values of the placeholders that will be provided in runtime. The place holder in the file name must have to be surrounded by __NAME__and the placeholder logical name separator should be hyphen (-).

Create a template for a properties file; having property key-value templates like
${project-name}.key=This is ${project-name} test property and the file name will be \src\main\resources\archetype-resources\src\main\resources\__property-file-name__.properties
because we want to generate the file name in runtime, so we have placed one placeholder in the file name.
Feel free to as many template files as your requirements.

Now we need to modify the archetype-metadata.xml like below.

– The requiredProperties section will declare all the properties that required along with their default values while generating the project from this archetype.

– The fileSets will declare the files that will be placed in the final project that will be generated.

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

<archetype-descriptor name="basic">

    <requiredProperties>

        <requiredProperty key="project-name" />

        <requiredProperty key="property-file-name">

            <defaultValue>Resource-default</defaultValue>

        </requiredProperty>

        <!--JUnit version to use in generated project -->

        <requiredProperty key="junit-version">

            <defaultValue>4.10</defaultValue>

        </requiredProperty>

    </requiredProperties>

    <!--Add new fileset for resources -->

    <!--Set filtered="true" to process files in that directory as templates -->

    <!--Set packaged="false" to remove package folder structure from resource

        directory -->

    <fileSets>

        <fileSet filtered="true">

            <directory>src/main/resources</directory>

            <!--Filters example -->

            <includes>

                <include>*.txt</include>

                <include>*.properties</include>

            </includes>

            <excludes>

                <exclude>**/*.xml</exclude>

            </excludes>

        </fileSet>

        <fileSet filtered="true" packaged="true">

            <directory>src/main/java</directory>

        </fileSet>

        <fileSet filtered="true" packaged="true">

            <directory>src/test/java</directory>

        </fileSet>

    </fileSets>

</archetype-descriptor>

We also need to change the pom.xml file under archetype-resources folder to accept the runtime GAV (GroupId:ArtifactId:Version) coordinates . We need to change it to placeholder in order to accept runtime values, for the project we will generate with this archetype.

The pom.xml under archetype-resources should look like

<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/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>${groupId}</groupId>

    <artifactId>${artifactId}</artifactId>

    <version>${version}</version>

    <dependencies>

        <dependency>

            <groupId>junit</groupId>

            <artifactId>junit</artifactId>

            <version>${junit-version}</version>

            <scope>test</scope>

        </dependency>

    </dependencies>

</project>

So we are mostly done with the changes related to Archetype changes, we should now build the archetype maven project by command mvn clean install. The project should build fine and we are ready to use this archetype to create new maven projects.

Create new projects with custom archetype

Once we have a successful build of the archetype project and this project is successfully installed in local, we will run the below command to create the maven project.

mvn archetype:generate -DarchetypeCatalog=local -DarchetypeArtifactId=maven-howtodoinjava-archetype -DarchetypeGroupId=com.howtodoinjava.archetype -DarchetypeVersion=1.0-SNAPSHOT

Maven will start interactive mode and ask for all required properties regarding new maven project. Properties with default values are skipped but the default value can be overridden if you do not confirm the configuration in the last step.

Custom archetypes inputs for example:

Once this step is complete, we should have a new project created based on the template we have developed.

So going forward, if you are in any such scenario where default maven archetypes are not enough, you can use the hidden power of maven to create your own custom archetypes.