Fork me on GitHub
Built by Maven

How does the Archetype Plugin know about archetypes?

Knowledge about archetypes is stored in catalogs.

The catalogs are xml files: see the reference documentation.

The Archetype Plugin comes bundled with an internal catalog. This one is used by default.

The Archetype Plugin can use catalogs from local filesystem and from HTTP connections.

Catalog file explained

A catalog is an xml file with such content:

<?xml version="1.0" encoding="UTF-8"?>
<archetype-catalog  xmlns="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-catalog/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/plugins/maven-archetype-plugin/archetype-catalog/1.0.0 http://maven.apache.org/xsd/archetype-catalog-1.0.0.xsd">
  <archetypes>
    <archetype>
[1]    <groupId>org.appfuse.archetypes</groupId>
[2]    <artifactId>appfuse-basic-jsf</artifactId>
[3]    <version>2.0</version>
[4]    <repository>http://static.appfuse.org/releases</repository>
[5]    <description>AppFuse archetype for creating a web application with Hibernate, Spring and JSF</description>
    </archetype>
    ...
  </archetypes>
</archetype-catalog>
  1. The groupId of the archetype. REQUIRED
  2. The artifactId of the archetype. REQUIRED
  3. The version of the archetype. RELEASE is a valid version. REQUIRED
  4. The repository where to find the archetype. OPTIONAL. When omitted, the archetype is searched for in the repository where the catalog comes from.
  5. The description of the archetype. OPTIONAL

Archetype selection explained

During the creation of a project from an archetype, the Archetype Plugin asks the user to choose an archetype from a list containing the archetypes from each of the provided catalogs (yes, there may be many).

For each archetype in the list, the Archetype Plugin shows a line like:

1: internal -> appfuse-basic-jsf (AppFuse archetype for creating a web application with Hibernate, Spring and JSF)
  • 1: The index of the archetype in the aggregated list (starting from 1).
  • internal The name of the catalog where the archetype originates from.
  • appfuse-basic-jsf The artifactId of the archetype.
  • (AppFuse archetype...) The description of the archetype as found in the catalog.

Creating a catalog file

At the end of the create-from-project behaviour, the Archetype Plugin installs/deploys the archetype, and updates the local/remote catalog.

The crawl-repository goal is used to create a catalog file by crawling a Maven repository located in the filesystem.

Location of catalog files

The Archetype Plugin knows by default about its internal catalog. It also knows about the local and remote catalogs.

local represents the ~/.m2/archetype-catalog.xml catalog file.

remote represents the https://repo.maven.apache.org/maven2/archetype-catalog.xml catalog file.

The Archetype Plugin can also read catalogs from filesystem/HTTP by providing the path/URL of a catalog file or of a directory containing an archetype-catalog.xml file.