Maven Archetype Plugin – Plugin Documentation

Plugin Documentation

This report describes goals, parameters details, requirements and sample usage of this plugin.

Goals

Goals available for this plugin:

Goal Description

archetype:crawl Crawl a Maven repository (filesystem, not HTTP) and creates a catalog file.

Creates an archetype project from the current project.

This goal reads your source and resource files, the values of its parameters, and properties you specify in a .property file, and uses them to create a Maven archetype project using the maven-archetype packaging. If you build the resulting project, it will create the archetype. You can then use this archetype to create new projects that resemble the original.

The maven-archetype-plugin uses Velocity to expand template files, and this documentation talks about 'Velocity Properties', which are values substituted into Velocity templates. See The Velocity User's Guide for more information.

This goal modifies the text of the files of the current project to form the Velocity template files that make up the archetype.

GAV: The GAV values for the current project are replaced by properties: groupId, artifactId, and version. The user chooses new values for these when generating a project from the archetype.
package: All the files under one specified Java (or cognate) package are relocated to a project that the user chooses when generating a project. References to the class name are replaced by a property reference. For example, if the current project's sources are in the package org.apache.saltedpeanuts, then any example of the string org.apache.saltedpeanuts is replaced with the Velocity property reference ${packageName}. When the user generates a project, this is in turn replaced by his or her choice of a package.
custom properties: You may identify additional strings that should be replaced by parameters. To add custom properties, you must use the propertyFile parameter to specify a property file. See the documentation for propertyFile for the details.
integration tests: You may also specify a set of integration tests to be executed right after you create archetype from the project. Each test consists of a separate folder under src/it/projects folder and in there you specify archetype.properties, goal.txt and verify.groovy files. The archetype.properties file is the file used to generate a new project from the newly created archetype and the goal.txt a single-line file to specify the maven goal to invoke after generation of the test-project. Finally the verify.groovy is a groovy file that you can use to specify your assertions on the generated project.

Note that you may need to edit the results of this goal. This goal has no way to exclude unwanted files, or add copyright notices to the Velocity templates, or add more complex elements to the archetype metadata file.

This goal also generates a simple integration-test that exercises the generated archetype.

archetype:generate Generates a new project from an archetype, or updates the actual project if using a partial archetype. If the project is fully generated, it is generated in a directory corresponding to its artifactId. If the project is updated with a partial archetype, it is done in the current directory.

archetype:help Display help information on maven-archetype-plugin.
Call mvn archetype:help -Ddetail=true -Dgoal=<goal-name> to display parameter details.

archetype:integration-test

Execute the archetype integration tests, consisting in generating projects from the current archetype and optionally comparing generated projects with reference copy.

Each IT consists of a sub-directory in src/test/resources/projects containing:

a goal.txt file, containing a list of goals to run against the generated project (can be empty, content ignored before maven-archetype-plugin 2.1),
an archetype.properties file, containing properties for project generation,
an optional reference/ directory containing a reference copy of the expected project created from the IT.

To let the IT create a Maven module below some other Maven project (being generated from another archetype) one can additionally specify an optional archetype.pom.properties file in the parent directory, specifying the archetype's groupId, artifactId and version along with its archetype.properties file, containing properties for project generation. Both files are leveraged to create the parent project for this IT. Parent projects can be nested.

An example structure for such an integration test looks like this

integration test folder structure
File/Directory	Description
`src/test/resources/projects/it1`	Directory for integration test 1
`src/test/resources/projects/it1/archetype.pom.properties`	GAV for the archetype from which to generate the parent
`src/test/resources/projects/it1/archetype.properties`	All required properties for the archetype being specified by `archetype.pom.properties` on this level
`src/test/resources/projects/it1/child`	Directory for maven module within integration test 1 (this folder's name is not relevant)
`src/test/resources/projects/it1/child/goal.txt`	The file containing the list of goals to be executed against the generated project
`src/test/resources/projects/it1/child/archetype.properties`	All required properties for this project's archetype

Notice that it is expected to be run as part as of a build after the package phase and not directly as a goal from CLI.

archetype:jar Build a JAR from the current Archetype project.

archetype:update-local-catalog Updates the local catalog

System Requirements

The following specifies the minimum requirements to run this Maven plugin:

Maven	3.6.3
JDK	1.8

System Requirements History

The following specifies the minimum requirements to run this Maven plugin for historical versions:

Plugin Version	Maven	JDK
from 3.3.0 to 3.3.1	3.6.3	8
from 3.1.0 to 3.2.1	3.0	7
from 3.0.0 to 3.0.1	3.0	6
from 2.3 to 2.4	2.2.1	5
from 2.0 to 2.2	2.0.7	5
from 2.0-alpha-1 to 2.0-alpha-5	2.0.7	1.4
1.0-alpha-7	2.0	-
from 1.0-alpha-3 to 1.0-alpha-4	-	-

Usage

You should specify the version in your project's plugin configuration:

<project>
  ...
  <build>
    <!-- To define the plugin version in your parent POM -->
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-archetype-plugin</artifactId>
          <version>3.3.1</version>
        </plugin>
        ...
      </plugins>
    </pluginManagement>
    <!-- To use the plugin goals in your POM or parent POM -->
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-archetype-plugin</artifactId>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

For more information, see "Guide to Configuring Plug-ins"