Creating a Standard Project Archetype

Throughout this book, you have seen the archetypes that were introduced in Chapter 2 used to quickly lay down a project structure. While this is convenient, there is always some additional configuration required, either in adding or removing content from that generated by the archetypes. To avoid this, you can create one or more of your own archetypes.

Beyond the convenience of laying out a project structure instantly, archetypes give you the opportunity to start a project in the right way – that is, in a way that is consistent with other projects in your environment. As you saw in this chapter, the requirement of achieving consistency is a key issue facing teams.

Writing an archetype is quite like writing your own project, and replacing the specific values with parameters. There are two ways to create an archetype: one based on an existing project using mvn archetype:create-from-project, and the other, by hand, using an archetype. To get started with the archetype, run the following command:

C:mvnbookproficiotrunk> mvn archetype:create
-DgroupId=com.exist.mvnbook
-DartifactId=proficio-archetype
-DarchetypeArtifactId=maven-archetype-archetype

The layout of the resulting archetype is shown below:

Figure 7-8: Archetype directory layout

If you look at pom.xml at the top level, you’ll see that the archetype is just a normal JAR project – there is no special build configuration required. The JAR that is built is composed only of resources, so everything else is contained under src/main/resources. There are two pieces of information required: the archetype descriptor in META-INF/maven/archetype.xml, and the template project in archetype-resources.

The archetype descriptor describes how to construct a new project from the archetype-resources provided. The example descriptor looks like the following:

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

Each tag is a list of files to process and generate in the created project. The example above shows the sources and test sources, but it is also possible to specify files for resources, testResources, and siteResources.

The files within the archetype-resources section are Velocity templates. These files will be used to generate the template files when the archetype is run. For this example, the pom.xml file looks like the following:

<project xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>$groupId</groupId>
    <artifactId>$artifactId</artifactId>
    <version>$version</version>
    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>3.8.1</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

As you can see, the groupId, artifactId and version elements are variables that will be substituted with the values provided by the developer running archetype:create.

From here, you need to populate the template with the content that you’d like to have applied consistently to new projects. For more information on creating an archetype, refer to the documentation on the Maven Web site.

Once you have completed the content in the archetype, Maven will build, install and deploy it like any other JAR. Continuing from the example in section 7.3 of this chapter, you will use the “internal” repository. Since the archetype inherits the Proficio parent, it has the correct deployment settings already, so you can run the following command:

C:mvnbookproficiotrunkproficio-archetype> mvn deploy

The archetype is now ready to be used. To do so, go to an empty directory and run the following command:

C:mvnbook> mvn archetype:create -DgroupId=com.exist.mvnbook
-DartifactId=proficio-example
-DarchetypeGroupId=com.exist.mvnbook
-DarchetypeArtifactId=proficio-archetype
-DarchetypeVersion=1.0-SNAPSHOT

Normally, the archetypeVersion argument is not required at this point. However, since the archetype has not yet been released, if omitted, the required version would not be known (or if this was later development, a previous release would be used instead). Releasing a project is explained in section 7.8 of this chapter.

You now have the template project laid out in the proficio-example directory. It will look very similar to the content of the archetype-resources directory you created earlier, now however, the content of the files will be populated with the values that you provided on the command line.