Create a Maven archetype

After creating our project structures from the basic maven archetypes since starting to use Maven I thought it was time to start automating the process. It wasn't too painful but not quite as straight forward as I hoped either so I thought it was worth writing an article about my experience.

Example

Here's an example of the code which I've got working, so feel free to start from there.  Click on the link on my website post to download (it should anchor so that the zip file link is at the top of the page)

Link to zip 

I found it easiest to create a Java Project and copy the files into there and then convert the project to Maven project but whatever takes your fancy.

Using property names

The hard part of creating the archetype was getting the property names to show throughout the code. I had followed instructions on other websites that had mentioned the __my-property-name__ convention to get this to work. However after following the instructions on the Maven website I found that updating the files from the resulting project didn't work.

After some more searching I found out about the archetype-metadata.xml file which appears to be quite important. Once this was added into the system I found that my property names started resolving to their expected values. It also gave me an opportunity to add additional parameters like the projectName used in the example. I found that if you want to place property names in a filename or directory name then you needed to use the __my-property-name__ convention but inside the file you need to use the ${my-property-name} convention.

The archetype-metadata.xml file also meant that I could do away with the archetype.xml file that was suggested in the Maven tutorial. With this file you had to say exactly which files you wanted to include into your project, however by specifying **/* for the include tag of the archetype-metadata.xml file it included all of the files inside that folder without having to update the config each time the files changed.

Velocity and If Statements

The maven archetype build uses the velocity templating engine which means that you have a lot of control over what you can do. I'm not going to go through all the details of what Velocity does as there's a perfectly good website for that here.

What I will have a quick chat about is the if statement functionality. This is really powerful as I had initially started creating seperate archetypes depending on the type of project I was creating. I then quickly realised that a lot of these shared the same structure and files so managed to merge most of them together into a single archetype by using a mix of a new project type required parameter (as mentioned about above) and the velocity if statement. An example of the statement is shown below, the keyword #else can also be used.

#if( ${projectType} == "cms" || ${projectType} == "ecommerce" ) 
private int myNewVariable;
#end

Adding empty folders

This one had me stuck for a little while as I was trying to add empty folders into the archetype-resources section but they were not appearing in the generated project. The answer is to include them as a fileset in the archetype-metadata.xml as I have done in the example archetype with the "/src/main/webapp" folder.

<fileSet filtered="true" encoding="UTF-8">
<directory>src/main/webapp</directory>
</fileSet>

Create a project from the archetype

I use Eclipse as my development environment, if you are using NetBeans or others I imagine this part will be slightly different. In order to create the archetype from the project it was simply a case of right clicking the POM file and choosing to run Maven install.

Creating a new project from the archetype however was slightly more tricky as when you go to choose the archetype from the list it's not there. I had to add an archetype using the 'Add Archetype' button on the page where you would normally select the archetype from the list. For the example I just put in com.aplos for the Archetype Group Id, example-archetype for the Archetype Artifact Id and 1.0 for the Version, I left the repository url field blank and Eclipse found the archetype.

Conclusion

Following these steps should allow you to create a wide range of project structures and base files. I still cannot see how to populate the group id and package name for the project to the default of com.aplos. However I'm happy for now and if I learn the other parts I'll be sure to update this article, or if you know I'd be grateful to hear from you.