Guide to Creating Archetypes

Creating an archetype is a pretty straight forward process. An archetype is a very simple plugin, that contains the project prototype you wish to create. An archetype is made up of:

• an archetype descriptor (archetype.xml in directory: src/main/resources/META-INF/). It lists all the files that will be contained in the archetype and categorizes them so they can be processed correctly by the archetype generation mechanism.
• the prototype files that are copied by the archetype (directory: src/main/resources/archetype-resources/)
• the prototpye pom (pom.xml in: src/main/resources/archetype-resources)
• a pom for the archetype (pom.xml in the archetype's root directory).

To create an archetype follow these steps:
1. Create a new project and pom.xml for the archetype plugin
An example pom.xml for an archetype plugin looks as follows:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>my.groupId</groupId>
  <artifactId>my-archetype-id</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>maven-plugin</packaging>
</project>

All you need to specify is a groupId, artifactId and version. These three parameters will be needed later for invoking the archetype via archetype:create from the commandline.
2. Create the archetype descriptor
The archetype descriptor is a file called archetype.xml which must be located in src/main/resources/META-INF/ An example for an archetype descriptor can be found in the quickstart archetype:

<archetype>
  <id>quickstart</id>
  <sources>
    <source>src/main/java/App.java</source>
  </sources>
  <testSources>
    <source>src/test/java/AppTest.java</source>
  </testSources>
</archetype>

The <id> tag should be the same as the artifactId in the archetype pom.xml.
An optional <allowPartial>true</allowPartial> tag makes it possible to run the archetype:create even on existing projects.
The <sources>, <resources>, <testResources> and <siteResources> tags represent the different sections of the project:

• <sources> = src/main/java
• <resources> = src/main/resources
• <testSources> = src/test/java
• <testResources> = src/test/resources
• <siteResources> = src/site

<sources> and <testSources> can contain <source> elements that specify a source file.
<testResources> and <siteResources> can contain <resource> elements that specify a resource file.
Place other resources such as the ones in the src/main/webapp directory inside the <resources> tag.
At this point one can only specify individual files to be created but not empty directories.
Thus the quickstart archetype shown above defines the following directory structure:
archetype

|-- pom.xml
`-- src
    `-- main
        `-- resources
            |-- META-INF
            |   `-- archetype.xml
            `-- archetype-resources
                |-- pom.xml
                `-- src
                    |-- main
                    |   `-- java
                    |       `-- App.java
                    `-- test
                        `-- java
                            `-- AppTest.java

3. Create the prototype files and the prototype pom.xml
The next component of the archetype to be created is the prototype pom.xml. Any pom.xml will do, just don't forget to the set artifactId and groupId as variables ( ${artifactId} / ${groupId} ). Both variables will be initialized from the commandline when calling archetype:create.
An example for a prototype pom.xml is:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>${groupId}</groupId>
  <artifactId>${artifactId}</artifactId>
  <packaging>jar</packaging>
  <version>${version}</version>
  <name>A custom project</name>
  <url>http://www.myorganization.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

4. Install and run the archetype
Now you are ready to install the archetype:

mvn install

Now that you have created an archetype you can try it on your local system by using the following command. In this command, you need to specify the full information about the archetype you want to use (its groupId, its artifactId, its version) and the information about the new project you want to create (artifactId and groupId). Don't forget to include the version of your archetype (if you don't include the version, you archetype creation may fail with a message that version:RELEASE was not found)

mvn archetype:create                                    \
  -DarchetypeGroupId=<archetype-groupId>                \
  -DarchetypeArtifactId=<archetype-artifactId>          \
  -DarchetypeVersion=<archetype-version>                \
  -DgroupId=<my.groupid>                                \
  -DartifactId=<my-artifactId>  

Once you are happy with the state of your archetype you can deploy (or submit it to ibiblio) it as any other artifact and the archetype will then be available to any user of Maven.
Alternative way to start creating your Archetype
Instead of manually creating the directory structure needed for an archetype, simply use

mvn archetype:create
  -DgroupId=[your project's group id]
  -DartifactId=[your project's artifact id]
  -DarchetypeArtifactId=maven-archetype-archetype
Afterwhich, you can now customize the contents of the archetype-resources directory, and archetype.xml, then, proceed to Step#4 (Install and run the archetype plugin).