| ------ |
| Archetype Catalog |
| ------ |
| Raphaël Piéroni |
| ------ |
| 2011-09-30 |
| ------ |
| |
| ~~ Licensed to the Apache Software Foundation (ASF) under one |
| ~~ or more contributor license agreements. See the NOTICE file |
| ~~ distributed with this work for additional information |
| ~~ regarding copyright ownership. The ASF licenses this file |
| ~~ to you under the Apache License, Version 2.0 (the |
| ~~ "License"); you may not use this file except in compliance |
| ~~ with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~ Unless required by applicable law or agreed to in writing, |
| ~~ software distributed under the License is distributed on an |
| ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~ KIND, either express or implied. See the License for the |
| ~~ specific language governing permissions and limitations |
| ~~ under the License. |
| |
| ~~ NOTE: For help with the syntax of this file, see: |
| ~~ http://maven.apache.org/doxia/references/apt-format.html |
| |
| |
| How does the Archetype Plugin know about archetypes? |
| |
| Knowledge about archetypes is stored in catalogs. |
| |
| The catalogs are xml files: see the {{{../../archetype-models/archetype-catalog/archetype-catalog.html}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. |