Maven Archetypes explained

Maven Archetypes explained

As a kid, I had a fascination with kits. Any kind of kit would do: toolkits, first aid kits, sewing kits. There was something about the idea of a kit that captured my imagination; a collection of stuff, all put together for a purpose, but without any details about what that purpose would be. On the one hand, there was a specific use for each component; and yet, what they would ultimately be used for…who knew? It was a license to imagine.

I thought of this recently as I prepared a new kind of kit for us in Engineering at Datalogics: a kit for making software projects. Specifically, I created something I’d never made before: A Maven archetype.

We’ve been using Maven to build our Java projects for a while now, and it’s proven very useful; its ability for resolving dependencies alone has taken a lot of the pain out of Java development. Now, instead of adding individual packages to my class path, I just drop a chunk of XML into my POM file, and voilà! I can pull in a new third-party library in less than a minute, and be sure that it will work just as painlessly for my fellow developers.

Projects need more than just JARs though, we’ve built up a lot of infrastructure around our products. Every one of our repos now includes:

  • Java source code
  • Unit testing code
  • Integration testing code
  • Input files for the test code
  • Other resources, such as images and fonts
  • Javadoc, some of it extracted from the source, but also additional pieces
  • Markdown documentation, including release notes and a README file
  • Additional user documentation
  • The Maven POM file
  • Additional shell scripts that help with development

That’s a lot of material to copy into every project! Fortunately, there’s an easier way, a Maven Archetype.

An archetype is a Maven project template. It collects the resources required for a project into a form that can be reproduced on command. Just like any Maven project, it is an artifact that can be stored in a repository allowing it to be easily shared by other developers.

For our archetype, I started with our PDFJT Samples Repo. This repo is already set up for Java sample development, and is buildable with Maven. I checked out a fresh copy and removed all samples except for “HelloWorld.java.” Of course, to get the unit tests to pass, I had to remove all tests except the corresponding “HelloWorldTest.java” as well.
At this point, I had a sparse but buildable project. Next, I generated the archetype with Maven:

mvn archetype:create-from-project

This converts the project into an archetype, the output is in the target folder, just like any other Maven build.

However, the output folder is hard to work with while I’m developing; what I really want is a meta-project – something that we can use to set up other ‘real’ projects, but that I can treat like an ordinary project while I’m working with it. To do this, I used rsync to copy the built archetype into a new Git repo—this way, it can be tracked as a project. Once there, I made additional refinements to get it into usable shape.

A nice feature of working with Maven is that it makes it easy to test archetypes – all I have to do is install it to my local binary repo:

mvn install

And then, switching to another directory, I can try it out:

mvn archetype:generate

This lists a catalog of all known archetypes, including ones from the central Maven repository. To trim it down, I can add a filter like “datalogics:”

Once I’ve selected the repo, I’m prompted to enter the group ID, artifact ID, version and package name for the new project. In addition, I set it up to ask for the project name and description, as well. A new folder is created with a complete project that can be built and run right away, like any other Maven project:

mvn verify

I went through this process several times, getting created project to show up exactly as I wanted it. When time came to ‘release’ the archetype, all I had to do was a standard Maven deploy from the archetype folder:

mvn deploy

This pushed the project to our repository manager, a server for holding Maven artifacts for distribution. We currently run a local installation of JFrog Artifactory to support our developers.

Now my fellow developers can quickly get new PDFJT projects up and running with a single command, and most of what they’ll need will be right there, ready to run. We left several items, like test inputs and release notes, in the archetype; not every project will need all of them, but we figured it was easier to remove unnecessary components than to force developers to obtain them later.

The archetype has worked great so far, we’ve already used it to create a demo for using PDFJT with hardware security modules. It’s already proving a very handy kit to have around!

Leave a Reply

Your email address will not be published. Required fields are marked *