This post originated from an RSS feed registered with Java Buzz by Wilfred Springer. Original Post: Organizing Archetypes Feed Title: Xebia Blog » Wilfred Springer Feed URL: http://blog.xebia.com/author/wspringer/feed/?category=java Feed Description: Crazy ideas. Read this blog at your own risk. Latest Java Buzz Posts Latest Java Buzz Posts by Wilfred Springer Latest Posts From Xebia Blog » Wilfred Springer

Maven archetypes are an excellent way of allowing people to create instances of a particular type without having them to worry about dealing with all of the peculiarities of that specific type of project. And the latest incarnations of the Maven Archtetype Plugin are actually way better than I realized. The versions I used in the past did not include the ability to actually use Velocity templates to generate source code in a particular way. Pretty cool.

Since some of the dependencies of Preon are not in the central Maven repository yet, I decided to create an archetype of a Maven project, to make sure all of the external repositories are set correctly. But then the question is: how do you keep all of this organized in your project? Generating a project from an archetype is pretty easy nowadays, but either the archetypes should be present on your user's system, or they should specify the location of a catalog file. However, that catalog file will have references to the version of your archetypes. How do you make sure these versions are correct? And how do you make sure your archetype catalog is available online, without having to manually deploy it over and over again?

I couldn't find a real policy for keeping all of this organized, so this is what I did:

Module for Archetypes

First of all, I decided to have a module for all of my archetypes, as outlined in the picture above. Having a dedicated module that organizes all of my archetypes allows me to set specific policies for my archetypes, and it also allows me to keep my catalog file in a sensible location. (The catalog has references to all of the individual archetypes.)

Parameterized archetype-catalog.xml file

Now, I want my catalog of archetypes to have references to relevant versions of the archetypes. One way to get there is to carefully update the file by hand once a new version of the archetype is available. But that's also quite boring, and error-prone. So, what I did instead is keep the archetype-catalog.xml file in src/main/resources, and make sure the Maven Resources Plugin is kicking in to substitute variable references with relevant values.

<archetype-catalog>
  <archetypes>
    <archetype>
      <groupId>nl.flotsam.preon.archetypes</groupId>
      <artifactId>preon-simple-archetype</artifactId>
      <version>${project.version}</version>
      <repository>http://preon.flotsam.nl/archetypes</repository>
      <description>Simple Preon project, with dependencies to everything required.</description>
    </archetype>
  </archetypes>
</archetype-catalog>

Attaching catalog files

So, now we have catalog files that have correct version references, but it's still impossible to download them from a certain location. I started wondering about a solution, and first considered having them included as site resources. But then I realized I could also attach these files as new artifacts. That has a couple of interesting side effects, one of them being that they will also get uploaded to the Maven repository with every new deployment of my project. Just what I wanted. So, by adding a little configuration, I made sure the files were getting attached.

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>build-helper-maven-plugin</artifactId>
  <version>1.3</version>
  <inherited>false</inherited>
  <executions>
    <execution>
      <id>attach-artifacts</id>
      <phase>package</phase>
      <goals>
        <goal>attach-artifact</goal>
      </goals>
      <configuration>
        <artifacts>
          <artifact>
            <file>target/classes/archetype-catalog.xml</file>
            <type>xml</type>
            <classifier>catalog</classifier>
          </artifact>
        </artifacts>
      </configuration>
    </execution>
  </executions>
</plugin>

Panic: SNAPSHOT versions!

So far, it sounds pretty sensible. But then a problem turned up: if you attach files, and you deploy them to a repository, then the versions will get a suffix making the version unique for that particular build. That works fine with the usual plugins, but not with the Maven Archetype Plugin. Remember that - although the archetype-catalog.xml file now has versions correctly generated by the Maven Resources Plugin - it will still have a version reference without the unique build suffix. However, the Maven Deploy Plugin will upload versions that include the unique build suffix.

In order to solve that, I replaced the distributionManagement section in the pom.xml file of the preon-archetypes module, and made sure that - for snapshotRepository settings - the uniqueVersion is set to false. This will drop the unique suffix. However, it will also mess up your snapshot repository. In order to keep it tidy, the archetypes are deployed to a dedicated repository: the archetypes repository.

Done?

With all of this work done, creating a project from one of the archetypes is pretty easy:

mvn -Dhttp://preon.flotsam.nl/archetypes/nl/flotsam/preon/archetypes/preon-archetypes/1.1-SNAPSHOT/preon-archetypes-1.1-SNAPSHOT-catalog.xml archetype:generate

That's it. After that, you will able to select the specific archetype you want to instantiate, and Maven takes care of the rest.