Update documentation regarding archetypeCatalog and archetype repositories
authorrfscholte <rfscholte@apache.org>
Sat, 1 Apr 2017 12:14:21 +0000 (14:14 +0200)
committerrfscholte <rfscholte@apache.org>
Sat, 1 Apr 2017 12:14:21 +0000 (14:14 +0200)
maven-archetype-plugin/src/it/mrm/settings.xml
maven-archetype-plugin/src/site/apt/archetype-repository.apt [new file with mode: 0644]
maven-archetype-plugin/src/site/apt/examples/generate-alternative-catalog.apt
maven-archetype-plugin/src/site/apt/specification/generate.apt
maven-archetype-plugin/src/site/apt/usage.apt
maven-archetype-plugin/src/site/site.xml

index 5913350..bcae17c 100644 (file)
@@ -1,5 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
 <!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
diff --git a/maven-archetype-plugin/src/site/apt/archetype-repository.apt b/maven-archetype-plugin/src/site/apt/archetype-repository.apt
new file mode 100644 (file)
index 0000000..a9a2c83
--- /dev/null
@@ -0,0 +1,81 @@
+ ------
+ Archetype Repository
+ ------
+ Robert Scholte
+ ------
+ 2017-04-01
+ ------
+
+~~ 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
+
+  As of Maven Archetype Plugin 3.0.0 the archetype resolution has changed. It is not possible anymore to specify
+  the repository via the commandline, but instead the repositories as already specified for Maven are used.
+  This means that also the mirrors and proxies are respected, as well as the authentication on repositories.
+
+  If you're not using a repository manager and the archetype is available at Maven Central, there's nothing you have to do.
+
+  If you're using a repository manager and the archetype is available via this manager, there's nothing you have to do.
+
+  Only in case of a third party archetype which is not managed by a repository you have to add a repository entry to your <<<settings.xml>>> once:
+
+---
+<settings>
+  <mirrors>
+    <mirror>
+      <id>mrm-maven-plugin</id>
+      <name>Mock Repository Manager</name>
+      <url>http://www.mycompany.com/maven-reporistory-manager</url>
+      <mirrorOf>*,!archetype</mirrorOf>
+    </mirror>
+  </mirrors>
+  
+  <!--
+  <servers>
+    <server>
+      <id>archetype</id>
+      <username/>
+      <password/>
+    </server>
+  </servers>
+  -->
+  
+  <profiles>
+    <profile>
+      <id>acme</id>
+      <repositories>
+        <repository>
+          <id>archetype</id>
+          <url>https://www.acme.com/repo</url>
+          <releases>
+            <enabled>true</enabled>
+            <checksumPolicy>fail</checksumPolicy>
+          </releases>
+          <snapshots>
+            <enabled>true</enabled>
+            <checksumPolicy>warn</checksumPolicy>
+          </snapshots>
+        </repository>
+      </repositories>
+    </profile>
+  </profiles>
+</settings>
+---
+
index 585e398..242eecf 100644 (file)
@@ -37,19 +37,13 @@ Generate project using an alternative catalog
 
    * <<<remote>>> to use the maven's remote catalog. No catalog is currently provided.
 
-   * <<<file://path/to/archetype-catalog.xml>>> to use a specific local catalog.
-     When the catalog file is named <<<archetype-catalog.xml>>>, it can be omitted.
-
-   * <<<http://url/to/archetype-catalog.xml>>> to use a specific remote catalog.
-     When the catalog file is named <<<archetype-catalog.xml>>>, it can be omitted.
-
    []
 
    The default value is <<<remote,local>>>. Thus the local catalog is shown
    just after the remote one.
 
 +--
-$ mvn archetype:generate -DarchetypeCatalog=http://cocoon.apache.org
+$ mvn archetype:generate
 [INFO] Scanning for projects...
 [INFO] Searching repository for plugin with prefix: 'archetype'.
 [INFO] ------------------------------------------------------------------------
index 41a605f..eae9c58 100644 (file)
@@ -68,22 +68,15 @@ What is done during the creation of a project?
     Archetype Plugin with all the needed values as system properties.
 
     * <<<archetypeCatalog>>> which specifies the catalog(s).
-       The valid catalogs are: <<<internal>>> (the default), <<<local>>>, <<<remote>>>,
-       <<<file://path>>>, <<<http://url>>>.
+       The valid catalogs are: <<<internal>>> (the default), <<<local>>>, <<<remote>>>.
 
        * <<<internal>>> uses an internal catalog
 
-       * <<<local>>> uses the <<<~/.m2/archetype-catalog.xml>>> file
+       * <<<local>>> uses the <<<archetype-catalog.xml>>> file from the local repository
 
-       * <<<remote>>> uses the <<<http://repo.maven.apache.org/maven2/archetype-catalog.xml>>>
+       * <<<remote>>> uses the <<<archetype-catalog.xml>>> from Maven Central, either direct or via a repository manager 
          file
 
-       * <<<file://path>>> uses the catalog file defined by path (or the
-         <<<archetype-catalog.xml>>> file located in path directory)
-
-       * <<<http://url>>> uses the catalog file defined by url (or the
-         <<<archetype-catalog.xml>>> file located in URL directory)
-
        []
 
     * <<<archetypeGroupId>>> specifies the groupId of the archetype to use
index 5651cd2..0e822df 100644 (file)
@@ -32,6 +32,8 @@
 Project creation
 
     Creating a project from an archetype involves three steps:
+    
+    * prepare repository reference
 
     * the selection of the archetype,
 
@@ -43,6 +45,12 @@ Project creation
 
 Usage
 
+   In general an archetype is coming from a remote repository. If that repository can
+   be reached via the setup of your Maven, you're ready to start. In cases where the
+   repository is not managed and you want to refer to it directly, you have to add the
+   repository to your <<<settings.xml>>>. Read the small set of instructions on the
+   {{{./archetype-repository.html}Archetype Repository}}-page.
+
    Calling <<<archetype:generate>>> the plugin will first ask to choose
    the archetype from the internal catalog. Just enter the number of the archetype.
 
index bf44526..b6ada8c 100644 (file)
@@ -39,6 +39,7 @@
     <menu name="Reference">
       <item name="Archetype Descriptor" href="../archetype-models/archetype-descriptor/archetype-descriptor.html"/>
       <item name="maven-archetype Packaging" href="../archetype-packaging/"/>
+      <item name="Archetype repository" href="/archetype-repository.html"/>
     </menu>
 
     <menu name="Examples">