Saturday, May 12, 2012

Maven Archetypes Part 1: Where Do I Start?

creating the initial files and directories

Let's start with creating a directory for your archetype:

$ mkdir sample-archetype

Inside of that directory, let's create the files and directories you're going to need:

You should now have the current file structure in your sample-archetype directory:

Here's a breakdown of what the things you added do:

  • pom.xml: This tells Maven to construct the archetype artifact. It's a pretty standard pom and won't change much if at all for the life of your archetype.
  • src/main/resources/archetype-resources: This is the directory that Maven looks at to generate your project. The files you add in here will get copied and filtered into your project.
  • src/main/resources/archetype-resources/pom.xml: This will be the main pom file for the project your archetype creates.
  • src/main/resources/META-INF/maven: This is where Maven looks to find information about what to include in your project, what properties to ask the user for, and what files it should filter.
  • src/main/resources/META-INF/maven/archetype-metadata.xml: This is the file that Maven uses to configure your project. It includes instructions for how the files of your project should be filtered and where they should exist

setting up the pom files and updating the archetype metadata

Alright, now that we have all the files set up, let's construct the pom for the archetype (not the generated project) which is the pom.xml file in the current directory you're currently in (your sample-archetype directory):

Now that we have the archetype's pom file complete, let's add what we need for the project we're looking to generate. We'll start small and just generate a pom as the artifact for the project. When you're adding files for the project you'll be generating via the archetype, you'll use a lot of variables in your poms like ${artifactId} and ${version}. You'll want to specify that those poms should be filtered via the archetype-metadata.xml file so that those values turn into what the user generating the project is prompted for. Add the contents below to the src/main/resources/archetype-resources/pom.xml file:

Next, we need to update the src/main/resources/META-INF/maven/archetype-metadata.xml file to include the pom in our project:

installing your archetype and creating a project from it

Now that we have all of the basic files we need in place, go ahead and install the archetype running:

$ mvn clean install

Installing the archetype should place it in your local repository (wherever you have that configured to be, typically ~/.m2/repository). Update your local catalog (on my system, ~/.m2/archetype-catalog.xml) and add your new archetype:

After adding that to your archetype catalog, run the following command (but go back one directory first so you don't try to create a project within your archetype's directory):

You should see the following output (or something similar) after maven checks your repos:

Select the sample-archetype and add the criteria for the project as you're prompted:

You should now have a sample-project directory created that contains a pom.xml that should look like this:

Go to the directory for your newly created project, and install the project with the following command:

You should see the following output:

We've got ourselves an archetype now!

Don't stop here though. There's a lot of value in learning how to build a jar from an archetype, so check that post out next!

1 comment:

  1. Thanks for this entry! :) I think you missed the pom.xml code after the line "Add the contents below to the src/main/resources/archetype-resources/pom.xml file:"

    There is nothing there.